API Reference

Authorization: Bearer sk_server_your_key_here

{
  // Required
  text: string;              // Player's message (max 10,000 chars)
  entityMindId: string;      // Entity Mind ID (provides name, personality, knowledge filters)
 
  // Required for memory and per-player rate limits
  playerId?: string;         // Your player identifier (required for memory features and per-player rate limits)
 
  // Optional
  context?: {
    location?: string;           // Current location name
    locationDetails?: string;    // Location description
    timeOfDay?: string;          // "morning", "evening", etc.
    weather?: string;            // Weather conditions
    npcMood?: string;            // NPC's current mood
    playerAppearance?: string;   // How player looks to NPC
    nearbyCharacters?: string[]; // Other characters present
    recentEvents?: string[];     // Recent world events
  };
 
  memory?: {
    retrieve?: boolean;      // Retrieve past memories for this player (default: false)
  };
 
  options?: {
    topK?: number;           // Max lore results (default: 5, max: 10)
    maxTokens?: number;      // Max response tokens (default varies by verbosity: terse=80, balanced=200, verbose=400)
    temperature?: number;    // LLM temperature (default: 0.7)
    responseStyle?: "concise" | "detailed" | "conversational";
    skipSearch?: boolean;    // Skip lore search (default: false)
  };
 
  conversationHistory?: Array<{
    role: "user" | "assistant";
    content: string;
  }>;
 
  dryRun?: boolean;          // Return cost estimate without generating
}

{
  success: true;
  response: string;          // NPC's response text
  character: string;         // Character name
 
  metadata: {
    model: string;                    // LLM model used
    promptTokens: number;             // Input tokens
    completionTokens: number;         // Output tokens
    finishReason: "stop" | "length" | "content_filter" | "error";
 
    creditsUsed: number;              // Credits consumed
    creditsRemaining: number;         // Team balance after
 
    usedFallback: boolean;            // True if fallback LLM was used
    loreChunksUsed: number;           // Lore context chunks retrieved
    memoriesRetrieved: number;        // Past memories used
    memoriesStored: number;           // New memories created
 
    memoryCheckpoint?: boolean;       // True when session hit max length
 
    latency: {
      searchMs: number;
      llmMs: number;
      totalMs: number;
    };
 
    costBreakdown?: {
      search: number;           // Search/retrieval credits
      generation: number;       // LLM generation credits
      memory?: number;          // Memory operations credits (only present when memory operations occur)
    };
  };
}

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
    }
  }'

{
  "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": {
    "model": "llm-model",
    "promptTokens": 847,
    "completionTokens": 52,
    "finishReason": "stop",
    "creditsUsed": 0.45,
    "creditsRemaining": 9543.20,
    "loreChunksUsed": 3,
    "memoriesRetrieved": 2,
    "memoriesStored": 1,
    "latency": {
      "searchMs": 145,
      "llmMs": 1523,
      "totalMs": 1823
    }
  }
}

{
  minds: Array<{
    id: string;
    entityName: string;
    personality: string;
    backstory: string | null;
    backstorySummary: string | null;
    role: string | null;
    speakingStyle: string | null;
    hints: string[];
    restrictions: string[];
    locationId: string | null;
    location: { id: string; name: string } | null;
    knowledgeTags: string[];
    knowledgeDescription: string;
    computedFilter: object;
    responseConfig: object;
    buildCreditsUsed: number;
    interactionCount: number;
    relationshipCount: number;
    createdAt: string;
    updatedAt: string;
  }>;
}

curl https://loremind.peekgames.dev/api/loremind/v1/lore/minds \
  -H "Authorization: Bearer sk_editor_your_key"

{
  success: true;
  tags: Array<{
    id: string;
    name: string;
    color: string | null;
    isDefault: boolean;
    documentCount: number;
  }>;
  defaultTags: Array<{ id: string; name: string; color: string | null; documentCount: number }>;
  customTags: Array<{ id: string; name: string; color: string | null; documentCount: number }>;
  totalCount: number;
}

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": "Hello!",
    "entityMindId": "em_guard",
    "dryRun": true
  }'

{
  "dryRun": true,
  "estimate": {
    "credits": 0.42
  }
}

{
  "error": "Insufficient credits",
  "message": "This request requires approximately 0.45 credits. Current balance: 0.12.",
  "creditsNeeded": 0.45,
  "credits": 0.12
}

// In Editor: SDK uses Server API Key from Control Panel
// In Production: SDK routes through your backend URL
var npc = GetComponent<LoreMindNPC>();
var response = await npc.RespondAsync("Hello!");