Skip to content

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:

Authorization: Bearer <access_token>

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:

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "bearer",
  "expires_in": 1800
}

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.

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:

{"detail": "Error message"}

Ownership checks return 404 when a resource belongs to another user so object existence is not leaked.