Skip to Content
Sophon Docs
API Reference

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>/api

Default Gateway port in development: 8080.

Authentication

ModeUsed byHeader
JWT BearerDashboard, CLI after sophon login, MobileAuthorization: Bearer <jwt>
API tokensCI, scripts, long-lived integrationsAuthorization: Bearer sk_...
OIDC SSOEnterprise SSO-configured deploymentsJWT from IdP after OIDC exchange
No authPersonal 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 → JWT
  • POST /auth/logout — revoke current session
  • POST /auth/refresh — renew JWT before idle timeout
  • POST /auth/tokens — create API token
  • GET /auth/me — current user info
  • GET /auth/sessions — active sessions for current user
  • DELETE /auth/sessions/{id} — revoke a session

Agents

  • GET /agents / POST /agents / GET|PATCH|DELETE /agents/{id}
  • GET|PUT /agents/{id}/soul — read/write SOUL.md
  • GET|PUT /agents/{id}/boot — BOOT.md
  • GET|PUT /agents/{id}/heartbeat — HEARTBEAT.md
  • GET|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-agent file: multipart/form-data, one file field package, at most 1 MiB
  • POST /agent-packages/prepared/{token}/commit — body { agentId, allowDelegationFrom, replace }: install the prepared package. 201 with Location: /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 package
  • GET /agents/{id}/marketplace?check= — the agent's package origin and update status
  • POST /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/status and POST /marketplace/updates/apply gain agentUpdates, lastAgentRun, agentIds and agentResults

