API Documentation

Concepts

• Persona — a reusable character (Hossein, the IT manager). Has its own core knowledge files.
• Scenario — a reusable situation (a murder case, an interview). Has its own knowledge files.
• Agent — a composition of persona + scenario. Has the API token and the chat endpoint.

Authentication

Admin endpoints require the admin token. The per-agent chat endpoint accepts either the agent's token or the admin token.

Authorization: Bearer <token>
# or
X-API-Token: <token>
# or
?token=<token>

POST /api/agents/{id}/chat

Chat with an agent. Returns JSON, or SSE stream when stream: true.

curl -X POST https://your-host/api/agents/1/chat \
  -H "Authorization: Bearer YOUR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"سلام","stream":false}'

Python:

import httpx
r = httpx.post(
  "https://your-host/api/agents/1/chat",
  headers={"Authorization": "Bearer YOUR_AGENT_TOKEN"},
  json={"prompt": "Hello", "stream": False},
  timeout=300,
)
print(r.json()["response"])

Streaming (SSE) — each event is a JSON chunk:

data: {"response":"Hel","done":false}
data: {"response":"lo","done":false}
data: {"response":"","done":true,"eval_count":12}

PHP (non-streaming):

$ch = curl_init("https://your-host/api/agents/1/chat");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_AGENT_TOKEN",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode(["prompt" => "Hello", "stream" => false]),
]);
$resp = json_decode(curl_exec($ch), true);
echo $resp["response"];

Admin endpoints

All require the admin token.

Personas
  GET    /api/personas
  POST   /api/personas
  GET    /api/personas/{id}
  PATCH  /api/personas/{id}
  DELETE /api/personas/{id}                    (blocked if used by agents)
  POST   /api/personas/{id}/files              (multipart upload)
  GET    /api/personas/{id}/files
  DELETE /api/personas/{id}/files/{file_id}

Scenarios
  GET    /api/scenarios
  POST   /api/scenarios
  GET    /api/scenarios/{id}
  PATCH  /api/scenarios/{id}
  DELETE /api/scenarios/{id}
  POST   /api/scenarios/{id}/files
  GET    /api/scenarios/{id}/files
  DELETE /api/scenarios/{id}/files/{file_id}

Agents
  GET    /api/agents
  POST   /api/agents                           body: {name, persona_id, scenario_id?, ...}
  GET    /api/agents/{id}
  PATCH  /api/agents/{id}
  DELETE /api/agents/{id}
  POST   /api/agents/{id}/regenerate-token
  POST   /api/agents/{id}/chat                 (uses agent token, not admin)

Full schema at /docs (Swagger).