Skip to Content
Loremind Platform APIAPI Reference

API Reference

Base URL: https://loremind.peekgames.dev/api/loremind/v1

Authentication

LoreMind uses API keys for server-to-server authentication. Keys are created in Projects  under your project’s API Keys section.

Key TypePrefixUse Case
Server Keysk_server_Production server integration (NPC interactions)
Editor Keysk_editor_Game engine editor tooling only (Entity Mind dropdowns)

Include your API key in the Authorization header:

Authorization: Bearer sk_server_your_key_here

NPC Interaction

POST /npc/interact

Generate an NPC response to player input. This is the primary endpoint for NPC interactions.

Authentication: Server Key (sk_server_*)

Request Body

{
  // 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)
  };
 
  conversationHistory?: Array<{
    role: "user" | "assistant";
    content: string;
  }>;
}

Response

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

Example Request

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

Example Response

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

Error Responses

StatusErrorDescription
400Missing or empty textNo player message provided
400Text too longMessage exceeds 10,000 characters
400Missing entityMindIdentityMindId is required
401Invalid API keyAPI key is missing, malformed, or revoked
404Entity Mind not foundInvalid entityMindId
402Insufficient creditsTeam balance too low
403Editor API keys cannot be usedUse Server Key, not Editor Key
404Project not foundInvalid project or key
429Rate limit exceededToo many requests (see Retry-After header)
503Generation failedLLM error (retry)

Entity Minds

GET /lore/minds

List all Entity Minds for a project.

Authentication: Editor Key (sk_editor_*) or Dashboard session

Query Parameters:

  • projectId (required for dashboard users)

Response

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

Example (Game Engine Editor)

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

Tags

GET /lore/tags

List all tags for a project.

Authentication: Editor Key (sk_editor_*) or Dashboard session

Query Parameters:

  • projectId (required for dashboard users)

Response

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

Rate Limits

Rate limits are configurable per-project in Dashboard → Project Settings → Rate Limits.

When playerId is provided, rate limits apply per-player. Without playerId, limits apply per-project.

Response Headers

When rate limited, the API returns:

  • Retry-After: Seconds until retry (included with 429 responses)

Credits

Credits are usage-based with no expiration. See Billing for pricing. Monitor your balance and usage in the dashboard .

When credits run low, requests return 402 Insufficient credits:

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

SDK Integration

Game engine SDKs handle API calls automatically during editor testing. For production, you call the API from your backend - see Server Integration.

// 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!");
Last updated on
Server IntegrationLong-Term Memory