HTTP API
The routes of the app's own API, how to authenticate, and what the MCP endpoint is for.
Curltale AI exposes three things over HTTP:
| What | Path | Authentication | Use it for |
|---|---|---|---|
| The MCP endpoint | /mcp | Bearer token | Agents and tools. This is the integration surface: see Connect an agent and The tools. |
| The app's own API | /api/... (admin routes under /api/admin, the library under /api/library) | Session cookie | The web UI. You can script against it, but it is not a versioned contract: before 1.0, minor versions may change it. |
| Health | GET /api/health | None | Load balancers and monitoring. Returns {"ok": true}. |
The Excel template and exports are plain downloads: GET /api/template.xlsx and GET /api/export.xlsx?version=published (or draft).
Sign in from a script#
curl -c jar.txt -H 'content-type: application/json' \
-d '{"username":"admin","password":"..."}' https://<your-host>/api/login
curl -b jar.txt https://<your-host>/api/me
curl -b jar.txt https://<your-host>/api/entitiesThe cookie lasts SESSION_HOURS (default 12). The same rate limits and access rules apply as in the UI. A user's entitlements decide what the data routes return.
Routes#
Grouped by what they do. {x} is a path parameter. Roles are those of Users, roles and access; admin routes need the admin role.
Session and status#
| Route | Purpose |
|---|---|
POST /api/login, POST /api/logout | Start and end a session. |
GET /api/me, POST /api/me/password | Who you are (roles, entitlements) and change your password. |
GET /api/status | What the app has switched on (for example whether the library is enabled). |
GET /api/health | Health, without signing in. |
The model#
| Route | Purpose |
|---|---|
GET /api/entities, GET /api/entities/{key}, GET /api/entities/{key}/documents | List entities, read one with its fields, and list the related documents you may read. |
GET /api/relationships, GET /api/examples, GET /api/graph, GET /api/path | Relationships, query examples, the entity graph and join paths. |
GET /api/search | Hybrid search over the model. |
POST/PATCH/DELETE /api/entities/{key}, PUT/DELETE /api/entities/{key}/fields/{col} | Edit the draft (modeller). |
PUT/DELETE /api/relationships/{rid}, GET /api/relationships/next-id | Edit relationships in the draft. |
PUT/DELETE /api/examples/{kid} | Edit query examples in the draft. |
Versions and Excel#
| Route | Purpose |
|---|---|
POST /api/versions/draft, DELETE /api/versions/draft | Start or discard the draft. |
GET /api/versions/validate, GET /api/versions/diff | Validate the draft; compare it with the published version. |
POST /api/versions/publish, GET /api/versions/publish/status | Publish (publisher) and follow the progress. |
GET /api/audit | The audit log of model changes. |
GET /api/template.xlsx, GET /api/export.xlsx | Download the blank template or an export. |
POST /api/admin/import/excel | Upload a workbook (checked first; dry_run=false creates the draft). |
Data#
| Route | Purpose |
|---|---|
GET /api/data/status, GET /api/data/tables, GET /api/data/table, GET /api/data/row | Which database is in use, its tables, rows and one row. |
POST /api/data/sql | One read-only statement under your entitlements. |
GET /api/data/conformance | The model check. |
POST /api/admin/data/build | Build or rebuild the demo database (admin). |
Assistant#
| Route | Purpose |
|---|---|
POST /api/alfred | Ask Alfred a question (streamed). |
Administration#
| Route | Purpose |
|---|---|
GET/POST /api/admin/users, PUT /api/admin/users/{username}/roles, PUT /api/admin/users/{username}/entitlements | Users, roles and entitlements. |
GET/POST /api/admin/tokens, PUT /api/admin/tokens/{tid}/entitlements, DELETE /api/admin/tokens/{tid} | MCP tokens. |
GET/POST /api/admin/connectors, PUT/DELETE /api/admin/connectors/{cid} | Connectors. |
POST /api/admin/connectors/{cid}/test, /introspect, /activate, /generate-draft; POST /api/admin/connectors/deactivate; GET /api/admin/connectors/{cid}/structure | The connector workflow. |
GET/PUT /api/admin/settings, DELETE /api/admin/settings/{name} | Settings. |
POST /api/admin/llm/test, POST /api/admin/storage/test | Test the AI endpoint and the storage. |
POST /api/admin/reindex, GET /api/admin/questions | Rebuild the search index; questions nobody could answer. |
POST /api/admin/reset-ontology, GET /api/admin/backups, GET /api/admin/backups/{name} | Empty the ontology and download the Excel backups. |
GET /api/admin/audit, GET /api/admin/activity/summary, /sessions, /sessions/{sid}, /events/{eid}/result | The audit trail and the activity log. |
The library#
All under /api/library. {ref} is a collection's id or slug.
| Route | Purpose |
|---|---|
GET/POST /collections, PATCH/DELETE /collections/{ref} | Collections. |
GET/PUT /collections/{ref}/grants, DELETE /collections/{ref}/grants/{gid}, POST /collections/{ref}/self-grant | Access, including an admin granting themselves access (logged). |
GET/POST /collections/{ref}/sources, POST /collections/{ref}/sources/url, DELETE /collections/{ref}/sources/{sid} | Sources: upload, add a web page, delete. |
POST /collections/{ref}/sources/{sid}/retry, /refresh | Retry a failed source; capture a web page again. |
GET/PUT /collections/{ref}/sources/{sid}/wiki, POST .../wiki/regenerate, POST .../wiki/approve, GET .../passages, GET .../download/original, GET .../download/page | The source page, its passages and downloads. |
GET /collections/{ref}/search, GET /find | Search inside a collection; search across everything you may read. |
GET /collections/{ref}/topics, GET /collections/{ref}/topics/{slug}, POST .../merge, POST .../revise | Topics. |
PUT/DELETE .../topics/{slug}/model-links, POST .../model-links/decide, POST .../model-links/suggest | The bridge to the model. |
GET /collections/{ref}/inbox, GET /collections/{ref}/conflicts, GET .../conflicts/{kid}, POST .../conflicts/{kid}/approve, /reject, /redirect | The review queue and its decisions. |
GET/POST/PATCH/DELETE /collections/{ref}/vocabulary..., POST .../vocabulary/proposals/{pid}, POST .../vocabulary/{kind}/merge | The collection's vocabulary. |
GET/POST /collections/{ref}/health | Run and read the health check. |
GET /collections/{ref}/graph | The topic graph. |
GET/POST /collections/{ref}/interviews, POST .../interviews/{iid}/turns, /draft, /finalize, PUT/DELETE .../claims/{claim_id} | Interviews. |
GET /collections/{ref}/export | Export a collection as a zip (managers). |