API Reference

Authorization: Bearer sk_server_your_key_here

{
  // Required
  text: string;              // Player's message (max 1000 chars)
  character: {
    name: string;            // NPC name for response attribution
    personality?: string;    // Personality description
    role?: string;           // NPC's role/occupation
    speakingStyle?: string;  // How the NPC speaks
  };
 
  // Recommended
  entityMindId?: string;     // Entity Mind ID (provides personality, knowledge filters)
  playerId?: string;         // Your player identifier (enables memory, 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: 150)
    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
 
    costBreakdown: {
      llm: number;                    // LLM generation cost
      loreSearch: number;             // Embedding + vector search cost
      memory?: {                      // Only if memory enabled
        retrieval: number;
        storage: number;
        total: number;
      };
    };
 
    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;
    };
  };
}

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",
    "character": {
      "name": "Grom the Blacksmith"
    },
    "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": "gemini-1.5-flash",
    "promptTokens": 847,
    "completionTokens": 52,
    "finishReason": "stop",
    "creditsUsed": 0.45,
    "creditsRemaining": 9543.20,
    "costBreakdown": {
      "llm": 0.38,
      "loreSearch": 0.05,
      "memory": {
        "retrieval": 0.01,
        "storage": 0.01,
        "total": 0.02
      }
    },
    "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;
}

{
  device_id: string;    // Unity SystemInfo.deviceUniqueIdentifier
  platform?: string;    // "windows", "mac", "android", "ios", etc.
  sdk_version?: string; // SDK version
}

{
  session_token: string;   // JWT for subsequent requests
  expires_in: 1800;        // 30 minutes
  project_id: string;
  project_name: string;
}

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!",
    "character": { "name": "Guard" },
    "dryRun": true
  }'

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

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

// Direct Client mode - SDK handles auth automatically
var npc = GetComponent<LoreMindNPC>();
var response = await npc.RespondAsync("Hello!");