Export and publish

  • POST /agents/{id}/export?dryRun= — the agent as a .sophon-agent file (application/zip), or with dryRun=true a preview of the package
  • POST /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 — list
  • GET /sessions/{id} — describe
  • GET /sessions/{id}/messages — message history
  • POST /sessions/{id}/fork — fork a session
  • DELETE /sessions/{id} — delete
  • GET /sessions/{id}/events?window=&afterSequence=&limit=&types= — a bounded slice of the session's events, oldest first. window=oldest (the default) pages forward from afterSequence; window=latest returns the newest limit events, which is what a client rebuilding plan cards after a reload needs. Any other window is 400 invalid_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 providers
  • POST /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; 404 provider_not_found, 400 model_not_found, 409 provider_disabled
  • PUT /models/{id}/enabled — body { "enabled": true|false } (ManageModels). A body without enabled is 400 invalid_request, so an empty body never disables a provider
  • PUT /models/{id}/priority — body { "priority": n }, n of 1 or more (ManageModels). Priority orders providers after the default; it no longer picks the default
  • POST /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: [] or usageHint: "" clears it. contextWindow must be 256 to 10,000,000 and usageHint at most 64 characters. 204; 400 invalid_request; 404 provider_not_found
  • GET /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. 502 discovery_failed when the server does not answer within 10 seconds. Discovery never changes routing
  • GET /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 key
  • GET /models/routing — the retry policy and the failover order. This is a static snapshot: its fallbackEnabled does 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=true adds each role's chain: every layer the router checked, which one won, and what it shadowed
  • PUT /sessions/{id}/model-routing — body { v: 1, expectedSeq, layer, client, allowUnlistedModel }. expectedSeq makes the write compare-and-set (409 seq_conflict when the chat changed since you read it); leave it null for last write wins. A sub-agent or plan-step session is 409 activity_child: change its parent instead
  • GET|PUT /agents/{id}/model-routing — an agent's routing policy, stored in its agent.json. An inherit layer with no roles clears it
  • GET|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 ceiling
  • PUT /models/routing-defaults — body { v: 1, layer, localOnly } (ManageModels). mode must be auto or inherit; the host cannot pin. localOnly is required, so an omitted flag never lifts the ceiling. The write goes to config/appsettings.user.json, and from then on that file wins over SOPHON__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, off or degraded) with its reason, vectorStore (sqlite, qdrant or none) and vectorStoreState (ready, breakerOpen or none), embedderState (active, breakerOpen, unavailable or none), semanticSearchAvailable, pending (a cloud embedder waiting for consent), suggestion, and the background reindex job. Error text is shown to admins only
  • PUT /models/embeddings/settings — choose the embedder: body { mode, providerId, model, dimensions, preferLocal, test, startReindex }. mode is auto, local, provider or off. Under provider, one fixed text is embedded first unless test is false; a failed test is 422 embedding_test_failed and nothing is saved. An unknown provider is 404 provider_not_found. Saving writes Sophon:Embeddings to config/appsettings.user.json, which then wins over SOPHON__Embeddings__* environment variables. Saving a cloud provider here counts as consent
  • POST /models/embeddings/test?providerId=&model=&dimensions= — embed one fixed text and probe the vector store. A failed test is 200 with ok: false
  • GET /models/embeddings/consent?logDays= — the cloud embedder waiting for consent and how many memories, daily logs (last logDays days, default 30) and documents it would receive
  • POST /models/embeddings/consent?providerId=&startReindex=&logDays= — record an admin's consent. With nothing waiting and no providerId, 409 nothing_to_consent. A local provider is 400: it needs no consent
  • POST /models/embeddings/reindex?confirm=&logDays= — start the backlog for the active embedder. A cloud embedder needs confirm=true; without it the answer is 409 confirmation_required, and the message gives the counts that would be sent
  • DELETE /models/embeddings/reindex — cancel the running reindex (404 not_running when none runs)
  • POST /models/embeddings/rebuild?logDays= — drop and recreate the active embedder's collections and re-embed every user of every tenant. 202; 409 rebuild_running
  • POST /models/embeddings/install-local?providerId=&model= — ask a configured Ollama to pull an embedding model (default nomic-embed-text). Progress is in status.install. One install at a time (409 install_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 (409 collection_active), and neither can any collection while a reindex runs (409 reindex_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=plan keeps chat plans only. limit defaults to 50 (1 to 200). Each summary has status, interruptReason, costUsd and retryOfRunId
  • GET /graph-runs/{id} — the run, its node runs, its current plan, and a retry block: eligible, reason, message, kind (retry, budget or null), the step ids that would run again (rerunNodeIds), be kept (carriedNodeIds) or stay blocked (blockedNodeIds), effectful, and for a budget stop budget { spentUsd, capUsd, tokens, tokenCap } (null otherwise). The run adds continuationRunId
  • POST /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 503 host_stopping
  • POST /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 with Location: /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 with created: 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 503 host_stopping
  • POST /graph-runs/{id}/cancel — durable cancel, recorded as a user stop. It also stops a paused run. 200 { id, status: "cancelling" }; 409 already_terminal
  • POST /graph-runs/{id}/save-as-workflow — export a Completed or Failed run as a workflow; 409 not_saveable otherwise

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); add includeSuperseded=true to also return superseded (historical) facts
  • POST /memory/entries — create; optional supersedes: "mem_..." marks an existing entry as superseded by the new one
  • PUT|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 id
  • GET /memory/graph/mermaid — Mermaid export of the overview graph (same filters, plus direction=LR|TD and includeEntries)
  • GET /memory/entities/duplicates?threshold=&limit= — candidate duplicate entity pairs
  • POST /memory/entities/{id}/merge — merge a duplicate entity into a survivor
  • POST /memory/entities/duplicates/{pairKey}/dismiss — dismiss a candidate pair
  • POST /memory/vectors/reindex — purge and rebuild the current user's memory vectors
  • GET /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 workflows
  • GET /workflows/{id} — one workflow
  • POST /workflows — create or update (upsert by id; ManageWorkflows). 201 on create, 200 on update, with the stored definition plus issues (its warnings). 400 workflow_invalid with errors and issues; 409 workflow_id_unavailable. version, createdBy, ownerId, updatedBy, updatedAt, tenantId and sampleInput in the body are ignored
  • POST /workflows/validate — new in 2.2: the issues a save of the body would return, { valid, issues }; nothing is stored (ManageWorkflows). 413 payload_too_large over 1 MiB
  • DELETE /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); 204
  • POST /workflows/{id}/owner — body { "userId": "…" }: transfer ownership to a user of the tenant, by the owner or an Admin (ManageWorkflows); 204
  • POST /workflows/from-template — create a switched-off copy of a shipped template (ManageWorkflows); 201 with issues
  • GET /workflow-templates, GET /workflow-templates/{id} — the shipped templates
  • POST /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 a manual run in the background (ManageWorkflows, owner or Admin). Body (optional) { data, triggerData, agentId, useSampleInput }. 202 { runId, workflowId, status } with Location: /api/workflow-runs/{runId}. 400 bad_request for useSampleInput without a pinned sample
  • POST /workflows/{id}/execute — start a manual run and wait for it to end (ManageWorkflows). Answers workflowId, success, nodeResults, error, startedAt, completedAt, then runId, status, triggerKind, durationMs
  • POST /workflows/{id}/webhook — start a webhook run with the body as $trigger.data (ManageWorkflows, owner or Admin; a signed-in caller, not anonymous). 409 trigger_mismatch unless the workflow is enabled with a webhook trigger. ?async=true answers 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}/runs and GET /workflow-runs — root runs, newest first, as { items, nextCursor }. Query: status, trigger, before (cursor), limit (1-100, default 20); /workflow-runs also takes workflowId and latestPerWorkflow=true. Test runs are hidden unless trigger=test. 400 invalid_query
  • GET /workflow-runs/{runId} — { run, nodeRuns, definition, input, triggerData, finalVariables, children, parent, canWrite, nodeRunsOmitted }. definition, input, triggerData, finalVariables and each step's resolved inputs are null unless canWrite (the run's user or an Admin). At most 1000 step runs; the rest are counted in nodeRunsOmitted
  • GET /workflow-runs/{runId}/node-runs?after=&limit= — every step run by sequence, { items, nextCursor }, limit 1-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; 404 run_not_found; 409 run_not_active; 503 run_busy with Retry-After: 1
  • GET /workflows/{id}/history, GET /workflows/{id}/history/latest — finished root runs in the v2.1 history shape plus runId, status, triggerKind and durationMs; ?limit 1-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 a test run (ManageWorkflows). Body: the node, plus workflowId and fromRunId to bind it to a saved workflow and seed it from a run, mockOutputs, variables, triggerData, input, useSampleInput and confirmEffects. 200 { nodeId, success, output, error, result, testRunId, resolvedInputs, unresolvedReferences, effect }. 400 not_testable for Approval, Info request, Loop, Sub-workflow and long Wait steps; 409 effect_confirmation_required for an effectful step unless "confirmEffects": true; 413 payload_too_large over 256 KB
  • GET /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 a rerun run of the current definition that carries unchanged earlier steps (ManageWorkflows). 202 { runId, workflowId, status, rerunOfRunId } with Location; 409 run_active, nothing_to_rerun (with reason) or effect_confirmation_required (with effectfulReexecutions)
  • GET|PUT|DELETE /workflows/{id}/sample-input — read, pin or clear the workflow's sample input (owner or Admin; PUT and DELETE need ManageWorkflows). PUT takes { data, triggerData } or { fromRunId }; at most 64 KB. GET answers 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 — installed
  • POST /marketplace/install — install a marketplace package by name
  • DELETE /skills/{name}
  • GET /skills/{name} — manifest + details
  • POST /skills/author — generate via LLM
  • POST /skills/{name}/enable / DELETE /skills/{name}/enable (per-agent)

