> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.forboc.ai/api-reference/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.forboc.ai/_mcp/server. # API Reference ## API Docs - ForbocAI SDK API > Status [Health check](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/status/get-status.md) - ForbocAI SDK API > Cortex [List available models](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/cortex/list-models.md) - ForbocAI SDK API > Cortex [Initialize Cortex instance](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/cortex/init-cortex.md) - ForbocAI SDK API > Cortex [Generate completion (deprecated)](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/cortex/generate-completion.md) - ForbocAI SDK API > NP Cs [Atomic protocol step](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/np-cs/process-npc-step.md) - ForbocAI SDK API > NP Cs [Get directive (Step 2)](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/np-cs/get-npc-directive.md) - ForbocAI SDK API > NP Cs [Get context / SLM prompt (Step 4)](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/np-cs/get-npc-context.md) - ForbocAI SDK API > NP Cs [Get verdict (Step 7)](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/np-cs/get-npc-verdict.md) - ForbocAI SDK API > Memory [List memories](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/memory/list-memories.md) - ForbocAI SDK API > Memory [Confirm memory storage](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/memory/store-memory.md) - ForbocAI SDK API > Memory [Report recall results](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/memory/recall-memories.md) - ForbocAI SDK API > Memory [Clear memories](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/memory/clear-memories.md) - ForbocAI SDK API > Bridge [Validate action](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/bridge/validate-action.md) - ForbocAI SDK API > Bridge [Validate action for NPC](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/bridge/validate-action-for-npc.md) - ForbocAI SDK API > Bridge [List bridge rules](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/bridge/list-bridge-rules.md) - ForbocAI SDK API > Rules [List rulesets](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/rules/list-rulesets.md) - ForbocAI SDK API > Rules [Register ruleset](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/rules/register-ruleset.md) - ForbocAI SDK API > Rules [Delete ruleset](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/rules/delete-ruleset.md) - ForbocAI SDK API > Rules [List bridge presets](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/rules/list-bridge-presets.md) - ForbocAI SDK API > Rules [Create ruleset from preset](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/rules/create-ruleset-from-preset.md) - ForbocAI SDK API > Soul [Export Soul (Phase 1)](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/soul/export-soul.md) - ForbocAI SDK API > Soul [Confirm Soul Export (Phase 2)](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/soul/confirm-soul-export.md) - ForbocAI SDK API > Soul [Import Soul (Phase 1)](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/soul/import-soul.md) - ForbocAI SDK API > Soul [Confirm Soul Import (Phase 2)](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/soul/confirm-soul-import.md) - ForbocAI SDK API > Soul [Verify Soul](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/soul/verify-soul-by-tx-id.md) - ForbocAI SDK API > Soul [Get Soul by TXID](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/soul/get-soul-by-tx-id.md) - ForbocAI SDK API > Soul [List Souls](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/soul/list-souls.md) - ForbocAI SDK API > Ghost [Run Ghost Session](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/ghost/run-ghost-agent.md) - ForbocAI SDK API > Ghost [Get session status](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/ghost/get-ghost-status.md) - ForbocAI SDK API > Ghost [Get session results](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/ghost/get-ghost-results.md) - ForbocAI SDK API > Ghost [Stop Ghost session](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/ghost/stop-ghost-session.md) - ForbocAI SDK API > Ghost [Get Ghost history](https://docs.forboc.ai/api-reference/endpoints/forboc-ai-sdk-api/ghost/get-ghost-history.md) ## OpenAPI Specification The raw OpenAPI 3.1 specification for this API is available at: - [OpenAPI JSON](https://docs.forboc.ai/api-reference/openapi.json) - [OpenAPI YAML](https://docs.forboc.ai/api-reference/openapi.yaml) > **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.forboc.ai/api-reference/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.forboc.ai/_mcp/server. # API Reference ÁPI\_Réference // Éndpoint\_Dócs ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ 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 Báse\_ÚRL // Cónnect ``` Production: https://api.forboc.ai Local Dev: http://localhost:8080 ``` --- ## Authentication Áuth\_Módule // Béarer\_Tóken API requests require a bearer token in the Authorization header: ```bash 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 Módulátion\_Máp // Sýstem\_Óverview #### Cortex Initialize and manage local SLM inference engines #### NPCs (Multi-Round Protocol) Register npcs and execute the multi-round protocol (`/process` primary; directive/context/verdict compatibility) #### Memory API-directed memory recall and storage (local vector DB) #### Bridge Standalone action validation against game rules #### Soul Export and import portable npc state #### Ghost Run automated QA testing with headless npcs #### Rules Register directive rule sets for game-agnostic logic #### Status Health check and API version info ᛭ ᛫ ᛬ ᛫ ᛭ --- ## Response Format Respónse\_Schéma // JSÓN\_Fórmat Multi-round protocol responses use domain-specific shapes. Key examples: **Directive Response** (Step 2 — API tells SDK what to recall): ```json { "memoryRecall": { "query": "previous encounters with player", "limit": 5, "threshold": 0.5 } } ``` **Context Response** (Step 4 — API sends SLM prompt): ```json { "prompt": "You are Kira, a cautious merchant...\n[Memories]\n...\nRespond to: Player attacked you.", "constraints": { "maxTokens": 256, "temperature": 0.7 } } ``` **Verdict Response** (Step 6 — API validates + instructs): ```json { "valid": true, "dialogue": "You'll pay for that, scoundrel!", "action": { "type": "ATTACK", "target": "player_1" }, "signature": "v2_hmac_...", "memoryStore": [{ "text": "Player attacked me", "type": "experience", "importance": 0.9 }], "stateDelta": { "mood": "hostile", "trust": -0.5 } } ``` --- ## Error Handling Érror\_Códes // Fáulт\_Státus Errors return appropriate HTTP status codes with details: ```json { "error": { "code": "ITEM_NOT_IN_INVENTORY", "message": "NPC does not possess the item 'legendary_sword'", "details": { "item": "legendary_sword", "npcInventory": ["rusty_key", "healing_potion"] } } } ``` | Status Code | Description | | ----------- | ---------------------------------------- | | `200` | Success | | `403` | Forbidden | | `400` | Bad Request (invalid parameters) | | `401` | Unauthorized (missing/invalid token) | | `404` | Not Found | | `422` | Unprocessable Entity (validation failed) | | `500` | Internal Server Error | --- ## Rate Limits Ráte\_Límit // Thróttling > **Note:** Billing tiers are planned. The current API uses per-key rate limiting (100 requests/60s). The tiers below reflect the intended production model. | Tier | Requests/minute | Concurrent NPCs | | ---------- | --------------- | --------------- | | Free | 60 | 3 | | Pro | 600 | 25 | | Enterprise | Unlimited | Unlimited | --- ## SDKs SDK\_Lïbraries // Instáll Official SDK libraries wrap this API for common platforms: ```bash # JavaScript/TypeScript npm install @forbocai/core # Unreal Engine — see the UE SDK tab for C++ plugin installation ``` ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