NPC Interaction

{
  // Required
  text: string;              // Player's message (max 2,000 chars)
  entityMindId: string;      // Entity Mind ID (provides name, personality, knowledge filters)
  playerId: string;          // Your player identifier (max 255 chars; used for rate limiting,
                             // memory, and conversation tracking)
 
  // Optional
  context?: {
    location?: string;           // Current location name
    locationDetails?: string;    // Location description
    timeOfDay?: string;          // "morning", "evening", etc.
    weather?: string;            // Weather conditions
    atmosphere?: string;         // Scene mood ("peaceful", "tense", ...)
    situation?: string;          // Interaction type ("shopping", "combat", ...)
    npcMood?: string;            // NPC's current mood
    npcActivity?: string;        // What the NPC is doing
    playerAppearance?: string;   // How player looks to NPC
    playerReputation?: string;   // How the NPC views the player
    playerVisibleItems?: string[]; // Notable items the player carries
    nearbyCharacters?: string[]; // Other characters present
    nearbyObjects?: string[];    // Notable objects present
    recentEvents?: string[];     // Recent world events
    custom?: string;             // Freeform game-specific context (max 500 chars)
  };
 
  memory?: {
    retrieve?: boolean;      // Retrieve past memories for this player (default: false)
  };
 
  activeKnowledgeTags?: string[];  // Narrow which lore the NPC can reference (by tag name).
                                   // Max 50 tags, 100 chars each. Can only restrict the
                                   // Entity Mind's configured tags, never expand them.
 
  conversationHistory?: Array<{    // Max 50 messages, 10,000 chars per message.
    role: "user" | "assistant";    // The server keeps the most recent messages up to the
    content: string;               // project's max session length.
  }>;
}

{
  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)
  };
}

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": {}
}