Plugins (requires Admin role)

  • GET /plugins — loaded plugins plus current enabled/allowlist state
  • GET /plugins/{id} — plugin detail
  • POST /plugins/{id}/restart / POST /plugins/{id}/stop — hot start/stop, no Gateway restart
  • POST /plugins/scan — rescan plugin directories and load newly installed plugins
  • PUT /plugins/settings — toggle Sophon:Plugins:Enabled and the per-plugin allowlist (hot-reloaded)

Documents

  • POST /documents/upload — multipart/form-data
  • POST /documents/ingest-url — save a URL as a document (SSRF-guarded; HTML becomes a readable doc, files are saved as-is)
  • GET /documents — paginated, filterable
  • GET /documents/{id} — metadata + extracted text
  • GET /documents/{id}/download — original file
  • POST /documents/{id}/summarize
  • POST /documents/{id}/ask — grounded Q&A over one document; answers carry [n] citations resolved into citations[]
  • POST /documents/ask — grounded Q&A across the whole library (grounded: false when nothing relevant is found)
  • PUT /documents/{id}/content — replace content in place: same id, previous revision archived, version bumped, text re-extracted
  • GET /documents/{id}/versions — version history
  • GET /documents/{id}/versions/{version}/download — download a specific archived version
  • DELETE /documents/{id}

