API Reference¶
This reference covers the HTTP JSON endpoints and WebSocket protocol registered
in src/numi_chat/web/app.py. In development (ENVIRONMENT=development),
FastAPI also serves interactive OpenAPI docs at /docs, /redoc, and
/openapi.json. For the end-to-end turn lifecycle, see
Message Flow and Persistence.
Base URL and authentication¶
The server listens on http://localhost:4567 by default. JSON routes live under
/api/v1 (except health checks, /generated-files, /s/{token}, and
/ws/{chat_id}).
Requests can authenticate with either:
or the access_token HttpOnly cookie set by the web UI. Access JWTs are
checked against an active, unrevoked session in refreshtoken. Missing or
invalid credentials return 401, insufficient permissions return 403, and
rate-limited requests return 429 (with Retry-After when applicable).
Authentication endpoints¶
Mounted under /api/v1/auth:
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET |
/registration-status |
No | Check whether user self-registration is open |
POST |
/register |
No | Register the first account (becomes admin) or a new user when registration is enabled |
POST |
/token |
No | Log in with OAuth2 form fields username and password |
POST |
/refresh |
No | Rotate a refresh token for a new access/refresh token pair |
POST |
/logout |
No | Revoke the refresh cookie's session and clear auth cookies |
POST /register accepts {"username": "...", "password": "..."}. Usernames are
3 to 50 characters matching [A-Za-z0-9_-]+; passwords default to at least 12
characters with uppercase, lowercase, digit, and symbol requirements.
POST /token uses application/x-www-form-urlencoded and returns:
Each refresh token is single-use and rotates on POST /refresh.
Chat endpoints¶
All chat endpoints require authentication. {chat_id} is the chat's UUID.
| Method | Path | Purpose |
|---|---|---|
GET |
/api/v1/chats/ |
List chats (offset, limit 1 to 100, optional archived boolean) |
GET |
/api/v1/chats/search |
Search chat titles and messages (q up to 200 chars, optional archived boolean) |
POST |
/api/v1/chats/ |
Create a chat (201) |
PATCH |
/api/v1/chats/{chat_id}/organization |
Pin or archive a chat ({"pinned": bool, "archived": bool}) |
DELETE |
/api/v1/chats/{chat_id} |
Delete a chat and all owned files and records |
GET |
/api/v1/chats/{chat_id}/messages |
Load paginated chat messages |
POST |
/api/v1/chats/{chat_id}/title |
Rename a chat ({"title": "..."}) |
POST |
/api/v1/chats/{chat_id}/model |
Change the model on an empty chat ({"model": "..."}) |
POST |
/api/v1/chats/{chat_id}/continue |
Copy the visible conversation into a new chat with another model (201) |
GET |
/api/v1/chats/{chat_id}/queued-messages |
List pending queued inputs |
POST |
/api/v1/chats/{chat_id}/queued-messages |
Queue a message while a turn is running (202) |
DELETE |
/api/v1/chats/{chat_id}/queued-messages/{request_id} |
Remove a pending queued message |
POST |
/api/v1/chats/{chat_id}/reasoning |
Set the chat's reasoning effort ({"reasoning_level": "..."}) |
POST |
/api/v1/chats/{chat_id}/tools |
Set enabled custom tools ({"enabled_tools": ["..."]}); lifts prior group declines |
POST |
/api/v1/chats/{chat_id}/abort |
Cancel an active turn |
POST |
/api/v1/chats/{chat_id}/truncate/{message_id} |
Soft-delete message_id and all later messages, or switch response versions |
Continuations and queued input¶
POST /api/v1/chats/{chat_id}/continue accepts {"model": "CATALOG_MODEL_ID"}
and an optional through_message_id. It copies visible messages, tool calls,
uploads, and generated files into a new chat whose continued_from field points
to the source chat's UUID. Reasoning traces, usage totals, and unselected
response versions are omitted.
POST /api/v1/chats/{chat_id}/queued-messages accepts request_id (UUID),
message, optional attached_files and vision_files, optional
deep_research (default false), and timing (after_turn or next_step).
Up to 10 messages can wait per chat. next_step injects the message after the
current tool batch completes; after_turn starts immediately after the current
answer finishes.
Share links¶
A share link is a frozen, read-only public snapshot created at share time. Later messages or edits in the chat never modify an existing share link.
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET |
/api/v1/chats/{chat_id}/shares |
Yes | List active share links for the chat |
POST |
/api/v1/chats/{chat_id}/shares |
Yes | Create a share link ({"expires_in_days": 1 \| 7 \| 30 \| null}, returns 201) |
DELETE |
/api/v1/chats/{chat_id}/shares/{share_id} |
Yes | Revoke and delete a share link (204) |
GET |
/api/v1/shares/{token} |
No | Fetch the public snapshot JSON |
GET |
/api/v1/shares/{token}/favicon |
No | Fetch a citation favicon for a domain referenced in the snapshot |
GET |
/s/{token} |
No | Render the read-only shared chat page |
GET |
/s/{token}/files/{filename} |
No | Serve a generated file referenced in the snapshot |
Snapshots strip system messages, usage costs, internal database IDs, request
IDs, private tools (recall_memory, past_chats, remember_fact,
forget_fact, grocery_profile, view, read_skill), and tool activation
cards. Public share routes send Cache-Control: no-store,
Referrer-Policy: no-referrer, and X-Robots-Tag: noindex, nofollow, noarchive,
nosnippet, noimageindex.
Schedules and notifications¶
See Schedule chats. Every route requires authentication and only reaches the caller's own schedules.
| Method | Path | Purpose |
|---|---|---|
GET |
/api/v1/schedules |
List your schedules with next_run_at, last_status, last_error, and last_chat_id |
POST |
/api/v1/schedules |
Create a schedule (chat_id, prompt, time_of_day HH:MM, weekdays 0 = Monday, interval_hours 1 to 168 or null, IANA timezone, new_chat, deep_research, enabled; returns 201) |
PUT |
/api/v1/schedules/{id} |
Replace a schedule's settings (same body without chat_id) |
DELETE |
/api/v1/schedules/{id} |
Delete a schedule (204) |
POST |
/api/v1/schedules/{id}/run |
Start a run now (202, {"chat_id": "..."}; 409 while the chat or your turn limit is busy) |
GET |
/api/v1/notifications |
{"public_key", "paused", "idle_days"}; also records the visit used for the idle pause |
POST |
/api/v1/notifications/subscriptions |
Register this browser's push subscription ({"endpoint", "keys": {"p256dh", "auth"}}; the endpoint must be a public HTTPS URL) |
DELETE |
/api/v1/notifications/subscriptions |
Remove a subscription ({"endpoint"}) |
POST |
/api/v1/notifications/resume |
Turn paused notifications back on |
A scheduled run's user message carries a request_meta part whose
request_id starts with schedule-.
Reasoning updates¶
POST /api/v1/chats/{chat_id}/reasoning accepts off, minimal, low,
medium, high, xhigh, and max, normalizing the requested value against
the model's supported capabilities.
History pagination¶
GET /api/v1/chats/{chat_id}/messages accepts limit (1 to 100 user turns,
default 20) plus before_id, around_id, and through_id. Responses set
X-History-More and X-History-Before headers and fold tool outputs into their
corresponding assistant tool_calls entries for display.
Files and uploads¶
| Method | Path | Auth | Purpose |
|---|---|---|---|
POST |
/api/v1/upload?chat_id={chat_id} |
Yes | Upload a file to a chat (multipart/form-data field file) |
GET |
/api/v1/chats/{chat_id}/files |
Yes | List uploaded files in the chat |
GET |
/api/v1/chats/{chat_id}/files/download/{filename} |
Yes | Download an uploaded file |
GET |
/api/v1/library |
Yes | List uploaded and generated files across all your chats |
POST |
/api/v1/library/attach?chat_id={chat_id} |
Yes | Copy a file from your library into a chat |
POST |
/api/v1/me/avatar |
Yes | Upload a profile avatar (multipart/form-data field file; PNG, JPEG, WebP or GIF) |
GET |
/generated-files/{chat_id}/{filename} |
Yes | Serve a generated file (?preview=true for inline PDF, ?download=true to force download) |
User and settings endpoints¶
Mounted under /api/v1/me:
| Method | Path | Purpose |
|---|---|---|
GET |
/api/v1/me/ |
Read current user profile and tier capabilities |
PATCH |
/api/v1/me/username |
Change username ({"username": "..."}) |
POST |
/api/v1/me/password |
Change password ({"current_password": "...", "new_password": "..."}) and revoke other sessions |
GET |
/api/v1/me/sessions |
List active signed-in sessions |
DELETE |
/api/v1/me/sessions/{session_id} |
Revoke one other session |
POST |
/api/v1/me/sessions/revoke-others |
Revoke all sessions except the current one |
DELETE |
/api/v1/me/ |
Delete account and all owned data ({"password": "..."}) |
GET |
/api/v1/me/export |
Export account chats, messages, and memory as JSON |
GET |
/api/v1/me/settings |
Read personal_preferences |
POST |
/api/v1/me/settings |
Update personal_preferences |
PUT |
/api/v1/me/default-model |
Set the model new chats start with ({"model": "<id>"}; an empty string returns to the server default) |
Memory endpoints¶
All memory endpoints require authentication:
| Method | Path | Purpose |
|---|---|---|
GET |
/api/v1/memories/ |
List explicit facts saved with remember_fact |
DELETE |
/api/v1/memories/{memory_id} |
Delete one explicit fact |
GET |
/api/v1/memories/chats/{chat_id}/summary |
Read a chat's extracted summary and topics |
GET |
/api/v1/me/memory |
Read all active memory entries, details, and token counts |
PATCH |
/api/v1/me/memory/settings |
Toggle memory_enabled for the current account |
GET |
/api/v1/me/memory/export |
Export current memory, explicit facts, and personal instructions as Markdown |
POST |
/api/v1/me/memory/import |
Import external memory notes into structured entries |
DELETE |
/api/v1/me/memory |
Clear all saved memory and advance memory_reset_at |
POST |
/api/v1/me/memory/entries |
Create a manual memory entry |
PATCH |
/api/v1/me/memory/entries/{entry_id} |
Rename an entry or update its summary/category |
DELETE |
/api/v1/me/memory/entries/{entry_id} |
Delete an entry and its details |
POST |
/api/v1/me/memory/entries/{entry_id}/items |
Add a manual detail bullet to an entry |
PATCH |
/api/v1/me/memory/items/{item_id} |
Edit a detail's text or durability |
DELETE |
/api/v1/me/memory/items/{item_id} |
Delete one detail bullet |
GET |
/api/v1/me/memory/profile/history |
List immutable memory snapshots |
GET |
/api/v1/me/memory/profile/history/{snapshot_id} |
Read one memory snapshot |
POST |
/api/v1/me/memory/profile/consolidate |
Trigger background observation consolidation |
POST |
/api/v1/me/memory/aggregate |
Trigger cross-chat Profile and Preferences aggregation |
GET |
/api/v1/me/memory/model |
Read the active memory model |
GET |
/api/v1/me/memory/observations |
List extracted observations (consolidated, limit, offset) |
Details created or edited through the API are marked source: "manual", never
expire, and are not overwritten by background passes.
Metadata endpoints¶
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET |
/api/v1/tools |
Yes | List registered tools, schemas, groups, and deep_research availability |
GET |
/api/v1/models |
No | List selectable catalog models (plus owner's chatgpt:* models when authenticated); userDefault is the signed-in user's own default model, if still selectable |
GET |
/api/v1/instance |
No | Read public operator and privacy metadata |
GET |
/api/v1/version |
Yes | Read deployed build info (commit, committed_at, deployed_at) |
GET |
/api/v1/favicon |
Yes | Fetch a citation favicon (domain, optional size 16 to 128) |
Admin endpoints¶
All /api/v1/admin/* endpoints require is_admin=true.
Model-setting responses include model, kind (llm or decision), source,
config_model and override_model. The ranking shortlist response contains
models (each with id, label and hint), default_llm_model and
default_decision_model. It is separate from the conversational catalog.
| Method | Path | Purpose |
|---|---|---|
GET |
/api/v1/admin/stats |
Instance usage and record counts |
GET |
/api/v1/admin/users |
List accounts with usage statistics and assigned tiers |
POST |
/api/v1/admin/users/{user_id}/reset-password |
Reset a user's password |
PUT |
/api/v1/admin/users/{user_id}/tier |
Assign a user to an access tier |
DELETE |
/api/v1/admin/users/{user_id} |
Delete a user and all owned data |
GET, PUT |
/api/v1/admin/tiers |
Read or update access tiers and rate/tool limits |
GET, POST |
/api/v1/admin/app-settings |
Read or update instance settings (such as open registration) |
GET, PUT |
/api/v1/admin/skills |
List skills and toggle all skills or individual skills on/off |
GET, PUT, DELETE |
/api/v1/admin/model-settings/{name} |
Read, set, or reset the chat-title, memory, memory-upkeep or search-ranking model override |
GET |
/api/v1/admin/model-settings/search-ranking/decision-models |
Read the curated ranking shortlist and the initial LLM/decision choices; no upstream request |
GET |
/api/v1/admin/runtime-settings |
List the settings an admin can change without a restart, with current and configured values |
PUT, DELETE |
/api/v1/admin/runtime-settings/{key} |
Save ({"value": ...}) or reset one runtime setting |
GET |
/api/v1/admin/api-keys |
List provider API keys with source and masked last-4 hint |
PUT, DELETE |
/api/v1/admin/api-keys/{name} |
Save or remove an encrypted live API key override |
GET, DELETE |
/api/v1/admin/chatgpt |
Read or disconnect the calling admin's ChatGPT subscription |
POST, DELETE |
/api/v1/admin/chatgpt/sign-in |
Start or cancel a ChatGPT OAuth sign-in |
POST |
/api/v1/admin/chatgpt/complete |
Complete ChatGPT sign-in from a pasted callback URL |
POST, PUT |
/api/v1/admin/chatgpt/models |
Refresh or select enabled ChatGPT plan models |
PUT |
/api/v1/admin/chatgpt/settings |
Update ChatGPT plan reasoning_summary, verbosity, fast, or full_resolution_images |
GET, PUT, DELETE |
/api/v1/admin/web-providers |
Read, reorder/toggle, or reset web search (?kind=search), fetch (?kind=fetch) or Numi Search (?kind=numi) providers |
POST |
/api/v1/admin/web-providers/{name}/test |
Run a live test search or page fetch (?kind=fetch) against one provider |
GET, POST |
/api/v1/admin/models |
List or add catalog models |
PATCH, DELETE |
/api/v1/admin/models/{model_id} |
Edit or delete a catalog model (DELETE ?replacement= migrates chats) |
GET |
/api/v1/admin/models/{model_id}/references |
Count chats, settings, and tiers referencing a model |
POST |
/api/v1/admin/models/default |
Set the default catalog model |
GET |
/api/v1/admin/models/defaults |
List packaged models missing from the active catalog |
POST |
/api/v1/admin/models/import |
Import catalog JSON (mode: merge, update, or replace) |
GET |
/api/v1/admin/models/export |
Export the active catalog as JSON |
POST |
/api/v1/admin/models/reload |
Reload state/models.json from disk |
GET |
/api/v1/admin/models/discovery |
Search a provider's live model list (provider, query, limit) |
GET |
/api/v1/admin/models/discovery/detail |
Fetch detailed capabilities for one discovered model (provider, model_id) |
Health and browser routes¶
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET |
/health |
No | Basic service health |
GET |
/health/ready |
No | Database readiness check |
GET |
/health/live |
No | Process liveness check |
GET |
/, /chat, /login, /signup |
No | Web UI pages |
GET |
/admin, /models, /tiers |
Admin | Administration pages |
GET |
/licenses |
No | Open-source license inventory for bundled assets and Python packages |
WebSocket protocol¶
Connect to /ws/{chat_id} for a chat owned by the authenticated user using the
access_token cookie or an Authorization: Bearer header.
Sending a message¶
Send a JSON text frame:
{
"message": "Summarize these files",
"vision_files": ["diagram.png"],
"attached_files": ["notes.pdf"],
"deep_research": false,
"request_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}
Keep the same request_id when retrying a send so the server deduplicates an
already-saved user message. Send {"message": "ping"} for keepalive (replies
with {"type": "pong"}).
Reconnecting to an active turn¶
Pass turn_id and last_event_id in the query string when reconnecting. The
server sends a stream_sync event with active, reset, events, and turn
IDs so the browser can either replay missed events or reset to the latest
snapshot.
Server events¶
Broadcast turn events include event_id and turn_id.
| Type | Main fields | Meaning |
|---|---|---|
stream_sync |
active, reset, events, IDs |
Initial state or reconnect replay |
turn_start |
before_message_id, request_id |
A turn has started |
accepted |
request_id, message |
User message was persisted (continuation: true when dequeued mid-stream) |
request_resolved |
request_id, message_id |
Resent request_id matched an already-saved message |
rejected |
request_id, code, content |
Submission rejected (empty_message or turn_limit) |
tool_gate |
gate_id, groups, timeout_s, snapshot_key |
Pre-turn optional tool group suggestion awaiting user decision |
tool_gate_closed |
gate_id, enabled_groups, snapshot_key |
Tool activation card resolved |
status |
content |
Turn status update (such as thinking or compacting) |
content |
content |
Streamed assistant answer chunk |
reasoning |
content |
Streamed reasoning trace or summary chunk |
tool_preparing |
name, tool_call_id |
Tool call started streaming before arguments finished |
tool_start |
name, input, tool_call_id |
Tool execution started |
tool_end |
name, output, tool_call_id |
Tool execution finished |
research_agent |
agent, snapshot_key |
Live progress update for one deep research sub-agent |
title_update |
title |
Generated or updated chat title |
done |
message_id, optional usage, optional intermediate |
Assistant message persisted |
error |
content |
Turn error, cancellation, or budget limit |
turn_end |
None | Turn producer finished (including after error) |
queued_messages |
messages, snapshot_key |
Updated queue of pending user inputs |
Error format¶
HTTP errors use FastAPI's standard JSON body:
Ownership checks return 404 when a resource belongs to another user so object
existence is not leaked.