API reference
Base URL for the manual lab: http://localhost:8000. Protected endpoints require Authorization: Bearer <key>. JSON requests also need Content-Type: application/json.
The running service exposes /docs, /redoc, and /openapi.json. Use that schema to verify a deployed revision; this page describes the committed backend used for this documentation change.
Query body
Section titled “Query body”POST /api/v1/query accepts:
| Field | Default / constraint | Meaning |
|---|---|---|
query | Required; 1–20,000 characters | Prompt text |
context_limit | 5; range 1–20 | Knowledge documents requested |
include_sources | true | Include retrieved content in response |
conversation_id | null | Continue an existing thread when memory is enabled |
user_id | null | Non-secret identifier; does not enforce isolation |
model | null | Requested model when routing is enabled |
prompt_id, playbook_id | null | Repository file paths used for metadata extraction |
task_type | null | Routing hint |
For example, use prompts/security/security-review.md or playbooks/security-review.md as metadata paths. They are routing signals, not an automatic instruction-file execution mechanism.
The response includes response, sources, model, timestamp, tokens_used, conversation_id, and routing_info. See the first-query example.
Endpoint index
Section titled “Endpoint index”| Method and path | Request | Purpose |
|---|---|---|
GET /health | None; public | Knowledge-store count and API reachability |
POST /api/v1/query | JSON object above | Retrieve and generate |
POST /api/v1/ingest | JSON array of {id, content} | Add knowledge documents |
GET /api/v1/models | None | List Ollama models |
POST /api/v1/pull-model | URL model_name | Download a model; changes disk state |
GET /api/v1/router/health | None | Router component summary |
GET /api/v1/router/statistics | None | Process-local routing counts |
POST /api/v1/router/test | URL query, optional prompt_id, playbook_id | Preview scoring |
POST /api/v1/router/refresh-models | None | Refresh availability cache |
POST /api/v1/conversations | JSON user_id, optional retention_days (1–365, default 7) | Create thread |
GET /api/v1/conversations/{id} | Path ID | Thread metadata |
GET /api/v1/conversations/{id}/messages | Path ID; URL limit default 10 | Stored messages |
GET /api/v1/users/{user_id}/conversations | Path user; URL limit default 20 | List threads |
DELETE /api/v1/conversations/{id} | Path ID | Delete thread and attempt vector cleanup |
POST /api/v1/conversations/cleanup | None | Delete expired SQLite threads |
Limits and caveats
Section titled “Limits and caveats”Query uses 10 requests/minute and ingest uses 20, sharing a single per-token history in the current process. Models and pull-model do not implement the limits previously documented for them. Limits are not coordinated across workers. Conversation list limits are not bounded with Pydantic constraints.
The health endpoints do not prove generation works. Conversation endpoints do not authorize ownership. Cleanup’s reported message count is an approximation and omits vector expiry. Read memory behavior before using these endpoints.
Errors
Section titled “Errors”| Status | Typical cause |
|---|---|
| 403 | Missing/invalid bearer authentication in the pinned stack |
| 404 | A requested conversation is missing where checked |
| 422 | Missing parameters, wrong request location, or invalid JSON fields |
| 429 | Query/ingest in-memory request threshold |
| 500 | Generation/storage failure; some paths expose exception text |
| 501 | Requested conversation/router feature is disabled |
Next: Configuration or troubleshooting.