API Quickstart

Get an NPC response from the LoreMind API in one request. POST /npc/interact is the stable production endpoint — the same call your game server makes at runtime.

Prerequisites

A LoreMind project with lore and at least one Entity Mind — the Quick Start walks through this in the browser
A Server API Key (sk_server_*): create one in Projects → your project → API Keys
Your Entity Mind ID: copy it from Entity Minds

Make the Request


curl -X POST https://loremind.peekgames.dev/api/loremind/v1/npc/interact \
  -H "Authorization: Bearer YOUR_SERVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, what is your name?",
    "entityMindId": "YOUR_ENTITY_MIND_ID",
    "playerId": "test_player_001"
  }'

All three fields are required: text is the player’s message (max 2,000 characters), entityMindId selects the NPC, and playerId is any stable identifier for the player — it’s used for rate limiting, memory, and conversation tracking.

Response Shape


{
  success: true;
  response: string;          // NPC's response text
  character: string;         // Character name
 
  metadata: {
    memoryCheckpoint?: boolean;   // True when session hit max length and memories were auto-saved
    warnings?: string[];          // Non-fatal notices (e.g. ignored knowledge tags)
  };
}

Add Context and Memory

NPCs respond to the scene you set. The same endpoint accepts optional context, memory, and activeKnowledgeTags blocks:


curl -X POST https://loremind.peekgames.dev/api/loremind/v1/npc/interact \
  -H "Authorization: Bearer sk_server_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "What can you tell me about the dragon?",
    "entityMindId": "em_abc123",
    "playerId": "steam_76561198012345678",
    "context": {
      "location": "Blacksmith Shop",
      "timeOfDay": "evening",
      "weather": "rainy"
    },
    "memory": {
      "retrieve": true
    },
    "activeKnowledgeTags": ["dragon-war", "village-history"]
  }'


{
  "success": true,
  "response": "The dragon? Aye, I've heard the rumors. Spotted near the old watchtower, they say. If you're thinking of going after it, you'll need better steel than what you're carrying.",
  "character": "Grom the Blacksmith",
  "metadata": {}
}

See Runtime Context for every context field and its limits, and Long-Term Memory for how memory works.

If It Fails

Status	Error	Fix
401	`Invalid API key`	The key is missing, malformed, or revoked — check you copied the full `sk_server_*` key
403	`Invalid authentication`	You used an Editor Key — this endpoint requires a Server Key
402	`Insufficient credits`	Balance too low — see Credits & Billing
404	`Entity Mind not found`	Check the `entityMindId` against the dashboard

The full error table is in the API Reference.

Next Steps

Server Integration - Production patterns for Nakama, PlayFab, Node.js, and Mirror
Authentication - Key types, storage, and player identity
Long-Term Memory - Make NPCs remember players
API Reference - Full request and response schemas