AbraTabia AI Storyteller Chat API Reference
api.php/chat, does nearly all the work for all three bot types. This page documents every request field, every response field, the action signals, and the supporting endpoints for knowledge, memory, and crawling. If you have not installed the server yet, start with getting started.
Authentication and Request Format
All endpoints are POST with a JSON body. Send your key in the X-API-Key header, or as an apiKey field in the body. Paths use path info, and if your server does not support that, api.php?action=chat works the same as api.php/chat.
curl -X POST https://yourserver.com/api.php/chat \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{"chatbotID": "my-storyteller", "prompt": "I push open the tavern door.", "convoID": ""}'POST api.php/chat: Request Fields
Three fields carry a basic conversation, everything else is optional or gamehost-specific.
| Field | Notes |
|---|---|
chatbotID | Required. The bot ID from the admin area. |
prompt | Required. The user or player message. |
convoID | Blank starts a new conversation, then echo back the returned value on every following message. |
userInfo | Optional object stored with the conversation. Its fname value is told to the bot, so the narrator can use the player's name. |
userKnowledgeBase | Optional per-user memory tag. Setting it enables long-term memory recall and saving for that player. See knowledge base and memory. |
passedRules | Optional extra rules string appended for this request only, useful for temporary constraints like "the player is poisoned this scene". |
gameRules | Gamehost only. The rules of your game as text. |
actionsList | Gamehost only. Object of {"actionName": "when to fire it"} custom actions. |
numPlayers | Gamehost only. Required on the first message of a new game, 1 to 10. |
player | Gamehost only. Which player number is talking. |
startData | Gamehost only. That player's secret setup info during pre-game. |
playerData | Gamehost only. That player's submission for the current turn. |
POST api.php/chat: Response Fields
| Field | Notes |
|---|---|
message | The bot's reply text. |
action | Blank, or an action word your UI can react to (see below). |
convoID | The conversation ID to send with the next message. |
error | Blank on success. |
notice | Only present when a non-fatal problem occurred, like a failed knowledge lookup. The reply still came back, but you may want to log it. |
billing | Rough token usage for the request, handy for cost tracking per session. |
playerData | Gamehost only. Submissions received for the current turn. |
currentTurn | Gamehost only. -1 during pre-game setup, then 0 and up. |
Action Signals
Bots return an action field alongside each message so your UI can react without parsing the prose:
| Bot type | Actions |
|---|---|
| Storyteller | choice (a real decision point), chapter (scene break), encounter (someone or something important appeared), cleanup (history was compacted). |
| Assistant | angry (the user is frustrated), cleanup. |
| Gamehost | Whatever you define in actionsList. |
How to use the storyteller actions well is covered in the storyteller bots guide, and the gamehost turn flow in the gamehost guide.
POST api.php/knowledge/add
Store text in the knowledge base. Long text is chunked automatically, and unchanged chunks are skipped for free on re-submits, so pushing the same document twice costs nothing.
| Field | Notes |
|---|---|
data | Required. The text to store. |
tag | Required. Which collection to store it in. |
name, title | Optional labels for managing content later. |
POST api.php/knowledge/search
Search the knowledge base directly, useful for debugging retrieval or building your own lookups.
| Field | Notes |
|---|---|
prompt | Required. The search text. |
tag | Optional. Blank searches everything. |
numResults | Optional. How many scored matches to return. |
POST api.php/memory/add
Store a user memory directly, bypassing the automatic after-response saving. Fields: data (the memory text) and tag (the user's memory tag).
POST api.php/crawl
Crawl a website into the knowledge base. This endpoint also requires the admin password in the X-Admin-Password header, since a crawl is an administrative action that spends embedding credits.
| Field | Notes |
|---|---|
url | Required. Where to start crawling. Same-domain pages only. |
tag | Optional. Defaults to the domain. |
maxPages | Optional. Up to 200. |
One endpoint carries the whole conversation: send chatbotID, prompt, and convoID, get back message, action, and the next convoID. Add userKnowledgeBase for per-player memory, the gamehost fields for multiplayer, and the knowledge endpoints to keep your lore current.