REST API

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

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

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

Memory

• GET /memory/entries — paginated list with filters (scope, category, agent)
• POST /memory/entries — create
• GET|PATCH|DELETE /memory/entries/{id}
• GET /memory/search?q=&scope=&limit=
• POST /memory/entries/{id}/forget — gated via approval
• GET /memory/graph?entity=&depth= — traverse the entity graph
• GET /memory/daily-logs?date=

Workflows

• GET|POST /workflows
• GET|PATCH|DELETE /workflows/{id}
• POST /workflows/{id}/trigger
• POST /workflows/{id}/pause / POST /workflows/{id}/resume
• POST /workflows/{id}/clone
• GET /workflows/{id}/runs
• GET /workflows/{id}/runs/{runId}
• GET /workflows/{id}/history

Skills

• GET /skills — installed
• POST /skills/install — from URL or marketplace 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)

Documents

• POST /documents/upload — multipart/form-data
• GET /documents — paginated, filterable
• GET /documents/{id} — metadata + extracted text
• GET /documents/{id}/raw — original file
• POST /documents/{id}/summarize
• POST /documents/{id}/extract — structured extraction
• POST /documents/compare — multi-doc analysis
• 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|POST /webhooks
• GET|PATCH|DELETE /webhooks/{id}
• POST /webhooks/{id}/test
• GET /webhooks/{id}/deliveries
• POST /webhooks/{id}/deliveries/{deliveryId}/retry
• POST /webhooks/{id}/rotate-secret
• POST /webhooks/receive/{slug} — inbound webhook target

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

• GET|POST /discussions
• GET|PATCH|DELETE /discussions/{id}
• POST /discussions/{id}/runs — start a run
• GET /discussions/{id}/runs — list runs
• GET /discussions/runs/{runId}
• POST /discussions/runs/{runId}/cancel

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

Voice

• GET /voice/providers
• GET /voice/voices?provider=
• POST /voice/speak — synthesize (returns audio stream)
• POST /voice/transcribe — transcribe audio
• GET|PUT /voice/config

Home feed

• GET /home — composed home feed (hero, insights, thought, summary, on-this-day, active tasks)

Sophon Node

• GET|POST /nodes
• GET|PATCH|DELETE /nodes/{id}
• POST /nodes/{id}/approve
• POST /nodes/{id}/scopes
• POST /nodes/{id}/command — execute command
• GET /nodes/me/commands — polled by the node (fallback transport)
• POST /nodes/me/pair — pairing flow
• POST /nodes/me/heartbeat

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

• POST /backup — create
• GET /backup/{id}/status
• GET /backup/{id}/download
• POST /backup/restore
• POST /backup/verify

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:

Include X-Sophon-Request-Id with support tickets.

Rate limits

Default per-user rate limits (configurable):

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