REST API
HTTP API surface — all endpoint groups, authentication, pagination, errors, and rate limits.
Sophon exposes every feature through a REST API at /api/* on the Gateway. The Dashboard, CLI, and Mobile app all use the same API; there are no internal endpoints.
Base URL
https://<gateway>/apiDefault Gateway port in development: 8080.
Authentication
| Mode | Used by | Header |
|---|---|---|
| JWT Bearer | Dashboard, CLI after sophon login, Mobile | Authorization: Bearer <jwt> |
| API tokens | CI, scripts, long-lived integrations | Authorization: Bearer sk_... |
| OIDC SSO | Enterprise SSO-configured deployments | JWT from IdP after OIDC exchange |
| No auth | Personal tier with AutoAdmin: true in config (dev only) | — |
Tokens are user-scoped. Multi-tenant deployments also require tenant context (see Tenants).
Endpoint groups
All endpoints live under /api. Major groups:
Identity & auth
POST /auth/login— email + password → JWTPOST /auth/logout— revoke current sessionPOST /auth/refresh— renew JWT before idle timeoutPOST /auth/tokens— create API tokenGET /auth/me— current user infoGET /auth/sessions— active sessions for current userDELETE /auth/sessions/{id}— revoke a session
Agents
GET /agents/POST /agents/GET|PATCH|DELETE /agents/{id}GET|PUT /agents/{id}/soul— read/write SOUL.mdGET|PUT /agents/{id}/boot— BOOT.mdGET|PUT /agents/{id}/heartbeat— HEARTBEAT.mdGET|PUT /agents/{id}/tools— tool allowlist
Agent packages
New in 2.2: agents are the third marketplace package type, beside skills and plugins. See Agent Packages. Clients check for the agentPackages.v1 feature first. Every change needs ManageSkills, else 403 { "error": "forbidden", "message": "…" }; routes marked marketplace answer 404 MARKETPLACE_DISABLED while the marketplace is off. Failures are { error, message } with a snake_case code.
Install
POST /marketplace/agents/prepare— body{ slug, version }: download, check and scan a marketplace agent package and return a preview with a one-time token (marketplace)POST /agent-packages/import— the same from a.sophon-agentfile:multipart/form-data, one file fieldpackage, at most 1 MiBPOST /agent-packages/prepared/{token}/commit— body{ agentId, allowDelegationFrom, replace }: install the prepared package. 201 withLocation: /api/agents/{agentId}DELETE /agent-packages/prepared/{token}— discard a prepared package; 204
Installed agents
GET /marketplace/search?type=agent— search agent packages (untyped searches leave agents out)GET /marketplace/installed?types=agent— agents installed from a packageGET /agents/{id}/marketplace?check=— the agent's package origin and update statusPOST /agents/{id}/marketplace/update/prepare— preview an update (marketplace);POST /agents/{id}/marketplace/update/apply— take it (marketplace)POST /agents/{id}/marketplace/skip(marketplace),POST /agents/{id}/marketplace/reset,PUT /agents/{id}/marketplace/auto-update(marketplace),POST /agents/{id}/marketplace/keep-using,DELETE /agents/{id}/marketplace(detach)POST /marketplace/updates/check,GET /marketplace/updates/statusandPOST /marketplace/updates/applygainagentUpdates,lastAgentRun,agentIdsandagentResults
Export and publish
POST /agents/{id}/export?dryRun=— the agent as a.sophon-agentfile (application/zip), or withdryRun=truea preview of the packagePOST /agents/{id}/publish— publish through the linked marketplace account (marketplace)
POST /marketplace/install with an agent package answers 422 package_is_agent: install agents through the routes above, which show the persona files and required skills before anything is installed.
Chat + sessions
POST /chat— send a message synchronously (returns immediately, task runs in background)GET /sessions— listGET /sessions/{id}— describeGET /sessions/{id}/messages— message historyPOST /sessions/{id}/fork— fork a sessionDELETE /sessions/{id}— deleteGET /sessions/{id}/events?window=&afterSequence=&limit=&types=— a bounded slice of the session's events, oldest first.window=oldest(the default) pages forward fromafterSequence;window=latestreturns the newestlimitevents, which is what a client rebuilding plan cards after a reload needs. Any otherwindowis 400invalid_window
Models & routing
Providers, their models, and which model handles each job. See Model routing for how a route is chosen. Routes marked ManageModels need that permission (the Admin role has it); everything else needs only a signed-in user. The routes below that are new in 2.1 answer errors as { error, message } with a snake_case code; the older provider routes (POST, PUT and DELETE /models, POST /models/{id}/test) use the same shape with upper-case codes such as NOT_FOUND.
Providers
GET /models— configured providersPOST /models/PUT /models/{id}/DELETE /models/{id}— add, replace or remove a provider (ManageModels)POST /models/{id}/test— test a provider's connection (ManageModels)POST /models/{id}/default?modelId=— make this the one default provider, optionally with its default model (ManageModels). 204; 404provider_not_found, 400model_not_found, 409provider_disabledPUT /models/{id}/enabled— body{ "enabled": true|false }(ManageModels). A body withoutenabledis 400invalid_request, so an empty body never disables a providerPUT /models/{id}/priority— body{ "priority": n }, n of 1 or more (ManageModels). Priority orders providers after the default; it no longer picks the defaultPOST /models/{id}/models— merge per-model settings without resending the provider: body{ "models": [{ id, contextWindow, tier, roles, usageHint }] }(ManageModels). A field you leave out keeps its value;contextWindow: 0,tier: "",roles: []orusageHint: ""clears it.contextWindowmust be 256 to 10,000,000 andusageHintat most 64 characters. 204; 400invalid_request; 404provider_not_foundGET /models/{id}/available-models?refresh=— the models installed on an Ollama, LM Studio or OpenAI-compatible server, for the Discover dialog (ManageModels). Cached for 60 seconds per provider. 502discovery_failedwhen the server does not answer within 10 seconds. Discovery never changes routingGET /models/candidates— every provider (inactive ones included) with its models as routing sees them: tier, context window,contextUnverified,isLocal, tool and vision support, price per 1M tokens, roles. Never includes an endpoint or a keyGET /models/routing— the retry policy and the failover order. This is a static snapshot: itsfallbackEnableddoes not describe a pinned chat, which never leaves its provider unless Allow fallback is on
Routing at each scope
Every scope stores the same layer: { mode, profile, pin, roles, allowFallback }. mode is inherit (Default), auto or pinned. profile is one of quality, balanced, economy, localFirst, localOnly and is only valid with auto. roles maps orchestrator, executor, researcher, utility and vision to a model ref { providerId, modelId }. allowFallback: null inherits from the next scope. A write replaces the layer whole. Every response carries effective: one row per role, always all five, with the provider and model that role resolves to, its source scope, routedBy, available and warnings.
GET /sessions/{id}/model-routing?explain=— a chat's routing.explain=trueadds each role'schain: every layer the router checked, which one won, and what it shadowedPUT /sessions/{id}/model-routing— body{ v: 1, expectedSeq, layer, client, allowUnlistedModel }.expectedSeqmakes the write compare-and-set (409seq_conflictwhen the chat changed since you read it); leave it null for last write wins. A sub-agent or plan-step session is 409activity_child: change its parent insteadGET|PUT /agents/{id}/model-routing— an agent's routing policy, stored in itsagent.json. Aninheritlayer with no roles clears itGET|PUT /preferences/model-routing— your own default for chats that set nothing ("My default")GET /models/routing-defaults— the host layer and the host Local only ceilingPUT /models/routing-defaults— body{ v: 1, layer, localOnly }(ManageModels).modemust beautoorinherit; the host cannot pin.localOnlyis required, so an omitted flag never lifts the ceiling. The write goes toconfig/appsettings.user.json, and from then on that file wins overSOPHON__Models__Routing__*environment variables
allowUnlistedModel: true lets a write name a model the provider does not list; it needs ManageModels (403 policy_denied otherwise). Other write errors are 400 invalid_argument, provider_unknown, provider_inactive, provider_ambiguous or model_unknown, and 403 policy_denied when a host Local only ceiling refuses a cloud model. A chat you do not own answers a bodiless 404.
Pin a chat to a cloud model, with a local model for research:
curl -X PUT https://gw.example.com/api/sessions/$SESSION/model-routing \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"v": 1,
"expectedSeq": 3,
"client": "api",
"layer": {
"mode": "pinned",
"pin": { "providerId": "anthropic-3f2a9c1b7d4e5f", "modelId": "claude-sonnet-4-6" },
"roles": { "researcher": { "providerId": "ollama-7f3c2a9b1d4e5f6a7", "modelId": "qwen3:8b" } },
"allowFallback": false
}
}'The 200 response is the chat's routing state after the write. One of its five effective rows:
{
"role": "researcher",
"providerId": "ollama-7f3c2a9b1d4e5f6a7",
"providerType": "ollama",
"providerName": "GPU box",
"modelId": "qwen3:8b",
"isLocal": true,
"source": "session",
"routedBy": "pinned",
"available": true,
"unavailableReason": null,
"warnings": [],
"tier": "fast",
"profile": null,
"chain": null
}The state also carries seq (send it back as expectedSeq), allowFallback with allowFallbackSource, localOnly, autoProfile and gaps. Provider ids are generated as the provider type plus a hex suffix, 24 characters in all; read yours from GET /models or GET /models/candidates.
Embeddings
The host embedder and vector index behind semantic memory and document search. See Embeddings. GET /status needs only a signed-in user; every other route needs ManageModels, and every route except test also needs an Admin of the default tenant (403 admin_required otherwise). Jobs run in the background: poll status. Optional POST parameters are query strings, so a bare curl -X POST works.
GET /models/embeddings/status— what works right now:state(ready,resolving,awaitingConsent,offordegraded) with itsreason,vectorStore(sqlite,qdrantornone) andvectorStoreState(ready,breakerOpenornone),embedderState(active,breakerOpen,unavailableornone),semanticSearchAvailable,pending(a cloud embedder waiting for consent),suggestion, and the backgroundreindexjob. Error text is shown to admins onlyPUT /models/embeddings/settings— choose the embedder: body{ mode, providerId, model, dimensions, preferLocal, test, startReindex }.modeisauto,local,provideroroff. Underprovider, one fixed text is embedded first unlesstestis false; a failed test is 422embedding_test_failedand nothing is saved. An unknown provider is 404provider_not_found. Saving writesSophon:Embeddingstoconfig/appsettings.user.json, which then wins overSOPHON__Embeddings__*environment variables. Saving a cloud provider here counts as consentPOST /models/embeddings/test?providerId=&model=&dimensions=— embed one fixed text and probe the vector store. A failed test is 200 withok: falseGET /models/embeddings/consent?logDays=— the cloud embedder waiting for consent and how many memories, daily logs (lastlogDaysdays, default 30) and documents it would receivePOST /models/embeddings/consent?providerId=&startReindex=&logDays=— record an admin's consent. With nothing waiting and noproviderId, 409nothing_to_consent. A local provider is 400: it needs no consentPOST /models/embeddings/reindex?confirm=&logDays=— start the backlog for the active embedder. A cloud embedder needsconfirm=true; without it the answer is 409confirmation_required, and the message gives the counts that would be sentDELETE /models/embeddings/reindex— cancel the running reindex (404not_runningwhen none runs)POST /models/embeddings/rebuild?logDays=— drop and recreate the active embedder's collections and re-embed every user of every tenant. 202; 409rebuild_runningPOST /models/embeddings/install-local?providerId=&model=— ask a configured Ollama to pull an embedding model (defaultnomic-embed-text). Progress is instatus.install. One install at a time (409install_running)GET /models/embeddings/collections/DELETE /models/embeddings/collections/{name}— list vector collections, or delete an inactive one. The collections of the selected, pending or recorded embedder cannot be deleted (409collection_active), and neither can any collection while a reindex runs (409reindex_running)
GET /memory/search now also returns semanticAvailable and semanticError. When the embedder or the vector store fails or is slow, search answers with keyword results instead of an error.
Choose a local embedder explicitly:
curl -X PUT https://gw.example.com/api/models/embeddings/settings \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "mode": "provider", "providerId": "ollama-7f3c2a9b1d4e5f6a7", "model": "nomic-embed-text" }'The 200 response is { status, test, reindex }: the new status, the test that ran before saving, and what happened to the backlog. A local embedder fills its index in the background by itself (unless Sophon:Embeddings:AutoReindex is off); a cloud embedder's first index waits for startReindex=true on the consent call or confirm=true on reindex.
Graph runs
Durable plan runs, including plan recovery. Users see and act on their own runs; admins see all. A run that is missing or not yours answers a bodiless 404. Every refusal is { error, message } with a stable code; before 2.1, error held the sentence.
GET /graph-runs?status=&sessionId=&kind=&limit=— runs, newest first.kind=plankeeps chat plans only.limitdefaults to 50 (1 to 200). Each summary hasstatus,interruptReason,costUsdandretryOfRunIdGET /graph-runs/{id}— the run, its node runs, its current plan, and aretryblock:eligible,reason,message,kind(retry,budgetor null), the step ids that would run again (rerunNodeIds), be kept (carriedNodeIds) or stay blocked (blockedNodeIds),effectful, and for a budget stopbudget { spentUsd, capUsd, tokens, tokenCap }(null otherwise). The run addscontinuationRunIdPOST /graph-runs/{id}/resume— resume a paused (Interrupted) run. 202{ id, status: "resuming" }. Refusals:not_interrupted,run_active,delegation_run,graph_runtime_disabled,budget_exceeded(still over the current cap; resume works once an admin raises it), and 503host_stoppingPOST /graph-runs/{id}/retry— no body. Retry failed steps, or continue a budget stop with a new budget, as a new continuation run that keeps every completed step. The old run is never reopened. 202 withLocation: /api/graph-runs/{newId}and{ id, planId, retryOfRunId, created: true }; a plan gets one continuation, so a repeat call returns the same one as 200 withcreated: false. Refusals:use_resume,run_active,delegation_run,nothing_to_retry,only_blocked_steps,plan_unavailable,session_busy(another plan in the session is live),retry_disabled,graph_runtime_disabled, and 503host_stoppingPOST /graph-runs/{id}/cancel— durable cancel, recorded as a user stop. It also stops a paused run. 200{ id, status: "cancelling" }; 409already_terminalPOST /graph-runs/{id}/save-as-workflow— export a Completed or Failed run as a workflow; 409not_saveableotherwise
Continue a plan that stopped at its budget:
curl -X POST https://gw.example.com/api/graph-runs/graphrun_4f1c2a9e7b3d4c5e8a6f0b1d2c3e4f5a/retry \
-H "Authorization: Bearer $TOKEN"{
"id": "graphrun_9a8b7c6d5e4f30211a2b3c4d5e6f7a8b",
"planId": "plan_7c2e9f04a1b",
"retryOfRunId": "graphrun_4f1c2a9e7b3d4c5e8a6f0b1d2c3e4f5a",
"created": true
}The status is 202 and Location points at the new run. A refusal looks like 409 { "error": "use_resume", "message": "…" }.
Memory
GET /memory/entries— paginated list with filters (scope, agent, query); addincludeSuperseded=trueto also return superseded (historical) factsPOST /memory/entries— create; optionalsupersedes: "mem_..."marks an existing entry as superseded by the new onePUT|DELETE /memory/entries/{id}GET /memory/search?q=&scope=&limit=GET /memory/graph/all?nodeLimit=&entryDays=&kinds=&scope=— full-graph overview (powers the graph explorer)GET /memory/graph?seed=&depth=&limit=— subgraph cluster seeded at an entry or entity idGET /memory/graph/mermaid— Mermaid export of the overview graph (same filters, plusdirection=LR|TDandincludeEntries)GET /memory/entities/duplicates?threshold=&limit=— candidate duplicate entity pairsPOST /memory/entities/{id}/merge— merge a duplicate entity into a survivorPOST /memory/entities/duplicates/{pairKey}/dismiss— dismiss a candidate pairPOST /memory/vectors/reindex— purge and rebuild the current user's memory vectorsGET /memory/logs?agentId=&days=— daily logs
Workflows
Workflows and their JSON format. Every route that names a workflow loads it in the caller's tenant first (404 otherwise). Routes marked ManageWorkflows need that permission (Operator and Admin; since v2.2.0 Viewers on Pro and Enterprise lose it), and routes that change or run a stored workflow also need its owner or an Admin of the tenant, else 403 not_workflow_owner. Workflow errors are { error, message } with a snake_case code.
Definitions
GET /workflows— list the tenant's workflowsGET /workflows/{id}— one workflowPOST /workflows— create or update (upsert byid; ManageWorkflows). 201 on create, 200 on update, with the stored definition plusissues(its warnings). 400workflow_invalidwitherrorsandissues; 409workflow_id_unavailable.version,createdBy,ownerId,updatedBy,updatedAt,tenantIdandsampleInputin the body are ignoredPOST /workflows/validate— new in 2.2: the issues a save of the body would return,{ valid, issues }; nothing is stored (ManageWorkflows). 413payload_too_largeover 1 MiBDELETE /workflows/{id}— delete the workflow, its versions and its run records (ManageWorkflows)GET /workflows/{id}/versions,GET /workflows/{id}/versions/{version}— earlier versions (the 20 newest are kept)POST /workflows/{id}/rollback/{version}— save an earlier version as the newest (ManageWorkflows); 204POST /workflows/{id}/owner— body{ "userId": "…" }: transfer ownership to a user of the tenant, by the owner or an Admin (ManageWorkflows); 204POST /workflows/from-template— create a switched-off copy of a shipped template (ManageWorkflows); 201 withissuesGET /workflow-templates,GET /workflow-templates/{id}— the shipped templatesPOST /workflows/check-credentials— check that the services a definition needs are connected (ManageWorkflows)GET /workflows/trigger-types— new in 2.2:{ fireable, known }, the trigger types this Gateway can fire (any signed-in user)GET /workflows/tool-availability— which tools the workflow sandbox preset allows (ManageWorkflows)GET /channels/send-targets?workflowId=&channel=— the channels a workflow's Send message steps may use (ManageWorkflows)
Starting runs
POST /workflows/{id}/runs— new in 2.2: start amanualrun in the background (ManageWorkflows, owner or Admin). Body (optional){ data, triggerData, agentId, useSampleInput }. 202{ runId, workflowId, status }withLocation: /api/workflow-runs/{runId}. 400bad_requestforuseSampleInputwithout a pinned samplePOST /workflows/{id}/execute— start amanualrun and wait for it to end (ManageWorkflows). AnswersworkflowId, success, nodeResults, error, startedAt, completedAt, thenrunId, status, triggerKind, durationMsPOST /workflows/{id}/webhook— start awebhookrun with the body as$trigger.data(ManageWorkflows, owner or Admin; a signed-in caller, not anonymous). 409trigger_mismatchunless the workflow is enabled with awebhooktrigger.?async=trueanswers 202{ runId, workflowId, status: "pending" }without waiting. For anonymous senders, use a signed inbound registration
Every run start answers 429 too_many_runs when the owner or tenant is over its active-run cap (64 per owner, 256 per tenant by default); nothing is stored then.
Run records (new in 2.2)
GET /workflows/{id}/runsandGET /workflow-runs— root runs, newest first, as{ items, nextCursor }. Query:status,trigger,before(cursor),limit(1-100, default 20);/workflow-runsalso takesworkflowIdandlatestPerWorkflow=true. Test runs are hidden unlesstrigger=test. 400invalid_queryGET /workflow-runs/{runId}—{ run, nodeRuns, definition, input, triggerData, finalVariables, children, parent, canWrite, nodeRunsOmitted }.definition,input,triggerData,finalVariablesand each step's resolved inputs are null unlesscanWrite(the run's user or an Admin). At most 1000 step runs; the rest are counted innodeRunsOmittedGET /workflow-runs/{runId}/node-runs?after=&limit=— every step run bysequence,{ items, nextCursor },limit1-500 (default 200)POST /workflow-runs/{runId}/cancel— cancel a run, or a child run's root (ManageWorkflows, the run's user or an Admin). 204; 404run_not_found; 409run_not_active; 503run_busywithRetry-After: 1GET /workflows/{id}/history,GET /workflows/{id}/history/latest— finished root runs in the v2.1 history shape plusrunId,status,triggerKindanddurationMs;?limit1-100, default 20
Run reads need no permission: they return runs the caller may read (the run's user, the user who started it, or an Admin of the tenant), and fail closed without a user or tenant claim. A missing, foreign or unreadable run answers the same 404 run_not_found.
Run statuses: pending, running, waitingApproval, waitingInput, succeeded, failed, cancelled, interrupted. Trigger kinds: manual, api, webhook, cron, tool, subWorkflow, test, rerun, channelMessage, emailReceived, legacy. Each step run carries effect, tainted, model, inputTokens, outputTokens and costUsd.
Debugging (new in 2.2)
POST /workflows/test-node— run one step as atestrun (ManageWorkflows). Body: thenode, plusworkflowIdandfromRunIdto bind it to a saved workflow and seed it from a run,mockOutputs,variables,triggerData,input,useSampleInputandconfirmEffects. 200{ nodeId, success, output, error, result, testRunId, resolvedInputs, unresolvedReferences, effect }. 400not_testablefor Approval, Info request, Loop, Sub-workflow and long Wait steps; 409effect_confirmation_requiredfor aneffectfulstep unless"confirmEffects": true; 413payload_too_largeover 256 KBGET /workflow-runs/{runId}/rerun-plan?fromNodeId=— what a re-run would keep and run again:{ eligible, reason, fromNodeId, carriedNodeIds, rerunNodeIds, effectfulReexecutions, definitionChanged, changedNodeIds, unreplayableNodeIds, redactedInputs }(ManageWorkflows)POST /workflow-runs/{runId}/rerun— body{ fromNodeId, confirmEffects }: start arerunrun of the current definition that carries unchanged earlier steps (ManageWorkflows). 202{ runId, workflowId, status, rerunOfRunId }withLocation; 409run_active,nothing_to_rerun(withreason) oreffect_confirmation_required(witheffectfulReexecutions)GET|PUT|DELETE /workflows/{id}/sample-input— read, pin or clear the workflow's sample input (owner or Admin;PUTandDELETEneed ManageWorkflows).PUTtakes{ data, triggerData }or{ fromRunId }; at most 64 KB.GETanswers 204 when none is pinned
Pin a sample, then start a run with it:
curl -X PUT https://gw.example.com/api/workflows/web-digest/sample-input \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "triggerData": { "url": "https://example.com/news" } }'
curl -X POST https://gw.example.com/api/workflows/web-digest/runs \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "useSampleInput": true }'{ "runId": "wfr_3f0c9a1e5b7d4c2a8e6f1b0d9c7a5e3f", "workflowId": "web-digest", "status": "pending" }The status is 202. Follow the run with GET /api/workflow-runs/{runId} or the WorkflowRunUpdated hub event.
Skills
GET /skills— installedPOST /marketplace/install— install a marketplace package by nameDELETE /skills/{name}GET /skills/{name}— manifest + detailsPOST /skills/author— generate via LLMPOST /skills/{name}/enable/DELETE /skills/{name}/enable(per-agent)
Plugins (requires Admin role)
GET /plugins— loaded plugins plus current enabled/allowlist stateGET /plugins/{id}— plugin detailPOST /plugins/{id}/restart/POST /plugins/{id}/stop— hot start/stop, no Gateway restartPOST /plugins/scan— rescan plugin directories and load newly installed pluginsPUT /plugins/settings— toggleSophon:Plugins:Enabledand the per-plugin allowlist (hot-reloaded)
Documents
POST /documents/upload— multipart/form-dataPOST /documents/ingest-url— save a URL as a document (SSRF-guarded; HTML becomes a readable doc, files are saved as-is)GET /documents— paginated, filterableGET /documents/{id}— metadata + extracted textGET /documents/{id}/download— original filePOST /documents/{id}/summarizePOST /documents/{id}/ask— grounded Q&A over one document; answers carry[n]citations resolved intocitations[]POST /documents/ask— grounded Q&A across the whole library (grounded: falsewhen nothing relevant is found)PUT /documents/{id}/content— replace content in place: same id, previous revision archived, version bumped, text re-extractedGET /documents/{id}/versions— version historyGET /documents/{id}/versions/{version}/download— download a specific archived versionDELETE /documents/{id}
Channels
GET /channels— list configuredPOST /channels— addGET|PATCH|DELETE /channels/{id}POST /channels/{id}/test
Connections
GET /connectionsPOST /connections/{service}/authorize— start OAuth flowGET /connections/{service}/callback— OAuth callbackPOST /connections— API key / manual credentialsGET|DELETE /connections/{id}POST /connections/{id}/testPOST /connections/{id}/rotate
Cron jobs
GET|POST /cronGET|PATCH|DELETE /cron/{id}POST /cron/{id}/triggerPOST /cron/{id}/pause/POST /cron/{id}/resumeGET /cron/{id}/history
Webhooks
GET /webhooks— the tenant's registrations (workflow-target registrations only for their creator and Admins)POST /webhooks— create an inbound or outbound registration. Since v2.2.0 an inbound one can taketarget: "workflow:{id}"(see Webhooks)GET|PUT|DELETE /webhooks/{id}POST /webhooks/{id}/testGET /webhooks/{id}/history— recent deliveriesPOST /webhooks/{id}/toggle— enable or disablePOST /webhooks/in/{slug}— the inbound endpoint senders post to (anonymous; outside/api; authenticated by the registration's bearer token, HMAC signature or custom header)
Since v2.2.0 every /api/webhooks/{id} route answers a bodiless 404 for an unknown id or another tenant's registration, and failures are { error, message } (the message used to be in error), with codes such as INVALID_TARGET, TARGET_CONFLICT, WEBHOOK_AUTH_REQUIRED, TARGET_NOT_FOUND, not_workflow_owner and trigger_mismatch.
Tasks
GET /tasks/activeGET /tasks/historyGET /tasks/{id}POST /tasks/{id}/cancel
Canvas
GET /canvas?session=— list canvases in a sessionGET /canvas/{id}POST /canvas/{id}/forkGET /canvas/{id}/export— zip of filesDELETE /canvas/{id}
Claude Code
GET|POST /claude-codeGET|DELETE /claude-code/{id}POST /claude-code/{id}/messages— send a messageGET /claude-code/{id}/events— event stream (SSE)POST /claude-code/{id}/exec— shell commandGET /claude-code/{id}/export— zip of project
Discussions (removed in v2.2.0)
Discussions were removed in v2.2.0 with no replacement. Every route under /api/discussions answers 410 { "error": "feature_removed", "message": "Discussions were removed in Sophon v2.2.0." }, except GET /discussions/runs/active, /runs, /definitions and /templates, which answer [] so older apps show an empty list. Those four go away in v2.3.0. GET /home no longer returns activeDiscussions.
Insights
GET /insights/metrics?window=GET /insights/summaryGET /insights/cardsPOST /insights/cards/{id}/dismissPOST /insights/query
Approvals
GET /approvals— pendingGET /approvals/{id}POST /approvals/{id}/approvePOST /approvals/{id}/edit— approve with modificationsPOST /approvals/{id}/rejectGET /approvals/history
Info requests
Structured questions an agent asks mid-task (the ask tool). Pending questions are in-memory; history persists as session events.
GET /info-requests/pending?sessionId=— pending questions (used to recover question cards after reconnect)POST /info-requests/{id}/respond— answer a pending question when the SignalR connection is down
Voice
Capabilities
GET /voice/capabilities— the one call that answers "what can this server do for voice right now"
It returns availability flags plus the full provider lists:
| Field | Meaning |
|---|---|
nativeInputSupported / nativeOutputSupported | The client may use its own speech recognition and speech synthesis — always true; voice works with no provider configured |
serverTranscriptionAvailable | At least one speech-to-text provider is active and healthy |
providerSpeechAvailable | At least one text-to-speech provider is active and healthy |
handsFreeSupported | Server-side hands-free listening is available — computed from the active speech-to-text count, because any active provider can be endpointed. It says nothing about the Dashboard's provider-free browser path, which works without one |
sttProviders / ttsProviders | Every configured provider, each with status, vendor, streaming support and (for speech-to-text) supportsEndpointing and languages |
singleVendorOptions | Vendors that are active on both sides, for clients that want one vendor end to end |
status is active, inactive or error. That is what lets a client tell three states apart that used to look alike: a provider that is not configured is simply absent from the list; one that is configured but failing its health checks is present with status: "error" and excluded from the availability booleans; a healthy one is active. A provider is only marked failing after repeated failed health checks, so the status lags a real outage — see Voice.
Preferences (per user)
GET|PUT /voice/preferences— language, speed, input/output mode, default provider, conversation mode, silence and inactivity limits, and the personal speech-to-text overridesGET|PUT /voice/settings— compatibility alias for the same handlers
PUT replaces the stored preferences, so read-modify-write: send back every field you were given, with your changes applied.
Transcription
POST /voice/transcribe—multipart/form-data, one audio file (the first file in the form). Up to 10 MB;audio/*, or a.wav,.mp3,.m4a,.ogg,.webmor.flacextension. Returns{ text }. Answers 503transcription_unavailablewhen no provider can serve it, 502transcription_failedwhen the provider errorsPOST /voice/transcriptions— alias for the same handler
Text-to-speech providers (writes require Admin)
GET /voice/providers— id, name, type, voice, priority,status, last health checkPOST /voice/providers— add a provider (Admin)DELETE /voice/providers/{id}— remove a provider (Admin)GET /voice/providers/{id}/voices?language=— the provider's voice catalogPATCH /voice/providers/{id}/voice— set which voice this provider speaks with (Admin)POST /voice/providers/{id}/test— health check; returns{ healthy, error }(Admin)POST /voice/providers/{id}/synthesize-test— synthesize a sample line and return it as base64 audio (Admin)
Speech-to-text providers and host defaults
GET /stt/providers— configured speech-to-text providersPOST /stt/providers— add a provider (Admin)DELETE /stt/providers/{id}— remove a provider (Admin)POST /stt/providers/{id}/test— health check (Admin)GET /stt/providers/{id}/languages— the provider's language listGET /stt/settings— host-wide listening defaults (default provider, interim results, endpointing, maximum utterance)PUT /stt/settings— update those defaults (Admin). Per-user overrides live on/voice/preferencesinstead
Node voice runtime (Admin; 403 otherwise)
GET /voice/runtime/nodes— voice runtimes across paired nodesGET|PUT /voice/runtime/nodes/{id}— read or configure one node's voice runtimePOST /voice/runtime/nodes/{id}/start— start a talk session. Body:{ agentId, sessionId }, both optional but the object itself required. A session the node's owner does not own is ignored and a fresh one is startedPOST /voice/runtime/nodes/{id}/stop/POST /voice/runtime/nodes/{id}/interrupt
Node-token routes (off by default)
GET /nodes/me/voice/runtime,POST /nodes/me/voice/state,POST /nodes/me/voice/wake
These three authenticate with a node token, and all three answer 404 until an operator sets Sophon:Voice:NodeWake:Enabled=true. The check runs before authentication, so a disabled Gateway never reveals whether a token is valid. With the feature on, /wake additionally requires the node's voice permission, is rate-limited per node and rejects an over-long transcript. No shipped client calls these routes; nodes do not listen on their own. See Voice.
Home feed
GET /home— composed home feed (hero, insights, thought, summary, on-this-day, active tasks)
Sophon Node
GET /nodes— paired nodesGET /nodes/pending— nodes awaiting approvalGET /nodes/{id}— describe one nodePOST /nodes/{id}/approve/POST /nodes/{id}/revokePUT /nodes/{id}/permissions— set permission scopesPOST /nodes/{id}/rotate-token— issue a fresh node tokenGET|POST /nodes/{id}/commands— list or enqueue a commandGET /nodes/commands/{commandId}/wait— long-poll for a command resultPOST /nodes/commands/{commandId}/cancelGET /nodes/{id}/audit— the node's command audit trailGET /nodes/{id}/crashes— crash reports from the nodeGET /nodes/{id}/settings— new in 2.2 (Device Settings & Confirmations): the device's managed settings (folders and confirmations) as desired and as reported, with arevision(owner or admin)PUT /nodes/{id}/settings— new in 2.2: change them, e.g.{ "baseRevision": 7, "confirmations": { "enabled": true } }. The owner may loosen; an admin may only tighten. 409stale_revisionwhen someone saved first, 409confirmations_lockedwhile the device is locked, 403owner_required, 403confirmations_off_disabledPUT /nodes/{id}/display-name— new in 2.2: body{ "displayName": "…" }, at most 80 characters (owner or admin)GET /nodes/{id}/settings/confirmations?limit=— new in 2.2: the device's recent confirmation outcomes, newest first,limit1-50 (owner or admin)POST /nodes/pairing/request— start pairingGET /nodes/pairing/{nodeId}/status— poll pairing state (node-side, unauthenticated)
Node-token routes, called by the node itself rather than by a user: GET /nodes/me, POST /nodes/me/heartbeat, GET /nodes/me/commands, POST /nodes/me/commands/{commandId}/progress, POST /nodes/me/commands/{commandId}/complete, POST /nodes/me/crashes, and GET /nodes/update-manifest. The command queue is reachable over plain HTTP, but the shipped node takes its commands over the hub.
MCP
GET|POST /mcp/servers— client-side MCP server registrationsGET|PATCH|DELETE /mcp/servers/{id}POST /mcp/servers/{id}/testGET /mcp/servers/{id}/toolsGET /mcp/server/status— own server statusGET|PUT /mcp/server/configGET|POST /mcp/server/tokensDELETE /mcp/server/tokens/{id}GET /mcp/sse/GET /mcp/http— transport endpoints (MCP clients connect here; not for general REST callers)
Push notifications
POST /push/devices— registerGET /push/devicesDELETE /push/devices/{id}GET|PUT /push/devices/{id}/preferencesPOST /push/test
Admin (requires Admin role)
GET|POST /admin/usersGET|PATCH|DELETE /admin/users/{id}POST /admin/users/{id}/logoutGET|POST /admin/rolesGET|PATCH|DELETE /admin/roles/{id}GET /admin/audit?filter=...GET /admin/audit/exportGET|POST /admin/licensePOST /admin/license/verifyGET|POST /admin/onboarding— remote-access tickets
Tenants (Enterprise)
GET|POST /admin/tenantsGET|PATCH|DELETE /admin/tenants/{id}GET /admin/tenants/{id}/users— tenant membershipPOST /admin/tenants/{id}/users— assign userPOST /admin/tenants/{id}/exportPOST /admin/tenants/import
Operations (Operator/Admin)
GET /ops/health— deep health checkGET /ops/system— resource usagePOST /ops/pause/POST /ops/resume/POST /ops/drainPOST /ops/services/{name}/restartPOST /ops/caches/{name}/flushPOST /ops/diagnostics/runGET /ops/diagnostics/bundle
Compliance
POST /compliance/reports— generateGET /compliance/reports/{id}GET /compliance/reports/{id}/downloadPOST /compliance/dsar— data subject access requestGET|POST /compliance/retentionPOST /compliance/access-reviews
Backup (requires ManageSettings — backups contain every user's data)
POST /backup— create a full data-directory backup; asynchronous: returns 202 Accepted (409 if one is already running)GET /backup/status— progress of the current / result of the last backup runGET /backup— list backupsDELETE /backup/{name}— delete a backup (strict name validation)
Public
GET /health— shallow health (load balancers)GET /versionGET /tools— available tool catalog
Pagination
List endpoints support offset or cursor pagination (depending on resource):
GET /memory/entries?limit=50&cursor=<opaque>Response:
{
"items": [...],
"nextCursor": "eyJpZCI6Im1lbV94eXoiLCJ...",
"hasMore": true
}Cursor tokens are opaque — don't parse them, just pass them back.
Error format
{
"error": {
"code": "not_authorized",
"message": "Missing required permission: ManageWorkflows",
"details": { "permission": "ManageWorkflows" },
"requestId": "req_abc123"
}
}Common codes:
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Malformed body / params |
| 401 | unauthenticated | Missing / expired token |
| 403 | not_authorized | Missing permission / tenant mismatch |
| 404 | not_found | Resource doesn't exist or you can't see it |
| 409 | conflict | Resource state conflict (e.g., pair already complete) |
| 410 | feature_removed | The feature was removed (since v2.2.0: /api/discussions/*) |
| 413 | payload_too_large | Over upload / body size limit |
| 422 | validation_failed | Schema validation error |
| 429 | rate_limited | Hit a rate limit (headers include Retry-After) |
| 429 | too_many_runs | A workflow run start over the owner's or tenant's active-run cap |
| 500 | internal_error | Unexpected |
| 502 | upstream_unavailable | LLM provider / external service failed |
| 503 | service_unavailable | Gateway in drain mode |
Newer route groups (models and routing, embeddings, graph runs, and since v2.2.0 workflows and workflow runs, node settings, agent packages and webhooks) answer with a flat body instead: { "error": "<code>", "message": "<sentence>" }. Read the code from error, and show message to people.
A browser request to /hubs/*, /mcp/*, or a POST, PUT, PATCH or DELETE under /api/* gets 403 origin_not_allowed when its Origin is not the Gateway's own address, a built-in development origin, or an entry in Sophon:Security:AllowedOrigins. Clients that send no Origin header (the CLI, scripts, Sophon Node) are not affected. See Configuration.
Include X-Sophon-Request-Id with support tickets.
Rate limits
Default per-user rate limits (configurable):
| Category | Limit |
|---|---|
| Read-heavy (GET list / describe) | 120/min |
| Write-heavy (POST, PATCH, DELETE) | 60/min |
| Approval / cancel | 30/min |
| Expensive (doc upload, backup, DSAR) | 10/min |
| Send message / chat | 60/min |
Exceeding limits returns 429 with Retry-After header. Limits are per-user; API tokens have separate per-token limits.
Content types
- Requests:
application/jsonunless otherwise noted - Responses:
application/json - Uploads:
multipart/form-datafor files - Event streams (Claude Code):
text/event-stream(SSE)
Tenant context
For multi-tenant deployments, specify tenant via:
X-Sophon-Tenant: acmeOr use tenant-scoped URL prefixes:
/api/tenants/acme/workflowsSee Tenants.
OpenAPI
The Gateway exposes Swagger / OpenAPI at:
https://<gateway>/swagger
https://<gateway>/swagger/v1/swagger.jsonUse this to generate SDKs in any language:
npx @openapitools/openapi-generator-cli generate \
-i https://gw.example.com/swagger/v1/swagger.json \
-g typescript-fetch \
-o ./sdk