AI API Endpoints
Every AI-related HTTP endpoint, by surface area. Auth column shows what the endpoint accepts: Session (logged-in user cookie), MCP (Authorization: Bearer cp_live_...), or Cron (Authorization: Bearer $CRON_SECRET).
Chat
| Method | Endpoint | Auth | Purpose |
|---|
| POST | /api/ai/chat | Session | SSE-streaming chat with tool calls. |
| POST | /api/integrations/ai/execute | Session | One-shot AI execute used by automation AI steps and the workflow builder test button. |
Chat Threads
| Method | Endpoint | Auth | Purpose |
|---|
| GET | /api/ai/chats | Session | List chat threads for the current user. |
| POST | /api/ai/chats | Session | Create a new thread. |
| GET | /api/ai/chats/:id | Session | Get a thread with metadata. |
| PATCH | /api/ai/chats/:id | Session | Update (rename / archive). |
| DELETE | /api/ai/chats/:id | Session | Delete a thread + all messages. |
| GET | /api/ai/chats/:id/messages | Session | List messages in a thread. |
| POST | /api/ai/chats/:id/messages | Session | Persist messages. |
Saved Prompts (Skills)
| Method | Endpoint | Auth | Purpose |
|---|
| GET | /api/ai/skills | Session | List per-user skills (KB-backed). |
| POST | /api/ai/skills | Session | Create a skill. Title up to 120 chars, content up to 5000. |
| DELETE | /api/ai/skills/:id | Session | Delete a skill. |
| POST | /api/ai/skills/:id | Session | Mark used (no-op, kept for compat). |
Transcripts
| Method | Endpoint | Auth | Purpose |
|---|
| POST | /api/ai/transcribe | Session | Upload audio + transcribe. Multipart form. |
| GET | /api/ai/transcripts | Session | List the current user’s transcripts. |
| GET | /api/ai/transcripts/:id | Session | Get a transcript. |
| DELETE | /api/ai/transcripts/:id | Session | Delete. |
Passport OCR
| Method | Endpoint | Auth | Purpose |
|---|
| POST | /api/ai/passport-ocr | Session | AI vision passport extraction. |
BYOK Credentials
| Method | Endpoint | Auth | Roles | Purpose |
|---|
| GET | /api/settings/ai-config/personal | Session | Member | Personal BYOK row + active org policy. |
| PATCH | /api/settings/ai-config/personal | Session | Member | Upsert personal BYOK. 403 when org disables personal keys. |
| DELETE | /api/settings/ai-config/personal | Session | Member | Clear personal BYOK. |
| GET | /api/settings/ai-config | Session | OWNER/ADMIN | Workspace-level override. |
| POST | /api/settings/ai-config | Session | OWNER | Legacy extraction-pipeline endpoint (with verifyApiKey). |
| PATCH | /api/settings/ai-config | Session | OWNER/ADMIN | Update workspace override. |
| DELETE | /api/settings/ai-config | Session | OWNER/ADMIN | Clear workspace override. |
| GET | /api/organizations/[orgId]/ai-config | Session | OWNER/ADMIN | Org-level primary BYOK + allowPersonalKeys. |
| PUT | /api/organizations/[orgId]/ai-config | Session | OWNER/ADMIN | Update org config (incl. allowPersonalKeys). |
| DELETE | /api/organizations/[orgId]/ai-config | Session | OWNER | Clear org config. |
| GET | /api/ai/models | Session | - | Live model catalogue (proxies provider /v1/models, 5-min cache). |
| POST | /api/settings/ai-config/openclaw/test-fire | Session | OWNER/ADMIN | Probe the saved OpenClaw gateway: GET /health + POST /v1/chat/completions. Returns structured result with status / duration / body for each probe + a one-line summary. Surfaces the today-typical 404 (endpoint not implemented) clearly. |
| POST | /api/settings/ai-config/hermes/test-fire | Session | OWNER/ADMIN | Probe the saved Hermes gateway: GET /v1/models + POST /v1/chat/completions. The endpoint must be the tenant base URL, e.g. https://gateway.opbox.app/tenant/classical-visas, not the host root. |
Agent Tasks (Bridge - MCP API Key Auth)
| Method | Endpoint | Auth | Purpose |
|---|
| POST | /api/agent-tasks/[taskId]/claim | MCP | Atomic claim. Returns claimToken + autonomy level. |
| PATCH | /api/agent-tasks/[taskId]/progress | MCP | Update progressText. Requires claimToken. |
| PATCH | /api/agent-tasks/[taskId]/complete | MCP | Transition to DONE/FAILED. Accepts result + cost + duration. |
Agent Tasks (Admin - Session Auth)
| Method | Endpoint | Auth | Roles | Purpose |
|---|
| GET | /api/agent-tasks | Session | OWNER/ADMIN | List tasks. |
| POST | /api/agent-tasks | Session | OWNER/ADMIN | Create manual task. |
| GET | /api/agent-tasks/[taskId] | Session | OWNER/ADMIN | Full task details. |
| PATCH | /api/agent-tasks/[taskId] | Session | OWNER/ADMIN | Cancel. |
| POST | /api/agent-tasks/[taskId]/retry | Session | OWNER/ADMIN | Retry FAILED/TIMED_OUT. |
Agent API Keys
| Method | Endpoint | Auth | Roles | Purpose |
|---|
| GET | /api/agent/api-keys | Session | OWNER/ADMIN | List MCP keys (masked). |
| POST | /api/agent/api-keys | Session | OWNER/ADMIN | Mint a key. Returns cleartext once. |
| PATCH | /api/agent/api-keys/[id] | Session | OWNER/ADMIN | Update name / autonomy / disabled state. |
| DELETE | /api/agent/api-keys/[id] | Session | OWNER/ADMIN | Revoke. |
MCP Bridge
| Method | Endpoint | Auth | Purpose |
|---|
| GET | /api/mcp/health | MCP | Liveness + key summary. |
| GET | /api/mcp/tools/list | MCP | Lazy catalogue (~5KB). Pass ?mode=full for the full payload. |
| POST | /api/mcp/tools/call | MCP or OpenClaw bearer | Execute a tool. JSON body with name and arguments. The bearer auth resolver tries cp_live_* first; on miss, falls back to OpenClaw bearer hash lookup (bidirectional auth). |
| GET | /api/mcp/catalogue/fingerprint | None | Public stable SHA-256 of the live tool catalogue. |
| GET | /api/mcp/catalogue/diff | Session | Admin: diff against last snapshot. |
| GET | /api/mcp/catalogue/snapshots | Session | Admin: list snapshots. |
Doc Generation
| Method | Endpoint | Auth | Purpose |
|---|
| POST | /api/documents/packs/[packId]/generate | Session | Generate. Coverage FAIL returns 422. |
| POST | /api/documents/packs/[packId]/preview | Session | Preview without writing. |
| GET | /api/documents/generated/[id] | Session | Generated doc metadata + snapshot. |
| GET | /api/documents/generated/[id]/download | Session | Stream the rendered DOCX. |
| GET | /api/documents/doc/[id]/bookmarks | Session | List bookmarks. |
| DELETE | /api/documents/doc/[id]/bookmarks/[name] | Session | Remove a bookmark (markers only). |
| GET | /api/documents/doc/[id]/styles | Session | Word paragraph styles. |
| GET | /api/settings/agent-config | Session | OWNER/ADMIN: doc-gen agent config (cloud-fire + kill-switch). |
| PUT | /api/settings/agent-config | Session | OWNER/ADMIN: update. |
| POST | /api/settings/agent-config/test-fire | Session | OWNER/ADMIN: test the cloud-fire dispatch. |
RAG
| Method | Endpoint | Auth | Roles | Purpose |
|---|
| GET | /api/admin/rag | Session | OWNER/ADMIN | Status + stats. ?sourceType=... filters. |
| POST | /api/admin/rag | Session | OWNER | Trigger backfill. JSON body with sourceType (omit to backfill all types). |
| GET | /api/docs/search | Session | - | Search system docs (powers search_system_docs). |
| POST | /api/docs/embed | Session | OWNER/ADMIN | Embed system docs. |
Cost Control
| Method | Endpoint | Auth | Roles | Purpose |
|---|
| GET | /api/settings/ai-usage | Session | OWNER/ADMIN | Usage data. ?view=summary for spend breakdown. |
| POST | /api/settings/ai-usage/reconcile | Session | OWNER | Run reconcileBudgetSnapshot() for current month. |
Identity & Files
| Method | Endpoint | Auth | Purpose |
|---|
| POST | /api/files/[fileId]/request-access | Session | Request cross-workspace access. |
| GET | /api/files/shared/[fileId]?grantId=... | Session | Stream a granted file. |
| GET | /api/oversight/identities | Session | Search global profiles (workspace + overseer model). |
| GET | /api/oversight/identities/[id] | Session | Single profile + risk + audit. |
Security Events
| Method | Endpoint | Auth | Roles | Purpose |
|---|
| GET | /api/admin/security-events | Session | OWNER | Query the security event log. |
Cron-Triggered AI Work
| Method | Endpoint | Auth | Purpose |
|---|
| POST | /api/cron/verify-ai-keys | Cron | Probe stored BYOK keys against /v1/models?limit=1; clear keyVerifiedAt on 401/403. |
| POST | /api/cron/tool-catalogue-notify | Cron | Daily 04:00 UTC - page workspace OWNERs on structural catalogue changes. |
| POST | /api/cron/retry-background-jobs | Cron | Retry compliance-critical fire-and-forget jobs (incl. some AI side effects). |
All cron endpoints share a timing-safe auth helper - they 401 on missing or wrong CRON_SECRET.
Session (cookie)
Standard NextAuth session cookie. CSRF token required for non-GET methods (x-csrf-token header from useCsrf() hook).
MCP (Bearer)
Authorization: Bearer cp_live_...
X-MCP-Client: claude-code
X-MCP-Client is mandatory; missing it returns 400. Browsers can’t set it cross-origin, which blocks compromised browser sessions from invoking MCP even with a stolen key.
Cron (Bearer)
Authorization: Bearer $CRON_SECRET
CRON_SECRET is an environment secret (CRON_SECRET in .env), supplied to both the frontend and the cron-scheduler container that polls /api/cron/workflows. Compared timing-safe via crypto.timingSafeEqual.
See Also