API Reference

The ForbocAI API provides RESTful endpoints for the Multi-Round Protocol — the API is the “Mind” that orchestrates all npc decisions, while the SDK is the “Body” that executes them locally. Endpoints are protocol verbs, not CRUD operations. The primary runtime route is /npcs/{npcId}/process (atomic continuation), and compatibility phase routes remain available: /npcs/{npcId}/directive, /npcs/{npcId}/context, and /npcs/{npcId}/verdict.

Base URL

Production: https://api.forboc.ai
Local Dev:  http://localhost:8080

Authentication

API requests require a bearer token in the Authorization header:

$
curl -X POST https://api.forboc.ai/npcs/npc_demo/directive \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"observation":"Player entered tavern","npcState":{"mood":"neutral"}}'

POST /npcs/{npcId}/verdict returns signature in the response body. Use it as the canonical validation proof; if your backend needs an explicit header for downstream checks, forward it as X-Forboc-Signature.

API Categories

Response Format

Multi-round protocol responses use domain-specific shapes. Key examples:

Directive Response (Step 2 — API tells SDK what to recall):

1
{
2
  "memoryRecall": { "query": "previous encounters with player", "limit": 5, "threshold": 0.5 }
3
}

Context Response (Step 4 — API sends SLM prompt):

1
{
2
  "prompt": "You are Kira, a cautious merchant...\n[Memories]\n...\nRespond to: Player attacked you.",
3
  "constraints": { "maxTokens": 256, "temperature": 0.7 }
4
}

Verdict Response (Step 6 — API validates + instructs):

1
{
2
  "valid": true,
3
  "dialogue": "You'll pay for that, scoundrel!",
4
  "action": { "type": "ATTACK", "target": "player_1" },
5
  "signature": "v2_hmac_...",
6
  "memoryStore": [{ "text": "Player attacked me", "type": "experience", "importance": 0.9 }],
7
  "stateDelta": { "mood": "hostile", "trust": -0.5 }
8
}

Error Handling

Errors return appropriate HTTP status codes with details:

1
{
2
  "error": {
3
    "code": "ITEM_NOT_IN_INVENTORY",
4
    "message": "NPC does not possess the item 'legendary_sword'",
5
    "details": {
6
      "item": "legendary_sword",
7
      "npcInventory": ["rusty_key", "healing_potion"]
8
    }
9
  }
10
}

Rate Limits

Note: Billing tiers are planned. The current API uses per-key rate limiting (100 requests/60s). The tiers below reflect the intended production model.

SDKs

Official SDK libraries wrap this API for common platforms:

$
# JavaScript/TypeScript
$
npm install @forbocai/core
$
$
# Unreal Engine — see the UE SDK tab for C++ plugin installation