Channels

  • GET /channels — list configured
  • POST /channels — add
  • GET|PATCH|DELETE /channels/{id}
  • POST /channels/{id}/test

Connections

  • GET /connections
  • POST /connections/{service}/authorize — start OAuth flow
  • GET /connections/{service}/callback — OAuth callback
  • POST /connections — API key / manual credentials
  • GET|DELETE /connections/{id}
  • POST /connections/{id}/test
  • POST /connections/{id}/rotate

Cron jobs

  • GET|POST /cron
  • GET|PATCH|DELETE /cron/{id}
  • POST /cron/{id}/trigger
  • POST /cron/{id}/pause / POST /cron/{id}/resume
  • GET /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 take target: "workflow:{id}" (see Webhooks)
  • GET|PUT|DELETE /webhooks/{id}
  • POST /webhooks/{id}/test
  • GET /webhooks/{id}/history — recent deliveries
  • POST /webhooks/{id}/toggle — enable or disable
  • POST /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/active
  • GET /tasks/history
  • GET /tasks/{id}
  • POST /tasks/{id}/cancel

Canvas

  • GET /canvas?session= — list canvases in a session
  • GET /canvas/{id}
  • POST /canvas/{id}/fork
  • GET /canvas/{id}/export — zip of files
  • DELETE /canvas/{id}

Claude Code

  • GET|POST /claude-code
  • GET|DELETE /claude-code/{id}
  • POST /claude-code/{id}/messages — send a message
  • GET /claude-code/{id}/events — event stream (SSE)
  • POST /claude-code/{id}/exec — shell command
  • GET /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/summary
  • GET /insights/cards
  • POST /insights/cards/{id}/dismiss
  • POST /insights/query

Approvals

  • GET /approvals — pending
  • GET /approvals/{id}
  • POST /approvals/{id}/approve
  • POST /approvals/{id}/edit — approve with modifications
  • POST /approvals/{id}/reject
  • GET /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:

FieldMeaning
nativeInputSupported / nativeOutputSupportedThe client may use its own speech recognition and speech synthesis — always true; voice works with no provider configured
serverTranscriptionAvailableAt least one speech-to-text provider is active and healthy
providerSpeechAvailableAt least one text-to-speech provider is active and healthy
handsFreeSupportedServer-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 / ttsProvidersEvery configured provider, each with status, vendor, streaming support and (for speech-to-text) supportsEndpointing and languages
singleVendorOptionsVendors 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 overrides
  • GET|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, .webm or .flac extension. Returns { text }. Answers 503 transcription_unavailable when no provider can serve it, 502 transcription_failed when the provider errors
  • POST /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 check
  • POST /voice/providers — add a provider (Admin)
  • DELETE /voice/providers/{id} — remove a provider (Admin)
  • GET /voice/providers/{id}/voices?language= — the provider's voice catalog
  • PATCH /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 providers
  • POST /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 list
  • GET /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/preferences instead

Node voice runtime (Admin; 403 otherwise)

  • GET /voice/runtime/nodes — voice runtimes across paired nodes
  • GET|PUT /voice/runtime/nodes/{id} — read or configure one node's voice runtime
  • POST /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 started
  • POST /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 nodes
  • GET /nodes/pending — nodes awaiting approval
  • GET /nodes/{id} — describe one node
  • POST /nodes/{id}/approve / POST /nodes/{id}/revoke
  • PUT /nodes/{id}/permissions — set permission scopes
  • POST /nodes/{id}/rotate-token — issue a fresh node token
  • GET|POST /nodes/{id}/commands — list or enqueue a command
  • GET /nodes/commands/{commandId}/wait — long-poll for a command result
  • POST /nodes/commands/{commandId}/cancel
  • GET /nodes/{id}/audit — the node's command audit trail
  • GET /nodes/{id}/crashes — crash reports from the node
  • GET /nodes/{id}/settings — new in 2.2 (Device Settings & Confirmations): the device's managed settings (folders and confirmations) as desired and as reported, with a revision (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. 409 stale_revision when someone saved first, 409 confirmations_locked while the device is locked, 403 owner_required, 403 confirmations_off_disabled
  • PUT /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, limit 1-50 (owner or admin)
  • POST /nodes/pairing/request — start pairing
  • GET /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 registrations
  • GET|PATCH|DELETE /mcp/servers/{id}
  • POST /mcp/servers/{id}/test
  • GET /mcp/servers/{id}/tools
  • GET /mcp/server/status — own server status
  • GET|PUT /mcp/server/config
  • GET|POST /mcp/server/tokens
  • DELETE /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 — register
  • GET /push/devices
  • DELETE /push/devices/{id}
  • GET|PUT /push/devices/{id}/preferences
  • POST /push/test

