SOIT Docs
API Reference

API Reference Overview

A capability-oriented map of SOIT API surfaces.

SOIT APIs are grouped by capability under /api/v1. This reference is a high-level map with the main endpoint families per capability — for exact request schemas, use the generated OpenAPI docs at http://localhost:9200 when running SOIT locally.

API surfaces

PrefixCapabilityReference page
/v1, /api/v1/tools, /mcpOpenAI-compatible gateway, direct tool calls, MCP serverGateway, Tools, and MCP API
/api/v1/agentsAgent definitions, versions, releases, executionAgents API
/api/v1/threads, /api/v1/responsesConversations and response executionThreads and Responses API
/api/v1/workflowsWorkflow graphs, versions, execution controlWorkflows API
/api/v1/knowledgeKnowledge bases, documents, indexes, queryKnowledge API
/api/v1/runs, /api/v1/tasks, /api/v1/observe, /api/v1/exportsRuntime ledger, observe views, evidence bundles, and ledger exportsRuns, Tasks, and Observe API
/api/v1/evaluationsRegression runs and reportsEvaluation API
/api/v1/notificationsNotification records and read stateNotifications API
/api/v1/pluginsPlugin lifecycle, artifacts, runtime registryPlugins API
/api/v1/modelhubProviders, model catalog, diagnosticsModelHub API
/api/v1 (identity routes)Auth, tenants, workspaces, API keys, service principalsIdentity API
/api/v1/security, /api/v1/secretsEgress policy, usage limits, secret referencesSecurity and Secrets API
/api/v1/billingBudgets and their statusBudgets and Cost
/api/v1/diagnosticsLive diagnostics for workspace owners, showing the edition and license from v1.4.0; the telemetry report at /diagnostics/telemetry for tenant admins (new in v1.4.0)Editions and Licenses, Telemetry

Conventions

All endpoints share the platform conventions:

  • Envelope — responses under /api/v1 carry success, code, message, data, request_id, and run_id (when execution occurred). Routes under /v1 answer in OpenAI's shapes instead, and /mcp and /.well-known/* in their protocols' own shapes.
  • Authentication — an API key is accepted as Authorization: Bearer sk_… or in X-API-Key.
  • Rate limits — a call refused by a rate limit or a daily quota answers 429 with a Retry-After header and the code RATE_LIMIT_EXCEEDED.
  • Scoping — tenant and workspace resolve from authentication context and headers, never from request parameters.
  • Pagination — cursor-based: page_size / page_token in, items / next_page_token out.
  • Idempotency — write APIs support an Idempotency-Key header.
  • Health — GET /health, /health/ready, /health/live, and /metrics are unversioned.

Versioning and Release

Use immutable versions and release pointers for SOIT agents, workflows, plugins, and other capabilities.

Gateway, Tools, and MCP API

API surface for the OpenAI-compatible /v1 gateway, the Anthropic Messages API, direct tool calls, and the /mcp endpoint.

On this page

API surfacesConventions