Admin (requires Admin role)

  • GET|POST /admin/users
  • GET|PATCH|DELETE /admin/users/{id}
  • POST /admin/users/{id}/logout
  • GET|POST /admin/roles
  • GET|PATCH|DELETE /admin/roles/{id}
  • GET /admin/audit?filter=...
  • GET /admin/audit/export
  • GET|POST /admin/license
  • POST /admin/license/verify
  • GET|POST /admin/onboarding — remote-access tickets

Tenants (Enterprise)

  • GET|POST /admin/tenants
  • GET|PATCH|DELETE /admin/tenants/{id}
  • GET /admin/tenants/{id}/users — tenant membership
  • POST /admin/tenants/{id}/users — assign user
  • POST /admin/tenants/{id}/export
  • POST /admin/tenants/import

Operations (Operator/Admin)

  • GET /ops/health — deep health check
  • GET /ops/system — resource usage
  • POST /ops/pause / POST /ops/resume / POST /ops/drain
  • POST /ops/services/{name}/restart
  • POST /ops/caches/{name}/flush
  • POST /ops/diagnostics/run
  • GET /ops/diagnostics/bundle

Compliance

  • POST /compliance/reports — generate
  • GET /compliance/reports/{id}
  • GET /compliance/reports/{id}/download
  • POST /compliance/dsar — data subject access request
  • GET|POST /compliance/retention
  • POST /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 run
  • GET /backup — list backups
  • DELETE /backup/{name} — delete a backup (strict name validation)

Public

  • GET /health — shallow health (load balancers)
  • GET /version
  • GET /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:

HTTPCodeMeaning
400invalid_requestMalformed body / params
401unauthenticatedMissing / expired token
403not_authorizedMissing permission / tenant mismatch
404not_foundResource doesn't exist or you can't see it
409conflictResource state conflict (e.g., pair already complete)
410feature_removedThe feature was removed (since v2.2.0: /api/discussions/*)
413payload_too_largeOver upload / body size limit
422validation_failedSchema validation error
429rate_limitedHit a rate limit (headers include Retry-After)
429too_many_runsA workflow run start over the owner's or tenant's active-run cap
500internal_errorUnexpected
502upstream_unavailableLLM provider / external service failed
503service_unavailableGateway 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):

CategoryLimit
Read-heavy (GET list / describe)120/min
Write-heavy (POST, PATCH, DELETE)60/min
Approval / cancel30/min
Expensive (doc upload, backup, DSAR)10/min
Send message / chat60/min

Exceeding limits returns 429 with Retry-After header. Limits are per-user; API tokens have separate per-token limits.

Content types

  • Requests: application/json unless otherwise noted
  • Responses: application/json
  • Uploads: multipart/form-data for files
  • Event streams (Claude Code): text/event-stream (SSE)

Tenant context

For multi-tenant deployments, specify tenant via:

X-Sophon-Tenant: acme

Or use tenant-scoped URL prefixes:

/api/tenants/acme/workflows

See Tenants.

OpenAPI

The Gateway exposes Swagger / OpenAPI at:

https://<gateway>/swagger
https://<gateway>/swagger/v1/swagger.json

Use 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

Where to go next

  • SignalR — the WebSocket surface for real-time events
  • Webhooks — webhook payloads and signatures
  • CLI — higher-level wrapper over this REST surface