# SOAT > Open-source infrastructure for production-ready AI agents — backend, identity, storage, memory, and orchestration. ## When to use SOAT Reach for SOAT when the job is one of these. Each line names the operation that does it, so the decision and the call are in the same place. - **Give an agent memory that survives the process.** Sessions and conversations persist message history in PostgreSQL. `POST /api/v1/agents/{agent_id}/sessions`, then `POST /api/v1/sessions/{session_id}/messages` and `POST /api/v1/sessions/{session_id}/generate`. - **Ground an agent in your own documents.** Ingest files into chunked, embedded documents and search them with pgvector. `POST /api/v1/documents/ingest`, then `POST /api/v1/knowledge/search`. - **Run multi-step work deterministically instead of hoping one prompt covers it.** Orchestrations are DAGs of agent, tool, and human nodes; workflows are state machines for long-running work. `POST /api/v1/orchestrations/{orchestration_id}/runs`. - **Bound what an agent is allowed to do.** IAM policies gate every action, API keys scope to one project, guardrails screen input and output, and quotas cap spend. `POST /api/v1/policies`, `POST /api/v1/api-keys`, `POST /api/v1/quotas`. - **Put a human in the loop without stopping the run.** Approval nodes and exceptions pause a run, record who decided what, and resume from the same point. `POST /api/v1/approvals/{approval_id}/approve`. - **Prove after the fact what an agent did and what it cost.** Every generation writes a trace with each tool call, model response, and token count, alongside an append-only audit log. `GET /api/v1/traces/{trace_id}/tree`. - **Change an agent in production without guessing whether it got worse.** Agent versions are append-only; a canary release splits traffic, and promotion is gated on a passing eval run. `POST /api/v1/agents/{agent_id}/release`. - **Expose your own backend to an MCP client (Claude, Cursor, VS Code).** Every REST operation is also an MCP tool at `POST /mcp`, behind the same permission engine, with OAuth 2.1 discovery and Dynamic Client Registration. - **Stand up a whole agent stack reproducibly.** Agent Formations declare providers, tools, agents, orchestrations, and webhooks in one template, resolve the dependency graph, and apply it. `POST /api/v1/formations`. ## When not to use SOAT - You need a model. SOAT ships none and hosts none: it calls the provider you configure (OpenAI, Anthropic, Google, Bedrock, Ollama, or any OpenAI-compatible endpoint). - You need one stateless completion and nothing else. Call the provider directly; SOAT earns its place once state, permissions, retrieval, or evidence are involved. - You want a hosted control plane with no infrastructure of your own. SOAT is self-hosted software, not a SaaS — you run the server and the database. ## How an agent should call SOAT - **Surfaces.** One API, four ways in: REST under `/api/v1`, the MCP endpoint at `POST /mcp`, the `@soat/sdk` TypeScript client, and the `soat` CLI. The last three are generated from the same OpenAPI documents, so an operation that exists in one exists in all of them. - **Contract.** Read — every operation, schema, and security scheme in one OpenAPI 3.0 document. MCP tool names are the kebab-cased `operationId`. - **Base URL.** Your own deployment (`http://localhost:5047` out of the box). `soat.ttoss.dev` serves documentation only — there is no API behind it, so do not send calls there. - **Authentication.** Send `Authorization: Bearer `: a project API key (`sk_…`), a user JWT from `POST /api/v1/users/login`, or an OAuth 2.1 access token. OAuth clients discover the server at `/.well-known/oauth-authorization-server` (RFC 8414) and `/.well-known/oauth-protected-resource` (RFC 9728), and can register themselves at `/register` (RFC 7591) with no operator step. - **Field casing.** snake_case on the wire, everywhere — REST, MCP, webhooks, and the audit export. Unknown fields are rejected rather than ignored, so a typo fails loudly. - **Errors.** Every failure answers `{ "error": { "code", "message", "hint", "docs_url", "meta"? } }`. Branch on `code`, act on `hint`. The full catalog is at . - **Long operations.** Anything that can outlast a request takes one toggle, `wait`, defaulting to background: you get `202` (or `201`) plus a handle to poll. Pass `wait=true` to block for the result instead. - **Pagination.** Every list endpoint takes `limit` and `offset` and returns the same envelope, so one paging loop works for all of them. ## Getting access - **Nothing to sign up for.** SOAT is Apache-2.0 licensed and self-hosted. There is no account to create, no key to request, no trial to start, and no quota you have to ask anyone to raise. - **Run the stack.** Copy the Compose file from the quick start and run `docker compose up -d`. It brings up PostgreSQL with pgvector, a local Ollama for models, and the SOAT server on port 5047 — so the whole platform runs offline, with no third-party credential. - **Get the first credential.** `POST /api/v1/users/bootstrap` creates the first admin. It is open only until that admin exists, then closed for good, so the same call cannot be replayed against a running deployment. - **Issue your own API key.** `POST /api/v1/api-keys` (or `soat create-api-key`) mints a project-scoped `sk_…` key with exactly the actions of the policy you attach. Keys are self-serve and rotatable — `POST /api/v1/api-keys/{api_key_id}/rotate`. - **The sandbox is the same software.** There is no separate sandbox tier to request: a local instance is the product, so throwaway projects, seeded data, and destructive tests all run against your own deployment. Delete the volumes to reset. Full agent instructions: ## Table of Contents - [Key Concepts](https://soat.ttoss.dev/docs/getting-started/concepts.md): The mental model behind SOAT and how its core resources — projects, agents, sessions, and more — fit together. - [Quick Start](https://soat.ttoss.dev/docs/getting-started/getting-started.md): Get SOAT running locally with Docker Compose in under five minutes. - [Activity](https://soat.ttoss.dev/docs/modules/activity.md): Cursor-paginated feed of every autonomously executed action, for 'what did agents do today' auditability in SOAT. - [Actors](https://soat.ttoss.dev/docs/modules/actors.md): The Actors module represents people, bots, and external participants within a SOAT project, correlating them with external systems via external_id. - [Agents](https://soat.ttoss.dev/docs/modules/agents.md): Agents are persistent configurations for multi-step AI workflows that run reasoning-and-acting loops with tools in SOAT. - [AI Providers](https://soat.ttoss.dev/docs/modules/ai-providers.md): Register and manage LLM provider configurations — model, base URL, and API-key secret — per project in SOAT. - [API Keys](https://soat.ttoss.dev/docs/modules/api-keys.md): Long-lived programmatic credentials that authenticate as their owning user, optionally scoped to a project, with optional policy restrictions. - [Approvals](https://soat.ttoss.dev/docs/modules/approvals.md): Human-decision approval queue with frozen evidence and server-enforced expiry in SOAT. - [Audit Log](https://soat.ttoss.dev/docs/modules/audit-log.md): Append-only record of who did what to the SOAT platform — one entry per mutating administrative or resource action. - [Chains](https://soat.ttoss.dev/docs/modules/chains.md): Continuation chains — the linked tree of generations a resumed turn grows into, how large it has grown, and the ceilings that stop it. - [Chats](https://soat.ttoss.dev/docs/modules/chats.md): LLM completions with optional persistent configuration, supporting both stateless and per-chat modes in SOAT. - [Conversations](https://soat.ttoss.dev/docs/modules/conversations.md): Multi-party dialogues that group ordered, role-tagged messages with optional actor authorship within a SOAT project. - [Docs](https://soat.ttoss.dev/docs/modules/docs.md): MCP-only tools that give agents direct access to SOAT platform documentation. - [Documents](https://soat.ttoss.dev/docs/modules/documents.md): Store documents with per-chunk embedding vectors for semantic search across project content in SOAT. - [Embeddings](https://soat.ttoss.dev/docs/modules/embeddings.md): Generate numeric vector representations of text using SOAT's configured embedding model. - [Evaluations](https://soat.ttoss.dev/docs/modules/evaluations.md): Evaluations — datasets, scorers, and scored runs that turn 'did this change make the agent better?' into a pass/fail verdict in SOAT. - [Exceptions](https://soat.ttoss.dev/docs/modules/exceptions.md): Triageable failure and anomaly queue with severity, occurrence dedup, and an acknowledge/resolve lifecycle in SOAT. - [Files](https://soat.ttoss.dev/docs/modules/files.md): File upload, download, metadata, and deletion over a pluggable storage backend — local filesystem, S3, or GCS. - [Formations](https://soat.ttoss.dev/docs/modules/formations.md): A CloudFormation-inspired declarative layer that provisions an entire AI agent stack from a single JSON or YAML template. - [Generations](https://soat.ttoss.dev/docs/modules/generations.md): Generation records track individual LLM runs started by agents, including lifecycle status and failure details. - [Guardrails](https://soat.ttoss.dev/docs/modules/guardrails.md): First-class action-class policies that classify each agent tool call — execute, require approval, or block — with non-LLM guard expressions and pro... - [IAM](https://soat.ttoss.dev/docs/modules/iam.md): SOAT's AWS-inspired IAM engine for authentication and fine-grained authorization with Effect, Action, Resource, and Condition policy statements. - [Platform](https://soat.ttoss.dev/docs/modules/modules.md): Overview of SOAT platform modules exposed through the REST API, MCP server, CLI, and SDK. - [Ingestion Rules](https://soat.ttoss.dev/docs/modules/ingestion-rules.md): Route a file content_type to a converter tool so images, audio, and scanned PDFs can be ingested into searchable documents. - [Knowledge](https://soat.ttoss.dev/docs/modules/knowledge.md): Unified semantic search across a project's documents and memory entries, ranked by vector similarity and tagged by source. - [Memories](https://soat.ttoss.dev/docs/modules/memories.md): Named containers for storing and retrieving knowledge entries within a SOAT project. - [Model Routes](https://soat.ttoss.dev/docs/modules/model-routes.md): Ordered provider+model failover for SOAT completions: a named route with retry, per-target timeouts, and a circuit breaker, recorded on the generat... - [OAuth](https://soat.ttoss.dev/docs/modules/oauth.md): SOAT as a first-party OAuth 2.1 Authorization Server for its MCP endpoint. - [Orchestrations](https://soat.ttoss.dev/docs/modules/orchestrations.md): DAG-based pipeline definitions that chain agents, tools, and knowledge lookups into repeatable pipelines. - [Policies](https://soat.ttoss.dev/docs/modules/policies.md): Global, reusable IAM policy documents attached to users and API keys, defining fine-grained rules evaluated at request time. - [Projects](https://soat.ttoss.dev/docs/modules/projects.md): Multi-tenant namespaces in SOAT; every document, file, actor, and conversation belongs to a project. - [Quotas](https://soat.ttoss.dev/docs/modules/quotas.md): Hard, fail-closed enforcement of request rates and token/cost budgets per project, API key, agent, or end user in SOAT. - [Secrets](https://soat.ttoss.dev/docs/modules/secrets.md): Encrypted storage for sensitive values such as API keys and credentials in SOAT. - [Sessions](https://soat.ttoss.dev/docs/modules/sessions.md): A simplified one-user-to-one-agent conversational interface owned by an agent. - [Tools](https://soat.ttoss.dev/docs/modules/tools.md): Standalone, reusable tool definitions that SOAT agents call during generation. - [Traces](https://soat.ttoss.dev/docs/modules/traces.md): Traces record the full execution history of agent generations — every reasoning step and tool call. - [Triggers](https://soat.ttoss.dev/docs/modules/triggers.md): Bind a starter — manual, webhook, schedule, or event — to an executable target in SOAT. - [Usage](https://soat.ttoss.dev/docs/modules/usage.md): Usage events record the cost of every metered occurrence — a completed LLM call, an orchestration node's compute, API requests, and stored bytes — ... - [Users](https://soat.ttoss.dev/docs/modules/users.md): Human identities within a SOAT instance, authenticated via username and password. - [Webhooks](https://soat.ttoss.dev/docs/modules/webhooks.md): HTTP callbacks that deliver signed event notifications when project resources change. - [Workflows & Tasks](https://soat.ttoss.dev/docs/modules/workflows.md): State-machine definitions (workflows) and the durable, stateful work items that live in them (tasks). - [Bound an Agent with a Boundary Policy](https://soat.ttoss.dev/docs/tutorials/agent-boundary-policy.md): Cap what an agent can do with a boundary policy, so a sub-agent holding a caller's full token still cannot exceed its own ceiling. - [Agent SOAT Tools and Preset Parameters](https://soat.ttoss.dev/docs/tutorials/agent-soat-tools.md): Give an agent access to platform documents with builtin tools, and lock a tool to a document ID using preset parameters. - [Agent Versioning and Canary Rollout](https://soat.ttoss.dev/docs/tutorials/agent-versioning-and-canary-rollout.md): Treat an agent's prompt like deployable code: archive every config change as a version, roll a new prompt out to a slice of traffic, attribute beha... - [Agent over a Library of PDFs](https://soat.ttoss.dev/docs/tutorials/agent-with-pdfs.md): Build a SOAT agent that answers questions from a library of PDFs using ingestion and knowledge search. - [Approval Gates: Human-in-the-Loop with the `approval` Node](https://soat.ttoss.dev/docs/tutorials/approval-gate.md): Pause an orchestration for a human decision with an approval node, then approve or reject it from the approvals queue. - [Automate a Flow with Triggers](https://soat.ttoss.dev/docs/tutorials/automate-a-flow-with-triggers.md): Automate a SOAT flow by binding a manual, webhook, or schedule starter to an executable target with Triggers. - [Build an Agent Harness](https://soat.ttoss.dev/docs/tutorials/build-an-agent-harness.md): Build an agent harness on SOAT: declare what the agent can reach as a client tool, cap what its runner identity may do with a policy, and run the p... - [Call AWS and GCP APIs from an Agent](https://soat.ttoss.dev/docs/tutorials/call-aws-and-gcp-apis-from-an-agent.md): Give an agent a tool that calls a real AWS or Google Cloud API — SigV4 signed per request, or a service account access token minted and cached for ... - [Cap Spend Per End User](https://soat.ttoss.dev/docs/tutorials/cap-spend-per-end-user.md): Attribute agent spend to individual end users with Actors, then cap each user's monthly budget with one actor-scoped quota. - [Chat with an LLM](https://soat.ttoss.dev/docs/tutorials/chat-with-llm.md): Build a multi-turn LLM chat with managed conversation history on your own infrastructure, via CLI, SDK, or REST. - [Execute Agent Tool Calls in Your Own App (Client Tools)](https://soat.ttoss.dev/docs/tutorials/client-tools.md): Implement function calling with SOAT client tools: the agent pauses at requires_action, your app executes the function locally, then submits the to... - [Close the Monthly Books](https://soat.ttoss.dev/docs/tutorials/close-the-monthly-books.md): Compose an orchestration, a workflow, a trigger, and an approval into one governed month-end close process. - [Conditional Branching in Orchestrations](https://soat.ttoss.dev/docs/tutorials/conditional-orchestration.md): Build a branching orchestration with condition nodes and see skipped nodes recorded in the execution trace. - [Connect Third-Party LLMs](https://soat.ttoss.dev/docs/tutorials/connect-third-party-llms.md): Connect SOAT to hosted LLM providers such as xAI, OpenAI, Anthropic, and Amazon Bedrock. - [Create an Agent Squad](https://soat.ttoss.dev/docs/tutorials/create-an-agent-squad.md): Build and deploy a coordinated agent squad — researcher, writer, reviewer, and human approval — as a single Formation stack. - [Data Retention and Zero-Retention](https://soat.ttoss.dev/docs/tutorials/data-retention-and-zero-retention.md): Erase prompt and completion content from agent logs on demand, expire it automatically with a retention window, or never store it at all — while co... - [Debug Session, Generation, and Trace History](https://soat.ttoss.dev/docs/tutorials/debug-session-generation-trace-history.md): A practical workflow for debugging SOAT by mapping sessions, generations, and traces together. - [Generating Embeddings](https://soat.ttoss.dev/docs/tutorials/embeddings.md): Use the SOAT Embeddings endpoint to convert text into vectors and compute cosine similarity. - [Evaluate an Agent](https://soat.ttoss.dev/docs/tutorials/evaluate-an-agent.md): Turn "did my prompt change make the agent worse?" into a number: build a dataset of test cases, score real runs with deterministic scorers, and com... - [Deploy a Multi-Agent App with Agent Formation](https://soat.ttoss.dev/docs/tutorials/formations.md): Deploy a multi-agent orchestration pipeline with a single Agent Formation template instead of many ordered API calls. - [Gate a Canary Promotion on an Eval](https://soat.ttoss.dev/docs/tutorials/gate-a-canary-promotion-on-an-eval.md): Make a canary rollout wait for evidence: declare a suite alongside the agent in a formation, pin a run to the canary version, and let promotion suc... - [Gate a Dangerous Tool with Guardrails](https://soat.ttoss.dev/docs/tutorials/gate-a-tool-with-guardrails.md): Classify a dangerous tool call with a guardrail — execute below a threshold, require human sign-off above it, and hard-stop on a failing guard. - [Tutorials](https://soat.ttoss.dev/docs/tutorials/tutorials.md): End-to-end SOAT tutorials that walk through complete workflows from scratch — agents, tools, RAG, orchestration, guardrails, and cost controls. - [Ingest Images and Audio with Converters](https://soat.ttoss.dev/docs/tutorials/ingest-images-and-audio.md): Ingest images and audio into searchable documents using converter tools and ingestion rules. - [Judge Open-Ended Answers](https://soat.ttoss.dev/docs/tutorials/judge-open-ended-answers.md): Score answers that have no single correct string: an llm_judge scorer with a required threshold, run queued instead of blocking, polled to a verdic... - [Agent with Persistent Memory](https://soat.ttoss.dev/docs/tutorials/memories-agent.md): Give a SOAT agent long-term memory that persists across sessions. - [Meter and Budget Your Project's Spend](https://soat.ttoss.dev/docs/tutorials/metering-and-budgets.md): Meter an agent's token usage, price it, aggregate per-project spend, and get pushed a webhook alert when a budget threshold is crossed. - [Multi-Agent Sonnet with Nested Agent Calls](https://soat.ttoss.dev/docs/tutorials/multi-agent-orchestration.md): Build a nested-agent pipeline where one agent coordinates sub-agents with builtin tools. - [Write a Sonnet with a Workflow](https://soat.ttoss.dev/docs/tutorials/orchestrate-a-sonnet-with-workflows.md): Compose a sonnet stanza by stanza through a Workflow — a chain of agent-driven states, a human review, a guarded publish, and a backward move a DAG... - [Orchestrate a Sonnet](https://soat.ttoss.dev/docs/tutorials/orchestrate-a-sonnet.md): Build a sequential multi-agent pipeline with the Orchestrations module — four agents compose a sonnet stanza by stanza, invoked directly from the g... - [Orchestration Control Flow: Delay, Poll, and Loop](https://soat.ttoss.dev/docs/tutorials/orchestration-control-flow.md): Use orchestration control-flow nodes — delay, poll, loop, and condition — to pace, wait, repeat, and branch a run. - [Pass Per-User Credentials to Tools with Tool Context](https://soat.ttoss.dev/docs/tutorials/per-user-credentials-with-tool-context.md): Hand a per-user credential to an orchestration run with tool_context, land it as a real Authorization header with a {{context:...}} token, and conf... - [Permissions in Practice](https://soat.ttoss.dev/docs/tutorials/permissions.md): Walk through a realistic SOAT permissions setup from scratch with users, policies, and API keys. - [Replay a Bad Turn](https://soat.ttoss.dev/docs/tutorials/replay-a-bad-turn.md): Take one bad answer from production and close the loop on it: read the turn back step by step, freeze it as an eval fixture, fork the session at th... - [SOAT SDK](https://soat.ttoss.dev/docs/sdk/sdk.md): The @soat/sdk typed TypeScript client for the SOAT REST API, generated from the OpenAPI specs. - [Services Reference](https://soat.ttoss.dev/docs/sdk/services.md): Every SDK service and method, grouped by module. Each service is reached from the client as `soat.`, and each method corresponds to one RE... - [Usage Examples](https://soat.ttoss.dev/docs/sdk/usage.md): Examples for common SOAT SDK operations across every module, using a typed SoatClient instance. - [Commands Reference](https://soat.ttoss.dev/docs/cli/commands.md): Complete list of all CLI commands, grouped by module. - [SOAT CLI](https://soat.ttoss.dev/docs/cli/cli.md): The @soat/cli command-line interface for the SOAT REST API, with every operation auto-generated as a sub-command from the OpenAPI specs. - [Usage Examples](https://soat.ttoss.dev/docs/cli/usage.md): Common SOAT CLI workflows and command examples for agents, sessions, projects, and more. - [Connecting an MCP Client](https://soat.ttoss.dev/docs/mcp/connecting.md): How to connect an MCP client to SOAT's Streamable HTTP endpoint. - [MCP Server](https://soat.ttoss.dev/docs/mcp/mcp.md): SOAT exposes every resource as Model Context Protocol (MCP) tools that Claude, Copilot, and any MCP client can call directly. - [Tools Reference](https://soat.ttoss.dev/docs/mcp/tools.md): Every MCP tool exposed by the SOAT server, grouped by module. Each tool name maps directly to the MCP `tools/call` method name, and its arguments a... - [OpenAPI Specifications](https://soat.ttoss.dev/docs/openapi-specs.md): Machine-readable OpenAPI specifications for the SOAT REST API, as one merged bundle or one file per module. - [Building on SOAT](https://soat.ttoss.dev/docs/advanced/building-on-soat.md): Embedding SOAT behind your own product: one project per tenant, one project-scoped API key per tenant, and no ownership tables of your own. - [Choosing an Automation Model](https://soat.ttoss.dev/docs/advanced/choosing-an-automation-model.md): Neither, an orchestration, or a workflow? Decide whether the work needs a graph at all, then compare SOAT's two automation models — a cyclic state ... - [Debugging a Run](https://soat.ttoss.dev/docs/advanced/debugging-a-run.md): Which observability surface answers which question: a symptom-to-surface map, the id graph that joins them, and the four reasons a surface is legit... - [Engines & Algorithms](https://soat.ttoss.dev/docs/advanced/engines-and-algorithms.md): The two-layer pattern behind SOAT's intelligence modules: a mechanical engine you can rely on, an algorithm layer you can swap, and tools as the se... - [Expressions & Templating](https://soat.ttoss.dev/docs/advanced/expressions-and-templating.md): Complete reference for SOAT's six expression and templating pattern families and how each resolves at a different time so they compose without esca... - [Memory & Knowledge Engine](https://soat.ttoss.dev/docs/advanced/memory-and-knowledge-engine.md): How SOAT creates, stores, retrieves, and injects knowledge: the write and read pipelines end to end, every algorithm the engine runs today with its... - [Synchronous & Asynchronous Execution](https://soat.ttoss.dev/docs/advanced/sync-and-async.md): The wait toggle: every long-running endpoint runs in the background by default and returns a handle to poll; wait=true blocks. One contract, one po... - [Tool Context](https://soat.ttoss.dev/docs/advanced/tool-context.md): How session and actor context reaches a tool endpoint as X-Soat-Context-* request headers: the exact key-to-header rule, the auto-populated keys, p... - [The Layers of an Agent System](https://soat.ttoss.dev/docs/agent-system-layers.md): The layers an agent system decomposes into — harness, loop, graph, ratchet — which SOAT module owns each one, why the graph should be the last thin... - [List activity feed entries](https://soat.ttoss.dev/docs/api/activity/list-activity.md): Returns activity entries for a project, newest first, filterable by kind and severity. Paginated with an opaque cursor rather than offset/limit — p... - [Create an actor](https://soat.ttoss.dev/docs/api/actors/create-actor.md): Creates a new actor. project keys automatically infer the project from the key's scope; JWT callers must supply projectId. - [Delete an actor](https://soat.ttoss.dev/docs/api/actors/delete-actor.md): Deletes an actor by its ID - [Get actor tags](https://soat.ttoss.dev/docs/api/actors/get-actor-tags.md): Returns all tags attached to the actor - [Get an actor by ID](https://soat.ttoss.dev/docs/api/actors/get-actor.md): Returns an actor by its ID - [List actors](https://soat.ttoss.dev/docs/api/actors/list-actors.md): Returns all actors the caller has access to. If projectId is provided, returns only actors in that project. project keys are scoped to a single pro... - [Merge actor tags](https://soat.ttoss.dev/docs/api/actors/merge-actor-tags.md): Merges provided tags with existing tags (existing tags are preserved unless overridden) - [Replace actor tags](https://soat.ttoss.dev/docs/api/actors/replace-actor-tags.md): Replaces all tags on the actor with the provided tags (not merged) - [Update an actor](https://soat.ttoss.dev/docs/api/actors/update-actor.md): Updates an actor's properties - [Abort the rollout and roll back to stable](https://soat.ttoss.dev/docs/api/agents/abort-agent-release.md): Restores the stable version's config as the agent's live config and clears the release, so all traffic returns to the configuration the rollout was... - [Run an agent generation](https://soat.ttoss.dev/docs/api/agents/create-agent-generation.md): Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` t... - [Create an agent](https://soat.ttoss.dev/docs/api/agents/create-agent.md): Creates a new agent bound to an AI provider. - [Delete an agent](https://soat.ttoss.dev/docs/api/agents/delete-agent.md): Deletes an agent by ID. Fails with `409` if the agent has dependent generations or traces, unless `force=true` is passed, in which case those gener... - [Get an archived agent config version](https://soat.ttoss.dev/docs/api/agents/get-agent-version.md): Returns the exact configuration the agent held at a given version, so a generation can be traced back to the config that produced it. - [Get an agent](https://soat.ttoss.dev/docs/api/agents/get-agent.md): Returns a single agent by ID. - [List an agent's config versions](https://soat.ttoss.dev/docs/api/agents/list-agent-versions.md): Returns the agent's archived configurations, newest first. A version is written on create and on every subsequent write that changes the config — t... - [List agents](https://soat.ttoss.dev/docs/api/agents/list-agents.md): Returns all agents in the project. - [Partially update an agent](https://soat.ttoss.dev/docs/api/agents/patch-agent.md): Partially updates an existing agent. Identical to PUT — both perform partial updates. - [Promote the canary and end the rollout](https://soat.ttoss.dev/docs/api/agents/promote-agent-release.md): Makes the canary version's config the agent's live config and clears the release. The canary is pinned by version, so an edit that landed mid-rollo... - [Restore an archived config as a new version](https://soat.ttoss.dev/docs/api/agents/restore-agent-version.md): Copies the named version's configuration onto the agent as a **new** version rather than rewinding the counter, so history stays append-only and th... - [Set or replace a staged rollout](https://soat.ttoss.dev/docs/api/agents/set-agent-release.md): Starts serving two archived versions side by side: `canary_percent` of traffic gets `canary_version`, the rest gets `stable_version`. - [Submit tool outputs for a paused generation](https://soat.ttoss.dev/docs/api/agents/submit-agent-tool-outputs.md): Resumes a generation that was paused due to client tool calls. Provide tool outputs for each pending tool call. - [Update an agent](https://soat.ttoss.dev/docs/api/agents/update-agent.md): Updates an existing agent. Identical to PATCH — both perform partial updates. - [Create an AI provider](https://soat.ttoss.dev/docs/api/ai-providers/create-ai-provider.md): Creates a new LLM provider configuration - [Delete an AI provider](https://soat.ttoss.dev/docs/api/ai-providers/delete-ai-provider.md): Deletes an AI provider configuration. - [List per-provider price overrides](https://soat.ttoss.dev/docs/api/ai-providers/get-ai-provider-prices.md): Returns the per-provider price overrides for this AI provider instance. An override prices this specific provider (e.g. an enterprise-negotiated ra... - [Get an AI provider](https://soat.ttoss.dev/docs/api/ai-providers/get-ai-provider.md): Returns a specific AI provider configuration - [List the models this provider can run](https://soat.ttoss.dev/docs/api/ai-providers/list-ai-provider-models.md): Asks the provider which models it can run, using this provider record's own credentials and configuration, and returns provider-native model ids — ... - [List AI providers](https://soat.ttoss.dev/docs/api/ai-providers/list-ai-providers.md): Returns a list of AI provider configurations for a project - [Upsert per-provider price overrides](https://soat.ttoss.dev/docs/api/ai-providers/update-ai-provider-prices.md): Upserts price overrides for this AI provider instance, keyed on (model, effective_from). The provider slug is taken from the AI provider itself, so... - [Update an AI provider](https://soat.ttoss.dev/docs/api/ai-providers/update-ai-provider.md): Updates an AI provider configuration - [Create an API key](https://soat.ttoss.dev/docs/api/api-keys/create-api-key.md): Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or n... - [Delete an API key](https://soat.ttoss.dev/docs/api/api-keys/delete-api-key.md): Deletes an API key. Only the owner or an admin can delete it, and a project-scoped credential can only delete keys in its own project. - [Get an API key](https://soat.ttoss.dev/docs/api/api-keys/get-api-key.md): Returns details of an API key. Only the owner or an admin can access it, and a project-scoped credential can only reach keys in its own project. - [List API keys](https://soat.ttoss.dev/docs/api/api-keys/list-api-keys.md): Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - Project-sco... - [Update an API key](https://soat.ttoss.dev/docs/api/api-keys/update-api-key.md): Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key)... - [Approve an approval item](https://soat.ttoss.dev/docs/api/approvals/approve-approval.md): Approves the item. Optionally supply edited `arguments` to replace the proposed arguments (edit-then-approve); the original is preserved on the ite... - [Get an approval item](https://soat.ttoss.dev/docs/api/approvals/get-approval.md): Returns a single approval item with its full evidence. - [List recurring approval groups](https://soat.ttoss.dev/docs/api/approvals/list-approval-recurrences.md): Read-only rollup answering 'what keeps coming back?' — groups items by `dedup_key` and returns those recurring at least `min_count` times, most-rec... - [List approval items](https://soat.ttoss.dev/docs/api/approvals/list-approvals.md): Returns approval items for a project, filterable by status, origin, and expiry. - [Reject an approval item](https://soat.ttoss.dev/docs/api/approvals/reject-approval.md): Rejects the item. A reason is required and preserved on the item. - [Export audit entries as NDJSON](https://soat.ttoss.dev/docs/api/audit-log/export-audit-entries.md): Streams a project's audit-log entries as newline-delimited JSON — one entry object per line, oldest first — for archival before the retention windo... - [Get an audit entry](https://soat.ttoss.dev/docs/api/audit-log/get-audit-entry.md): Returns a single audit-log entry, including its `detail` payload - [List audit entries](https://soat.ttoss.dev/docs/api/audit-log/list-audit-entries.md): Returns audit-log entries visible to the caller, newest first. All filters are optional and combine with AND. `resource_srn` is a prefix match (e.g... - [Get a continuation chain](https://soat.ttoss.dev/docs/api/chains/get-chain.md): Returns a single continuation chain. To read the generations in it, list generations filtered by `chain_id`. - [List continuation chains](https://soat.ttoss.dev/docs/api/chains/list-chains.md): Returns the continuation chains in a project, newest first. Filter by `status` to find the chains that may still be spending (`active`) or the ones... - [Create a chat completion](https://soat.ttoss.dev/docs/api/chats/create-chat-completion.md): OpenAI Chat Completions-compatible endpoint. Mirrors OpenAI's `POST /v1/chat/completions` path so an OpenAI SDK can target it by base URL alone. - [Create a chat](https://soat.ttoss.dev/docs/api/chats/create-chat.md): Creates a new chat resource bound to an AI provider. - [Delete a chat](https://soat.ttoss.dev/docs/api/chats/delete-chat.md): Deletes a chat by ID. - [Get a chat](https://soat.ttoss.dev/docs/api/chats/get-chat.md): Returns a single chat by ID. - [List chats](https://soat.ttoss.dev/docs/api/chats/list-chats.md): Returns all chats in the project. - [Add a message to a conversation](https://soat.ttoss.dev/docs/api/conversations/add-conversation-message.md): Creates a document from the message text and attaches it to the conversation at the given position. If position is omitted, it is appended at the end. - [Create a conversation](https://soat.ttoss.dev/docs/api/conversations/create-conversation.md): Creates a new conversation. project keys automatically infer the project from the key's scope; JWT callers must supply projectId. - [Delete a conversation](https://soat.ttoss.dev/docs/api/conversations/delete-conversation.md): Deletes a conversation by its ID - [Generate the next message in a conversation](https://soat.ttoss.dev/docs/api/conversations/generate-conversation-message.md): Generates the next message using the specified actor's linked agent or chat. - [Get conversation tags](https://soat.ttoss.dev/docs/api/conversations/get-conversation-tags.md): Returns all tags attached to the conversation - [Get a conversation by ID](https://soat.ttoss.dev/docs/api/conversations/get-conversation.md): Returns a conversation by its ID - [List conversation messages](https://soat.ttoss.dev/docs/api/conversations/list-conversation-messages.md): Returns all messages (documents) attached to a conversation, ordered by position - [List conversations](https://soat.ttoss.dev/docs/api/conversations/list-conversations.md): Returns all conversations the caller has access to. If projectId is provided, returns only conversations in that project. project keys are scoped t... - [Merge conversation tags](https://soat.ttoss.dev/docs/api/conversations/merge-conversation-tags.md): Merges provided tags with existing tags - [Remove a message from a conversation](https://soat.ttoss.dev/docs/api/conversations/remove-conversation-message.md): Removes a document from a conversation - [Replace conversation tags](https://soat.ttoss.dev/docs/api/conversations/replace-conversation-tags.md): Replaces all tags on the conversation with the provided tags - [Update a conversation](https://soat.ttoss.dev/docs/api/conversations/update-conversation.md): Updates the status of a conversation - [Deliver an async converter result](https://soat.ttoss.dev/docs/api/documents/complete-ingestion-callback.md): Token-authed callback for a tool converter that deferred conversion by - [Create a document](https://soat.ttoss.dev/docs/api/documents/create-document.md): Creates a new text document and generates an embedding vector for semantic search. project keys automatically infer the project from the key's scop... - [Delete a document](https://soat.ttoss.dev/docs/api/documents/delete-document.md): Deletes a document and its underlying file - [Get document ingestion status](https://soat.ttoss.dev/docs/api/documents/get-document-status.md): Returns a lightweight ingestion status payload for polling — `status`, - [Get document tags](https://soat.ttoss.dev/docs/api/documents/get-document-tags.md): Returns all tags attached to the document - [Get a document by ID](https://soat.ttoss.dev/docs/api/documents/get-document.md): Returns a document with its text content - [Ingest a file into a chunked document](https://soat.ttoss.dev/docs/api/documents/ingest-document.md): Parses an already-uploaded file and creates one Document split into one or - [List documents](https://soat.ttoss.dev/docs/api/documents/list-documents.md): Returns all documents the caller has access to. If projectId is provided, returns only documents in that project. project keys are scoped to a sing... - [Merge document tags](https://soat.ttoss.dev/docs/api/documents/merge-document-tags.md): Merges provided tags with existing tags (existing tags are preserved unless overridden) - [Re-ingest an existing document](https://soat.ttoss.dev/docs/api/documents/reingest-document.md): Re-runs ingestion for an existing document against its already-stored - [Replace document tags](https://soat.ttoss.dev/docs/api/documents/replace-document-tags.md): Replaces all tags on the document with the provided tags (not merged) - [Update a document](https://soat.ttoss.dev/docs/api/documents/update-document.md): Updates document content, title, path, metadata, or tags. Supplying `path` moves the document to a new logical path within the project. - [Create embeddings](https://soat.ttoss.dev/docs/api/embeddings/create-embeddings.md): Generates embedding vectors for one or more text inputs using the server's configured embedding model. - [Cancel an eval run](https://soat.ttoss.dev/docs/api/evaluations/cancel-eval-run.md): Cancels a queued or running run: its outstanding item tasks are dropped so it stops consuming provider budget, and the run settles as `canceled`. - [Curate a dataset item from a generation](https://soat.ttoss.dev/docs/api/evaluations/create-dataset-item-from-generation.md): Promotes a real, completed generation into a test case: its input messages become the item's `input`, and its own answer becomes `expected_output` ... - [Add a dataset item](https://soat.ttoss.dev/docs/api/evaluations/create-dataset-item.md): Adds one test case. `input` is replayed verbatim as the generation's messages, so it must be a non-empty array of `{ role, content }`. - [Create a dataset](https://soat.ttoss.dev/docs/api/evaluations/create-dataset.md): Creates a project-scoped dataset — a named collection of test cases an eval runs an agent against. Names are unique per project. - [Create an eval](https://soat.ttoss.dev/docs/api/evaluations/create-eval.md): Binds an agent under test to a dataset and a list of scorers. The agent and the dataset must belong to the same project as the eval; a cross-projec... - [Delete a dataset item](https://soat.ttoss.dev/docs/api/evaluations/delete-dataset-item.md): Deletes a test case. Results of runs that already scored it stay readable; their `dataset_item_id` becomes null. - [Delete a dataset](https://soat.ttoss.dev/docs/api/evaluations/delete-dataset.md): Deletes a dataset, its items, and every eval bound to it. Results of runs that already scored those items keep their frozen copies of the input and... - [Delete an eval](https://soat.ttoss.dev/docs/api/evaluations/delete-eval.md): Deletes an eval, its runs, and their results - [Get a dataset](https://soat.ttoss.dev/docs/api/evaluations/get-dataset.md): Returns a specific dataset - [Get an eval run](https://soat.ttoss.dev/docs/api/evaluations/get-eval-run.md): Returns a run's status, counts, and aggregate scores - [Get an eval](https://soat.ttoss.dev/docs/api/evaluations/get-eval.md): Returns a specific eval - [List dataset items](https://soat.ttoss.dev/docs/api/evaluations/list-dataset-items.md): Returns the test cases in a dataset, oldest first - [List datasets](https://soat.ttoss.dev/docs/api/evaluations/list-datasets.md): Returns the datasets defined in a project - [List eval run results](https://soat.ttoss.dev/docs/api/evaluations/list-eval-results.md): Returns the per-item results of a run, oldest first - [List eval runs](https://soat.ttoss.dev/docs/api/evaluations/list-eval-runs.md): Returns an eval's runs, newest first - [List evals](https://soat.ttoss.dev/docs/api/evaluations/list-evals.md): Returns the evals defined in a project - [Start an eval run](https://soat.ttoss.dev/docs/api/evaluations/start-eval-run.md): Runs the eval against its dataset, creating one real agent generation per item and scoring the outputs. - [Update a dataset item](https://soat.ttoss.dev/docs/api/evaluations/update-dataset-item.md): Updates a test case. Runs that already scored it are unaffected — each result carries its own frozen copy of the input and expected output. - [Update a dataset](https://soat.ttoss.dev/docs/api/evaluations/update-dataset.md): Updates a dataset's name and/or description - [Update an eval](https://soat.ttoss.dev/docs/api/evaluations/update-eval.md): Updates an eval. Changing `agent_id` re-validates the scorers against the new agent, since an `output_schema` scorer that was legal against the old... - [Acknowledge an exception item](https://soat.ttoss.dev/docs/api/exceptions/acknowledge-exception.md): Moves the item to `acknowledged` ('someone is on it'), recording who. A no-op that returns the item unchanged when already acknowledged; rejected w... - [Get an exception item](https://soat.ttoss.dev/docs/api/exceptions/get-exception.md): Returns a single exception item with its full detail. - [List exception items](https://soat.ttoss.dev/docs/api/exceptions/list-exceptions.md): Returns exception items for a project, filterable by status, severity, and kind. - [Resolve an exception item](https://soat.ttoss.dev/docs/api/exceptions/resolve-exception.md): Moves the item to `resolved` ('fixed'), recording who and an optional note. - [Create a file](https://soat.ttoss.dev/docs/api/files/create-file.md): Creates a new file record in the system - [Create a presigned upload URL](https://soat.ttoss.dev/docs/api/files/create-presigned-url.md): Creates a short-lived, single-use presigned upload URL — the local-storage equivalent of an S3 presigned URL. The client then uploads the file cont... - [Delete a file](https://soat.ttoss.dev/docs/api/files/delete-file.md): Removes a file from the system by ID - [Download file as base64](https://soat.ttoss.dev/docs/api/files/download-file-base-64.md): Returns the file content encoded as base64 - [Download a file](https://soat.ttoss.dev/docs/api/files/download-file.md): Streams the file content to the client - [Get file tags](https://soat.ttoss.dev/docs/api/files/get-file-tags.md): Returns all tags attached to the file - [Get a file by ID](https://soat.ttoss.dev/docs/api/files/get-file.md): Returns the data and metadata of a specific file - [List all files](https://soat.ttoss.dev/docs/api/files/list-files.md): Returns a list of all stored files - [Merge file tags](https://soat.ttoss.dev/docs/api/files/merge-file-tags.md): Merges provided tags with existing tags - [Replace file tags](https://soat.ttoss.dev/docs/api/files/replace-file-tags.md): Replaces all tags on the file with the provided tags - [Update file metadata](https://soat.ttoss.dev/docs/api/files/update-file-metadata.md): Updates the metadata field of a file - [Upload a file using base64 encoding](https://soat.ttoss.dev/docs/api/files/upload-file-base-64.md): Uploads a file to the server using base64-encoded content - [Upload a file using an upload token](https://soat.ttoss.dev/docs/api/files/upload-file-with-token.md): Uploads file content authorized by a single-use token from `POST /api/v1/files/presigned-url`. No bearer credential is required — the token is the ... - [Upload a file](https://soat.ttoss.dev/docs/api/files/upload-file.md): Uploads a file to the server and stores it in the configured storage directory - [Create a new formation](https://soat.ttoss.dev/docs/api/formations/create-formation.md): Validates the template, creates the formation record, then provisions all declared resources in dependency order. - [Delete an formation](https://soat.ttoss.dev/docs/api/formations/delete-formation.md): Deletes the formation stack and all its managed resources in reverse dependency order. - [Get a specific formation](https://soat.ttoss.dev/docs/api/formations/get-formation.md): Returns the formation stack including its current resources. - [List formation operation events](https://soat.ttoss.dev/docs/api/formations/list-formation-events.md): Returns all operations (create, update, delete) with their event logs for the formation, ordered chronologically. - [List formations](https://soat.ttoss.dev/docs/api/formations/list-formations.md): Returns all formation stacks for a project - [Plan a formation deployment](https://soat.ttoss.dev/docs/api/formations/plan-formation.md): Computes a diff between the desired template and the current stack state without making any changes. Returns the list of planned actions. - [Update an formation](https://soat.ttoss.dev/docs/api/formations/update-formation.md): Applies a new template to the formation. Resources are created, updated, or deleted to reconcile the current state with the desired state. - [Validate a formation template](https://soat.ttoss.dev/docs/api/formations/validate-formation.md): Validates a formation template without creating any resources. Returns a list of errors and warnings. Accepts the template as a JSON object or as a... - [Get a generation's transcript](https://soat.ttoss.dev/docs/api/generations/get-generation-transcript.md): Returns one generation's turn read back as an ordered sequence of steps: what it was asked, each model step with its tool calls and results, and ho... - [Get a generation](https://soat.ttoss.dev/docs/api/generations/get-generation.md): Returns a single generation record by ID, including its status and the structured `error` payload when the generation failed (e.g. because the upst... - [List generations](https://soat.ttoss.dev/docs/api/generations/list-generations.md): Returns generations the caller can access, optionally filtered by agent, trace, orchestration run, node, and status. Replaces the former per-trace ... - [Purge generation content](https://soat.ttoss.dev/docs/api/generations/purge-generation-content.md): Clears the generation's content — `metadata`, `error`, `extraction`, and the internal recovery state of a paused run — and stamps `content_redacted... - [Update generation metadata](https://soat.ttoss.dev/docs/api/generations/update-generation.md): Attaches caller-supplied key/value metadata to a generation record for per-run audit attribution (e.g. recording which knowledge-corpus version pro... - [Create a guardrail](https://soat.ttoss.dev/docs/api/guardrails/create-guardrail.md): Creates a new guardrail in the project, archiving its document as version 1. The `document` is validated on write: `class` must be a literal (A/B/C... - [Delete a guardrail](https://soat.ttoss.dev/docs/api/guardrails/delete-guardrail.md): Deletes a guardrail and its archived versions by ID. - [Dry-run evaluate a guardrail](https://soat.ttoss.dev/docs/api/guardrails/evaluate-guardrail.md): Runs the full evaluation pipeline — the `class` expression, the guard, the context tool per `context_mode`, live `runtime.*` resolution — against c... - [Fetch an archived guardrail version](https://soat.ttoss.dev/docs/api/guardrails/get-guardrail-version.md): Returns the exact configuration — and so the exact `document` — that governed at a given version. Approval items, activity entries, and exceptions ... - [Get a guardrail](https://soat.ttoss.dev/docs/api/guardrails/get-guardrail.md): Returns a single guardrail by ID. - [List a guardrail's config versions](https://soat.ttoss.dev/docs/api/guardrails/list-guardrail-versions.md): Returns the guardrail's archived configurations, newest first. A version is written on create and on every subsequent write that changes the policy... - [List guardrails](https://soat.ttoss.dev/docs/api/guardrails/list-guardrails.md): Returns all guardrails in the project. - [Restore an archived guardrail config](https://soat.ttoss.dev/docs/api/guardrails/restore-guardrail-version.md): Writes an archived version's `document` back as the guardrail's live policy, which archives it again as a **new** version rather than rewinding the... - [Update a guardrail](https://soat.ttoss.dev/docs/api/guardrails/update-guardrail.md): Updates an existing guardrail. A `document` write that actually changes the policy increments `version` and archives the new document as a Guardrai... - [REST API Reference](https://soat.ttoss.dev/docs/api/api.md): Overview of the SOAT REST API: versioned, authenticated HTTP endpoints that return JSON for every platform operation. - [Create an ingestion rule](https://soat.ttoss.dev/docs/api/ingestion-rules/create-ingestion-rule.md): Creates a rule mapping a content_type glob to a converter. Exactly one of tool_id or agent_id must be set. - [Delete an ingestion rule](https://soat.ttoss.dev/docs/api/ingestion-rules/delete-ingestion-rule.md): Deletes an ingestion rule - [Get an ingestion rule](https://soat.ttoss.dev/docs/api/ingestion-rules/get-ingestion-rule.md): Returns a specific ingestion rule - [List ingestion rules](https://soat.ttoss.dev/docs/api/ingestion-rules/list-ingestion-rules.md): Returns the ingestion rules for a project - [Update an ingestion rule](https://soat.ttoss.dev/docs/api/ingestion-rules/update-ingestion-rule.md): Updates fields of an ingestion rule - [Search knowledge](https://soat.ttoss.dev/docs/api/knowledge/search-knowledge.md): Searches across documents and memory entries using semantic search, file paths, document IDs, or memory IDs/tags. At least one of `query`, `documen... - [Create a memory](https://soat.ttoss.dev/docs/api/memories/create-memory.md): Creates a new memory configuration in a project - [Delete a memory](https://soat.ttoss.dev/docs/api/memories/delete-memory.md): Deletes a memory configuration - [Get a memory](https://soat.ttoss.dev/docs/api/memories/get-memory.md): Returns a single memory configuration by ID - [List memories](https://soat.ttoss.dev/docs/api/memories/list-memories.md): Returns a list of memory configurations for a project - [Update a memory](https://soat.ttoss.dev/docs/api/memories/update-memory.md): Updates an existing memory configuration - [Create a memory entry](https://soat.ttoss.dev/docs/api/memory-entries/create-memory-entry.md): Creates a new entry in the specified memory container. Automatically generates an embedding for semantic search, and skips the write when an existi... - [Delete a memory entry](https://soat.ttoss.dev/docs/api/memory-entries/delete-memory-entry.md): Deletes a memory entry - [Get a memory entry](https://soat.ttoss.dev/docs/api/memory-entries/get-memory-entry.md): Returns a single memory entry by ID - [List memory entries](https://soat.ttoss.dev/docs/api/memory-entries/list-memory-entries.md): Returns all entries in a memory container - [Update a memory entry](https://soat.ttoss.dev/docs/api/memory-entries/update-memory-entry.md): Updates an existing memory entry. Regenerates the embedding if content changes. - [Create a model route](https://soat.ttoss.dev/docs/api/model-routes/create-model-route.md): Creates a project-scoped model route: a named, ordered list of provider+model targets tried in array order. Every target must reference an AI provi... - [Delete a model route](https://soat.ttoss.dev/docs/api/model-routes/delete-model-route.md): Deletes a model route. Returns 409 when an agent still references it — a routed agent has no pinned provider to fall back on, so the reference must... - [Get a model route](https://soat.ttoss.dev/docs/api/model-routes/get-model-route.md): Returns a specific model route - [List model routes](https://soat.ttoss.dev/docs/api/model-routes/list-model-routes.md): Returns the model routes defined in a project - [Update a model route](https://soat.ttoss.dev/docs/api/model-routes/update-model-route.md): Updates a model route's name, targets, retry classes, or breaker configuration. Omitted fields are left unchanged. - [Start the authorization code flow](https://soat.ttoss.dev/docs/api/oauth/authorize-oauth-client.md): The authorization endpoint. PKCE is mandatory — `code_challenge` is required and - [Exchange a code or refresh token for an access token](https://soat.ttoss.dev/docs/api/oauth/create-oauth-token.md): The token endpoint, serving the `authorization_code` and `refresh_token` grants. The client - [Get authorization server metadata](https://soat.ttoss.dev/docs/api/oauth/get-oauth-authorization-server-metadata.md): Returns the [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414) Authorization Server Metadata - [Get protected resource metadata](https://soat.ttoss.dev/docs/api/oauth/get-oauth-protected-resource-metadata.md): Returns the [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) Protected Resource Metadata - [Register an OAuth client](https://soat.ttoss.dev/docs/api/oauth/register-oauth-client.md): [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591) Dynamic Client Registration — the - [Cancel an orchestration run](https://soat.ttoss.dev/docs/api/orchestrations/cancel-orchestration-run.md): Cancels a run that has not yet reached a terminal state. - [Create an orchestration](https://soat.ttoss.dev/docs/api/orchestrations/create-orchestration.md): Creates a new orchestration (pipeline) definition in the project. - [Delete an orchestration](https://soat.ttoss.dev/docs/api/orchestrations/delete-orchestration.md): Deletes an orchestration definition and all its runs. - [Get an orchestration run](https://soat.ttoss.dev/docs/api/orchestrations/get-orchestration-run.md): Returns the status, state, and artifacts of a specific run. - [Fetch an archived orchestration version](https://soat.ttoss.dev/docs/api/orchestrations/get-orchestration-version.md): Returns the exact graph a given version describes. Every run records the version it started on in `orchestration_version` and executes that graph f... - [Get an orchestration](https://soat.ttoss.dev/docs/api/orchestrations/get-orchestration.md): Returns the orchestration with nodes and edges. - [Get orchestration queue stats](https://soat.ttoss.dev/docs/api/orchestrations/get-queue-stats.md): Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently c... - [List orchestration runs](https://soat.ttoss.dev/docs/api/orchestrations/list-orchestration-runs.md): Returns orchestration runs the caller can access, optionally filtered by orchestration, by parent run, or by whether the run has a parent at all. - [List an orchestration's graph versions](https://soat.ttoss.dev/docs/api/orchestrations/list-orchestration-versions.md): Returns the orchestration's archived graphs, newest first. A version is written on create and on every subsequent write that changes the graph (`no... - [List orchestrations](https://soat.ttoss.dev/docs/api/orchestrations/list-orchestrations.md): Returns orchestrations accessible to the caller. - [Restore an archived orchestration graph](https://soat.ttoss.dev/docs/api/orchestrations/restore-orchestration-version.md): Writes an archived version's graph back as the orchestration's live definition, which archives it again as a **new** version rather than rewinding ... - [Resume an orchestration run](https://soat.ttoss.dev/docs/api/orchestrations/resume-orchestration-run.md): Re-drives an awaiting_input orchestration run from its last checkpoint. This does not satisfy the pause itself — it carries no node_id or payload, ... - [Start an orchestration run](https://soat.ttoss.dev/docs/api/orchestrations/start-orchestration-run.md): Creates a new run for the orchestration named by orchestration_id. By default the run executes durably in the background: the response returns imme... - [Submit human input](https://soat.ttoss.dev/docs/api/orchestrations/submit-human-input.md): Provides human input to a run that is awaiting_input at a human node. - [Update an orchestration](https://soat.ttoss.dev/docs/api/orchestrations/update-orchestration.md): Partially updates an orchestration definition. - [Validate an orchestration graph](https://soat.ttoss.dev/docs/api/orchestrations/validate-orchestration.md): Statically validates an orchestration graph without persisting anything. Checks that every node has its required field, node ids are unique, edges ... - [Create a policy](https://soat.ttoss.dev/docs/api/policies/create-policy.md): Creates a new global policy. Requires admin role. - [Delete a policy](https://soat.ttoss.dev/docs/api/policies/delete-policy.md): Deletes a global policy. Requires admin role. - [Get a policy](https://soat.ttoss.dev/docs/api/policies/get-policy.md): Returns details of a specific policy. Requires admin role. - [List all policies](https://soat.ttoss.dev/docs/api/policies/list-policies.md): Returns global policies. Requires admin role. Pass user_id to list only the policies attached to that user (replaces the former per-user policies e... - [Update a policy](https://soat.ttoss.dev/docs/api/policies/update-policy.md): Updates an existing global policy. Requires admin role. - [Create a project](https://soat.ttoss.dev/docs/api/projects/create-project.md): Creates a new project. Requires admin role. - [Delete a project](https://soat.ttoss.dev/docs/api/projects/delete-project.md): Deletes a project. Requires admin role. Fails with `409` if the project has any dependent resource, unless `force=true` is passed, in which case th... - [List a project's price rows](https://soat.ttoss.dev/docs/api/projects/get-project-prices.md): Returns the project's per-provider-slug price rows — the middle pricing tier that covers every one of the project's instances of a given provider s... - [Get a project](https://soat.ttoss.dev/docs/api/projects/get-project.md): Returns details of a specific project. - [List projects](https://soat.ttoss.dev/docs/api/projects/list-projects.md): Lists projects accessible to the caller. - JWT admin: returns all projects. - JWT regular user: returns only projects granted by the user's policie... - [Upsert a project's price rows](https://soat.ttoss.dev/docs/api/projects/update-project-prices.md): Upserts project + provider-slug price rows, keyed on (provider, model, effective_from). A row covers all of the project's instances of that provide... - [Update a project](https://soat.ttoss.dev/docs/api/projects/update-project.md): Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the pro... - [Create a quota](https://soat.ttoss.dev/docs/api/quotas/create-quota.md): Creates a project-scoped quota. `requests` is valid for `scope: project`/`api_key`; `tokens` and `cost_usd` are valid for `scope: project`/`agent`/... - [Delete a quota](https://soat.ttoss.dev/docs/api/quotas/delete-quota.md): Deletes a quota and drops its window counters - [Get a quota](https://soat.ttoss.dev/docs/api/quotas/get-quota.md): Returns a specific quota, including current window usage - [List quotas](https://soat.ttoss.dev/docs/api/quotas/list-quotas.md): Returns the quotas defined in a project - [Update a quota](https://soat.ttoss.dev/docs/api/quotas/update-quota.md): Updates a quota's limit and/or mode. Other fields are immutable. - [Create a secret](https://soat.ttoss.dev/docs/api/secrets/create-secret.md): Creates a new encrypted secret in a project - [Delete a secret](https://soat.ttoss.dev/docs/api/secrets/delete-secret.md): Deletes a secret - [Get a secret](https://soat.ttoss.dev/docs/api/secrets/get-secret.md): Returns a specific secret - [List secrets](https://soat.ttoss.dev/docs/api/secrets/list-secrets.md): Returns a list of secrets for a project - [Update a secret](https://soat.ttoss.dev/docs/api/secrets/update-secret.md): Updates a secret's name and/or value - [Add a user message](https://soat.ttoss.dev/docs/api/sessions/add-session-message.md): Saves a user message to the session. When autoGenerate is enabled on the session and no generation is currently in progress, generation is triggere... - [Create a session](https://soat.ttoss.dev/docs/api/sessions/create-session.md): Creates a new session for the specified agent, along with the underlying conversation, so the caller only needs this single call to start interacti... - [Delete a session](https://soat.ttoss.dev/docs/api/sessions/delete-session.md): Deletes the session and its underlying conversation and messages. The session's actor is not deleted. Generations and traces produced by the sessio... - [Fork a session](https://soat.ttoss.dev/docs/api/sessions/fork-session.md): Branches a new session from a point in this session's history: same context, different continuation. - [Trigger agent generation](https://soat.ttoss.dev/docs/api/sessions/generate-session-response.md): Triggers the agent to generate a response based on the current conversation. Background by default: returns `202 Accepted` immediately while the ge... - [Get session tags](https://soat.ttoss.dev/docs/api/sessions/get-session-tags.md): Returns the session's tags object. - [Get a session](https://soat.ttoss.dev/docs/api/sessions/get-session.md): Returns details of a single session. - [List a session's forks](https://soat.ttoss.dev/docs/api/sessions/list-session-forks.md): Returns the sessions forked directly from this one. One level of lineage: a fork of a fork is listed under its own parent. - [List sessions](https://soat.ttoss.dev/docs/api/sessions/list-sessions.md): Returns sessions the caller can access, optionally filtered by agent, actor and status. - [Merge session tags](https://soat.ttoss.dev/docs/api/sessions/merge-session-tags.md): Merges the provided tags into the session's existing tags. - [Replace session tags](https://soat.ttoss.dev/docs/api/sessions/replace-session-tags.md): Replaces all tags on the session. - [Submit tool outputs](https://soat.ttoss.dev/docs/api/sessions/submit-session-tool-outputs.md): Submits client tool outputs for a generation that returned requires_action. The agent continues its loop and returns the final or next requires_act... - [Update a session](https://soat.ttoss.dev/docs/api/sessions/update-session.md): Updates the session name and/or status. - [Create a task](https://soat.ttoss.dev/docs/api/tasks/create-task.md): Creates a task bound to a workflow. By default the task is placed in the workflow's initial state; passing `state` places it directly in that named... - [Delete a task](https://soat.ttoss.dev/docs/api/tasks/delete-task.md): Deletes a task. Its transition history cascades. - [Get task history](https://soat.ttoss.dev/docs/api/tasks/get-task-history.md): Returns the append-only transition history of a task. - [Get a task](https://soat.ttoss.dev/docs/api/tasks/get-task.md): Retrieves a task, including its active dispatch and automation status. - [List tasks](https://soat.ttoss.dev/docs/api/tasks/list-tasks.md): Lists tasks (the board query). Filter by workflow, state, status, or assignee — `GET /tasks?workflow_id=...&state=...` is one board column. - [Transition a task](https://soat.ttoss.dev/docs/api/tasks/transition-task.md): Fires a named transition on a task. The transition must exist in the workflow and be valid from the task's current state; its guard must pass. This... - [Update a task](https://soat.ttoss.dev/docs/api/tasks/update-task.md): Updates a task's payload, title, or assignee. `state` is never directly writable — move it with a transition; sending a `state` field is rejected a... - [Call a tool](https://soat.ttoss.dev/docs/api/tools/call-tool.md): Directly invokes a tool and returns its output. Supported for `http`, `builtin`, `mcp`, and `pipeline` tools. `client` tools cannot be invoked serv... - [Create a tool](https://soat.ttoss.dev/docs/api/tools/create-tool.md): Creates a new tool in the project. - [Delete a tool](https://soat.ttoss.dev/docs/api/tools/delete-tool.md): Deletes a tool by ID. - [Get a tool](https://soat.ttoss.dev/docs/api/tools/get-tool.md): Returns a single tool by ID. - [List tools](https://soat.ttoss.dev/docs/api/tools/list-tools.md): Returns all tools in the project. - [Update a tool](https://soat.ttoss.dev/docs/api/tools/update-tool.md): Updates an existing tool. - [Get trace tree](https://soat.ttoss.dev/docs/api/traces/get-trace-tree.md): Returns the full execution tree rooted at the given trace (or its root if the given trace is a child). Each node represents one agent's execution s... - [Get a trace](https://soat.ttoss.dev/docs/api/traces/get-trace.md): Returns a single trace by ID. - [List traces](https://soat.ttoss.dev/docs/api/traces/list-traces.md): Returns a paginated list of execution traces for the project. - [Purge trace content](https://soat.ttoss.dev/docs/api/traces/purge-trace-content.md): Deletes the trace's steps object from storage and clears its content columns (`file_id`, `error`), cascading to every descendant trace and to all o... - [Create a trigger](https://soat.ttoss.dev/docs/api/triggers/create-trigger.md): Creates a new trigger for a project - [Delete a trigger](https://soat.ttoss.dev/docs/api/triggers/delete-trigger.md): Deletes a trigger - [Fire a trigger](https://soat.ttoss.dev/docs/api/triggers/fire-trigger.md): Fires a trigger synchronously and returns the terminal firing record. The firing itself always settles here; an `eval` target's run is queued rathe... - [Get a trigger firing](https://soat.ttoss.dev/docs/api/triggers/get-trigger-firing.md): Retrieves the details of a specific trigger firing - [Get trigger secret](https://soat.ttoss.dev/docs/api/triggers/get-trigger-secret.md): Retrieves the signing secret for a webhook trigger - [Get a trigger](https://soat.ttoss.dev/docs/api/triggers/get-trigger.md): Retrieves the details of a specific trigger - [List trigger firings](https://soat.ttoss.dev/docs/api/triggers/list-trigger-firings.md): Lists firings for a trigger (trigger_id is required). - [List triggers](https://soat.ttoss.dev/docs/api/triggers/list-triggers.md): Lists triggers. Filter by project, starter type, or target type. - [Rotate trigger secret](https://soat.ttoss.dev/docs/api/triggers/rotate-trigger-secret.md): Rotates the signing secret for a webhook trigger - [Update a trigger](https://soat.ttoss.dev/docs/api/triggers/update-trigger.md): Updates an existing trigger's configuration. The type is immutable. - [Create a usage threshold](https://soat.ttoss.dev/docs/api/usage/create-usage-threshold.md): Creates a usage alert threshold on a project. Thresholds are immutable apart from deletion — to change one, delete and recreate it (which resets it... - [Delete a usage threshold](https://soat.ttoss.dev/docs/api/usage/delete-usage-threshold.md): Deletes a usage threshold, resetting its fire state. Recreating a threshold starts its once-per-window / hysteresis state fresh. - [Get the price book](https://soat.ttoss.dev/docs/api/usage/get-price-book.md): Returns the global price book — the versioned per-provider/model unit prices used to compute usage cost at write time. Readable by any authenticate... - [Get a generation or run billing receipt](https://soat.ttoss.dev/docs/api/usage/get-usage-receipt.md): Returns a billing receipt. Pass generation_id for a per-generation receipt, or orchestration_run_id for a per-run receipt summed across the orchest... - [Get aggregated usage for a project](https://soat.ttoss.dev/docs/api/usage/get-usage.md): Returns a project's usage rolled up over an optional `[from, to]` time window, bucketed by a single dimension and optionally narrowed to one `meter... - [List usage meters](https://soat.ttoss.dev/docs/api/usage/list-usage-meters.md): Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent, generation, trace, actor, session, or `sou... - [List usage thresholds](https://soat.ttoss.dev/docs/api/usage/list-usage-thresholds.md): Lists the usage alert thresholds the caller can access, optionally filtered by project_id. Each threshold fires the `usage.threshold_crossed` webho... - [Upsert price-book rows](https://soat.ttoss.dev/docs/api/usage/upsert-price-book.md): Upserts price rows keyed on (provider, model, effective_from). Admin only. `effective_from` must be in the future once the (provider, model, compon... - [Attach policies to a user](https://soat.ttoss.dev/docs/api/users/attach-user-policies.md): Replaces the user's policy list with the provided policy IDs. Requires admin role. - [Create the first admin user](https://soat.ttoss.dev/docs/api/users/bootstrap-user.md): Creates the first admin user. Returns 409 if any user already exists. - [Create a user](https://soat.ttoss.dev/docs/api/users/create-user.md): Creates a new user in the system - [Delete a user by ID](https://soat.ttoss.dev/docs/api/users/delete-user.md): Deletes a specific user - [Get the current authenticated user](https://soat.ttoss.dev/docs/api/users/get-current-user.md): Returns the profile of the currently authenticated user - [Get a user by ID](https://soat.ttoss.dev/docs/api/users/get-user.md): Returns the data of a specific user - [List all users](https://soat.ttoss.dev/docs/api/users/list-users.md): Returns a list of all users - [Login user](https://soat.ttoss.dev/docs/api/users/login-user.md): Authenticates a user and returns a JWT token - [Create a webhook](https://soat.ttoss.dev/docs/api/webhooks/create-webhook.md): Creates a new webhook for a project - [Delete a webhook](https://soat.ttoss.dev/docs/api/webhooks/delete-webhook.md): Deletes a webhook and stops all event deliveries - [Get a delivery](https://soat.ttoss.dev/docs/api/webhooks/get-webhook-delivery.md): Retrieves the details of a specific webhook delivery - [Get webhook secret](https://soat.ttoss.dev/docs/api/webhooks/get-webhook-secret.md): Retrieves the signing secret for the specified webhook - [Get a webhook](https://soat.ttoss.dev/docs/api/webhooks/get-webhook.md): Retrieves the details of a specific webhook - [List webhook deliveries](https://soat.ttoss.dev/docs/api/webhooks/list-webhook-deliveries.md): Lists event deliveries for a webhook (webhook_id is required). - [List webhooks](https://soat.ttoss.dev/docs/api/webhooks/list-webhooks.md): Lists webhooks. Use the project_id query parameter to filter by project. - [Redeliver a webhook delivery](https://soat.ttoss.dev/docs/api/webhooks/redeliver-webhook-delivery.md): Queues the stored payload of an existing delivery to be sent again. - [Rotate webhook secret](https://soat.ttoss.dev/docs/api/webhooks/rotate-webhook-secret.md): Rotates the secret key for the specified webhook - [Update a webhook](https://soat.ttoss.dev/docs/api/webhooks/update-webhook.md): Updates an existing webhook's configuration - [Create a workflow](https://soat.ttoss.dev/docs/api/workflows/create-workflow.md): Creates a new workflow definition. The definition is statically validated. - [Delete a workflow](https://soat.ttoss.dev/docs/api/workflows/delete-workflow.md): Deletes a workflow. Rejected while open tasks exist. - [Fetch an archived workflow version](https://soat.ttoss.dev/docs/api/workflows/get-workflow-version.md): Returns the exact state machine a given version describes. Every task records the version it entered on in `workflow_version` and runs on that mach... - [Get a workflow](https://soat.ttoss.dev/docs/api/workflows/get-workflow.md): Retrieves a workflow definition. - [List a workflow's versions](https://soat.ttoss.dev/docs/api/workflows/list-workflow-versions.md): Returns the workflow's archived state machines, newest first. A version is written on create and on every subsequent write that changes the definit... - [List workflows](https://soat.ttoss.dev/docs/api/workflows/list-workflows.md): Lists workflow definitions in a project. - [Restore an archived workflow state machine](https://soat.ttoss.dev/docs/api/workflows/restore-workflow-version.md): Writes an archived version's state machine back as the workflow's live definition, which archives it again as a **new** version rather than rewindi... - [Update a workflow](https://soat.ttoss.dev/docs/api/workflows/update-workflow.md): Updates a workflow definition. Structural changes (states/transitions) are re-validated. Existing tasks in a removed state stay put but can only le... - [Activity Commands](https://soat.ttoss.dev/docs/cli/commands/activity.md): See [Activity module docs](../../modules/activity) for permissions and data model. - [Actors Commands](https://soat.ttoss.dev/docs/cli/commands/actors.md): See [Actors module docs](../../modules/actors) for permissions and data model. - [Agents Commands](https://soat.ttoss.dev/docs/cli/commands/agents.md): See [Agents module docs](../../modules/agents) for permissions and data model. - [AI Providers Commands](https://soat.ttoss.dev/docs/cli/commands/ai-providers.md): See [AI Providers module docs](../../modules/ai-providers) for permissions and data model. - [API Keys Commands](https://soat.ttoss.dev/docs/cli/commands/api-keys.md): See [API Keys module docs](../../modules/api-keys) for permissions and data model. - [Approvals Commands](https://soat.ttoss.dev/docs/cli/commands/approvals.md): See [Approvals module docs](../../modules/approvals) for permissions and data model. - [Audit Log Commands](https://soat.ttoss.dev/docs/cli/commands/audit-log.md): See [Audit Log module docs](../../modules/audit-log) for permissions and data model. - [Chains Commands](https://soat.ttoss.dev/docs/cli/commands/chains.md): See [Chains module docs](../../modules/chains) for permissions and data model. - [Chats Commands](https://soat.ttoss.dev/docs/cli/commands/chats.md): See [Chats module docs](../../modules/chats) for permissions and data model. - [Conversations Commands](https://soat.ttoss.dev/docs/cli/commands/conversations.md): See [Conversations module docs](../../modules/conversations) for permissions and data model. - [Documents Commands](https://soat.ttoss.dev/docs/cli/commands/documents.md): See [Documents module docs](../../modules/documents) for permissions and data model. - [Embeddings Commands](https://soat.ttoss.dev/docs/cli/commands/embeddings.md): See [Embeddings module docs](../../modules/embeddings) for permissions and data model. - [Evaluations Commands](https://soat.ttoss.dev/docs/cli/commands/evaluations.md): See [Evaluations module docs](../../modules/evaluations) for permissions and data model. - [Exceptions Commands](https://soat.ttoss.dev/docs/cli/commands/exceptions.md): See [Exceptions module docs](../../modules/exceptions) for permissions and data model. - [Files Commands](https://soat.ttoss.dev/docs/cli/commands/files.md): See [Files module docs](../../modules/files) for permissions and data model. - [Formations Commands](https://soat.ttoss.dev/docs/cli/commands/formations.md): See [Formations module docs](../../modules/formations) for permissions and data model. - [Generations Commands](https://soat.ttoss.dev/docs/cli/commands/generations.md): See [Generations module docs](../../modules/generations) for permissions and data model. - [Guardrails Commands](https://soat.ttoss.dev/docs/cli/commands/guardrails.md): See [Guardrails module docs](../../modules/guardrails) for permissions and data model. - [Ingestion Rules Commands](https://soat.ttoss.dev/docs/cli/commands/ingestion-rules.md): See [Ingestion Rules module docs](../../modules/ingestion-rules) for permissions and data model. - [Knowledge Commands](https://soat.ttoss.dev/docs/cli/commands/knowledge.md): See [Knowledge module docs](../../modules/knowledge) for permissions and data model. - [Memories Commands](https://soat.ttoss.dev/docs/cli/commands/memories.md): See [Memories module docs](../../modules/memories) for permissions and data model. - [Memory Entries Commands](https://soat.ttoss.dev/docs/cli/commands/memory-entries.md): See [Memory Entries module docs](../../modules/memories) for permissions and data model. - [Model Routes Commands](https://soat.ttoss.dev/docs/cli/commands/model-routes.md): See [Model Routes module docs](../../modules/model-routes) for permissions and data model. - [OAuth Commands](https://soat.ttoss.dev/docs/cli/commands/oauth.md): See [OAuth module docs](../../modules/oauth) for permissions and data model. - [Orchestrations Commands](https://soat.ttoss.dev/docs/cli/commands/orchestrations.md): See [Orchestrations module docs](../../modules/orchestrations) for permissions and data model. - [Policies Commands](https://soat.ttoss.dev/docs/cli/commands/policies.md): See [Policies module docs](../../modules/policies) for permissions and data model. - [Projects Commands](https://soat.ttoss.dev/docs/cli/commands/projects.md): See [Projects module docs](../../modules/projects) for permissions and data model. - [Quotas Commands](https://soat.ttoss.dev/docs/cli/commands/quotas.md): See [Quotas module docs](../../modules/quotas) for permissions and data model. - [Secrets Commands](https://soat.ttoss.dev/docs/cli/commands/secrets.md): See [Secrets module docs](../../modules/secrets) for permissions and data model. - [Sessions Commands](https://soat.ttoss.dev/docs/cli/commands/sessions.md): See [Sessions module docs](../../modules/sessions) for permissions and data model. - [Tasks Commands](https://soat.ttoss.dev/docs/cli/commands/tasks.md): See [Tasks module docs](../../modules/workflows) for permissions and data model. - [Tools Commands](https://soat.ttoss.dev/docs/cli/commands/tools.md): See [Tools module docs](../../modules/tools) for permissions and data model. - [Traces Commands](https://soat.ttoss.dev/docs/cli/commands/traces.md): See [Traces module docs](../../modules/traces) for permissions and data model. - [Triggers Commands](https://soat.ttoss.dev/docs/cli/commands/triggers.md): See [Triggers module docs](../../modules/triggers) for permissions and data model. - [Usage Commands](https://soat.ttoss.dev/docs/cli/commands/usage.md): See [Usage module docs](../../modules/usage) for permissions and data model. - [Users Commands](https://soat.ttoss.dev/docs/cli/commands/users.md): See [Users module docs](../../modules/users) for permissions and data model. - [Webhooks Commands](https://soat.ttoss.dev/docs/cli/commands/webhooks.md): See [Webhooks module docs](../../modules/webhooks) for permissions and data model. - [Workflows Commands](https://soat.ttoss.dev/docs/cli/commands/workflows.md): See [Workflows module docs](../../modules/workflows) for permissions and data model. - [Choosing a Client Surface](https://soat.ttoss.dev/docs/client-surfaces.md): Compare SOAT's four client surfaces — REST API, CLI, TypeScript SDK, and MCP — and pick the one that fits where your code runs. - [Error Codes](https://soat.ttoss.dev/docs/error-codes.md): Every error code the SOAT API can return, with its HTTP status and what to do about it. - [Actor](https://soat.ttoss.dev/docs/formations-types/actor.md): > This page is auto-generated from the formations OpenAPI spec. - [Agent](https://soat.ttoss.dev/docs/formations-types/agent.md): > This page is auto-generated from the formations OpenAPI spec. - [Ai Provider](https://soat.ttoss.dev/docs/formations-types/ai-provider.md): > This page is auto-generated from the formations OpenAPI spec. - [Api Key](https://soat.ttoss.dev/docs/formations-types/api-key.md): > This page is auto-generated from the formations OpenAPI spec. - [Chat](https://soat.ttoss.dev/docs/formations-types/chat.md): > This page is auto-generated from the formations OpenAPI spec. - [Conversation](https://soat.ttoss.dev/docs/formations-types/conversation.md): > This page is auto-generated from the formations OpenAPI spec. - [Dataset Item](https://soat.ttoss.dev/docs/formations-types/dataset-item.md): > This page is auto-generated from the formations OpenAPI spec. - [Dataset](https://soat.ttoss.dev/docs/formations-types/dataset.md): > This page is auto-generated from the formations OpenAPI spec. - [Document](https://soat.ttoss.dev/docs/formations-types/document.md): > This page is auto-generated from the formations OpenAPI spec. - [Eval](https://soat.ttoss.dev/docs/formations-types/eval.md): > This page is auto-generated from the formations OpenAPI spec. - [File](https://soat.ttoss.dev/docs/formations-types/file.md): > This page is auto-generated from the formations OpenAPI spec. - [Guardrail](https://soat.ttoss.dev/docs/formations-types/guardrail.md): > This page is auto-generated from the formations OpenAPI spec. - [Formation Resource Types](https://soat.ttoss.dev/docs/formations-types/formations-types.md): > This page is auto-generated from the formations OpenAPI spec. - [Ingestion Rule](https://soat.ttoss.dev/docs/formations-types/ingestion-rule.md): > This page is auto-generated from the formations OpenAPI spec. - [Memory Entry](https://soat.ttoss.dev/docs/formations-types/memory-entry.md): > This page is auto-generated from the formations OpenAPI spec. - [Memory](https://soat.ttoss.dev/docs/formations-types/memory.md): > This page is auto-generated from the formations OpenAPI spec. - [Model Route](https://soat.ttoss.dev/docs/formations-types/model-route.md): > This page is auto-generated from the formations OpenAPI spec. - [Orchestration](https://soat.ttoss.dev/docs/formations-types/orchestration.md): > This page is auto-generated from the formations OpenAPI spec. - [Policy](https://soat.ttoss.dev/docs/formations-types/policy.md): > This page is auto-generated from the formations OpenAPI spec. - [Project Price](https://soat.ttoss.dev/docs/formations-types/project-price.md): > This page is auto-generated from the formations OpenAPI spec. - [Quota](https://soat.ttoss.dev/docs/formations-types/quota.md): > This page is auto-generated from the formations OpenAPI spec. - [Secret](https://soat.ttoss.dev/docs/formations-types/secret.md): > This page is auto-generated from the formations OpenAPI spec. - [Session](https://soat.ttoss.dev/docs/formations-types/session.md): > This page is auto-generated from the formations OpenAPI spec. - [Tool](https://soat.ttoss.dev/docs/formations-types/tool.md): > This page is auto-generated from the formations OpenAPI spec. - [Trigger](https://soat.ttoss.dev/docs/formations-types/trigger.md): > This page is auto-generated from the formations OpenAPI spec. - [Webhook](https://soat.ttoss.dev/docs/formations-types/webhook.md): > This page is auto-generated from the formations OpenAPI spec. - [Workflow](https://soat.ttoss.dev/docs/formations-types/workflow.md): > This page is auto-generated from the formations OpenAPI spec. - [Introduction](https://soat.ttoss.dev/docs/introduction.md): SOAT is a self-hostable infrastructure layer for production-ready AI agents: IAM, storage, vector search, memory, orchestration, RAG, and a full MC... - [Activity](https://soat.ttoss.dev/mcp/tools/activity.md): MCP tools for the Activity module. See the [Activity module docs](/docs/modules/activity) for permissions and data model. - [Actors](https://soat.ttoss.dev/mcp/tools/actors.md): MCP tools for the Actors module. See the [Actors module docs](/docs/modules/actors) for permissions and data model. - [Agents](https://soat.ttoss.dev/mcp/tools/agents.md): MCP tools for the Agents module. See the [Agents module docs](/docs/modules/agents) for permissions and data model. - [AI Providers](https://soat.ttoss.dev/mcp/tools/ai-providers.md): MCP tools for the AI Providers module. See the [AI Providers module docs](/docs/modules/ai-providers) for permissions and data model. - [API Keys](https://soat.ttoss.dev/mcp/tools/api-keys.md): MCP tools for the API Keys module. See the [API Keys module docs](/docs/modules/api-keys) for permissions and data model. - [Approvals](https://soat.ttoss.dev/mcp/tools/approvals.md): MCP tools for the Approvals module. See the [Approvals module docs](/docs/modules/approvals) for permissions and data model. - [Audit Log](https://soat.ttoss.dev/mcp/tools/audit-log.md): MCP tools for the Audit Log module. See the [Audit Log module docs](/docs/modules/audit-log) for permissions and data model. - [Chains](https://soat.ttoss.dev/mcp/tools/chains.md): MCP tools for the Chains module. See the [Chains module docs](/docs/modules/chains) for permissions and data model. - [Chats](https://soat.ttoss.dev/mcp/tools/chats.md): MCP tools for the Chats module. See the [Chats module docs](/docs/modules/chats) for permissions and data model. - [Conversations](https://soat.ttoss.dev/mcp/tools/conversations.md): MCP tools for the Conversations module. See the [Conversations module docs](/docs/modules/conversations) for permissions and data model. - [Documents](https://soat.ttoss.dev/mcp/tools/documents.md): MCP tools for the Documents module. See the [Documents module docs](/docs/modules/documents) for permissions and data model. - [Embeddings](https://soat.ttoss.dev/mcp/tools/embeddings.md): MCP tools for the Embeddings module. See the [Embeddings module docs](/docs/modules/embeddings) for permissions and data model. - [Evaluations](https://soat.ttoss.dev/mcp/tools/evaluations.md): MCP tools for the Evaluations module. See the [Evaluations module docs](/docs/modules/evaluations) for permissions and data model. - [Exceptions](https://soat.ttoss.dev/mcp/tools/exceptions.md): MCP tools for the Exceptions module. See the [Exceptions module docs](/docs/modules/exceptions) for permissions and data model. - [Files](https://soat.ttoss.dev/mcp/tools/files.md): MCP tools for the Files module. See the [Files module docs](/docs/modules/files) for permissions and data model. - [Formations](https://soat.ttoss.dev/mcp/tools/formations.md): MCP tools for the Formations module. See the [Formations module docs](/docs/modules/formations) for permissions and data model. - [Generations](https://soat.ttoss.dev/mcp/tools/generations.md): MCP tools for the Generations module. See the [Generations module docs](/docs/modules/generations) for permissions and data model. - [Guardrails](https://soat.ttoss.dev/mcp/tools/guardrails.md): MCP tools for the Guardrails module. See the [Guardrails module docs](/docs/modules/guardrails) for permissions and data model. - [Ingestion Rules](https://soat.ttoss.dev/mcp/tools/ingestion-rules.md): MCP tools for the Ingestion Rules module. See the [Ingestion Rules module docs](/docs/modules/ingestion-rules) for permissions and data model. - [Knowledge](https://soat.ttoss.dev/mcp/tools/knowledge.md): MCP tools for the Knowledge module. See the [Knowledge module docs](/docs/modules/knowledge) for permissions and data model. - [Memories](https://soat.ttoss.dev/mcp/tools/memories.md): MCP tools for the Memories module. See the [Memories module docs](/docs/modules/memories) for permissions and data model. - [Memory Entries](https://soat.ttoss.dev/mcp/tools/memory-entries.md): MCP tools for the Memory Entries module. See the [Memory Entries module docs](/docs/modules/memories) for permissions and data model. - [Model Routes](https://soat.ttoss.dev/mcp/tools/model-routes.md): MCP tools for the Model Routes module. See the [Model Routes module docs](/docs/modules/model-routes) for permissions and data model. - [Orchestrations](https://soat.ttoss.dev/mcp/tools/orchestrations.md): MCP tools for the Orchestrations module. See the [Orchestrations module docs](/docs/modules/orchestrations) for permissions and data model. - [Policies](https://soat.ttoss.dev/mcp/tools/policies.md): MCP tools for the Policies module. See the [Policies module docs](/docs/modules/policies) for permissions and data model. - [Projects](https://soat.ttoss.dev/mcp/tools/projects.md): MCP tools for the Projects module. See the [Projects module docs](/docs/modules/projects) for permissions and data model. - [Quotas](https://soat.ttoss.dev/mcp/tools/quotas.md): MCP tools for the Quotas module. See the [Quotas module docs](/docs/modules/quotas) for permissions and data model. - [Secrets](https://soat.ttoss.dev/mcp/tools/secrets.md): MCP tools for the Secrets module. See the [Secrets module docs](/docs/modules/secrets) for permissions and data model. - [Sessions](https://soat.ttoss.dev/mcp/tools/sessions.md): MCP tools for the Sessions module. See the [Sessions module docs](/docs/modules/sessions) for permissions and data model. - [Tasks](https://soat.ttoss.dev/mcp/tools/tasks.md): MCP tools for the Tasks module. See the [Tasks module docs](/docs/modules/workflows) for permissions and data model. - [Tools](https://soat.ttoss.dev/mcp/tools/tools.md): MCP tools for the Tools module. See the [Tools module docs](/docs/modules/tools) for permissions and data model. - [Traces](https://soat.ttoss.dev/mcp/tools/traces.md): MCP tools for the Traces module. See the [Traces module docs](/docs/modules/traces) for permissions and data model. - [Triggers](https://soat.ttoss.dev/mcp/tools/triggers.md): MCP tools for the Triggers module. See the [Triggers module docs](/docs/modules/triggers) for permissions and data model. - [Usage](https://soat.ttoss.dev/mcp/tools/usage.md): MCP tools for the Usage module. See the [Usage module docs](/docs/modules/usage) for permissions and data model. - [Users](https://soat.ttoss.dev/mcp/tools/users.md): MCP tools for the Users module. See the [Users module docs](/docs/modules/users) for permissions and data model. - [Webhooks](https://soat.ttoss.dev/mcp/tools/webhooks.md): MCP tools for the Webhooks module. See the [Webhooks module docs](/docs/modules/webhooks) for permissions and data model. - [Workflows](https://soat.ttoss.dev/mcp/tools/workflows.md): MCP tools for the Workflows module. See the [Workflows module docs](/docs/modules/workflows) for permissions and data model. - [Permissions Reference](https://soat.ttoss.dev/docs/permissions.md): > This page is auto-generated. Do not edit manually — run `pnpm generate-permissions-page` to regenerate. - [Activity](https://soat.ttoss.dev/sdk/services/activity.md): SDK methods for the Activity module, accessed via `soat.activity`. See the [Activity module docs](/docs/modules/activity) for permissions and data ... - [Actors](https://soat.ttoss.dev/sdk/services/actors.md): SDK methods for the Actors module, accessed via `soat.actors`. See the [Actors module docs](/docs/modules/actors) for permissions and data model, a... - [Agents](https://soat.ttoss.dev/sdk/services/agents.md): SDK methods for the Agents module, accessed via `soat.agents`. See the [Agents module docs](/docs/modules/agents) for permissions and data model, a... - [AI Providers](https://soat.ttoss.dev/sdk/services/ai-providers.md): SDK methods for the AI Providers module, accessed via `soat.aiProviders`. See the [AI Providers module docs](/docs/modules/ai-providers) for permis... - [API Keys](https://soat.ttoss.dev/sdk/services/api-keys.md): SDK methods for the API Keys module, accessed via `soat.apiKeys`. See the [API Keys module docs](/docs/modules/api-keys) for permissions and data m... - [Approvals](https://soat.ttoss.dev/sdk/services/approvals.md): SDK methods for the Approvals module, accessed via `soat.approvals`. See the [Approvals module docs](/docs/modules/approvals) for permissions and d... - [Audit Log](https://soat.ttoss.dev/sdk/services/audit-log.md): SDK methods for the Audit Log module, accessed via `soat.auditLog`. See the [Audit Log module docs](/docs/modules/audit-log) for permissions and da... - [Chains](https://soat.ttoss.dev/sdk/services/chains.md): SDK methods for the Chains module, accessed via `soat.chains`. See the [Chains module docs](/docs/modules/chains) for permissions and data model, a... - [Chats](https://soat.ttoss.dev/sdk/services/chats.md): SDK methods for the Chats module, accessed via `soat.chats`. See the [Chats module docs](/docs/modules/chats) for permissions and data model, and e... - [Conversations](https://soat.ttoss.dev/sdk/services/conversations.md): SDK methods for the Conversations module, accessed via `soat.conversations`. See the [Conversations module docs](/docs/modules/conversations) for p... - [Documents](https://soat.ttoss.dev/sdk/services/documents.md): SDK methods for the Documents module, accessed via `soat.documents`. See the [Documents module docs](/docs/modules/documents) for permissions and d... - [Embeddings](https://soat.ttoss.dev/sdk/services/embeddings.md): SDK methods for the Embeddings module, accessed via `soat.embeddings`. See the [Embeddings module docs](/docs/modules/embeddings) for permissions a... - [Evaluations](https://soat.ttoss.dev/sdk/services/evaluations.md): SDK methods for the Evaluations module, accessed via `soat.evaluations`. See the [Evaluations module docs](/docs/modules/evaluations) for permissio... - [Exceptions](https://soat.ttoss.dev/sdk/services/exceptions.md): SDK methods for the Exceptions module, accessed via `soat.exceptions`. See the [Exceptions module docs](/docs/modules/exceptions) for permissions a... - [Files](https://soat.ttoss.dev/sdk/services/files.md): SDK methods for the Files module, accessed via `soat.files`. See the [Files module docs](/docs/modules/files) for permissions and data model, and e... - [Formations](https://soat.ttoss.dev/sdk/services/formations.md): SDK methods for the Formations module, accessed via `soat.formations`. See the [Formations module docs](/docs/modules/formations) for permissions a... - [Generations](https://soat.ttoss.dev/sdk/services/generations.md): SDK methods for the Generations module, accessed via `soat.generations`. See the [Generations module docs](/docs/modules/generations) for permissio... - [Guardrails](https://soat.ttoss.dev/sdk/services/guardrails.md): SDK methods for the Guardrails module, accessed via `soat.guardrails`. See the [Guardrails module docs](/docs/modules/guardrails) for permissions a... - [Ingestion Rules](https://soat.ttoss.dev/sdk/services/ingestion-rules.md): SDK methods for the Ingestion Rules module, accessed via `soat.ingestionRules`. See the [Ingestion Rules module docs](/docs/modules/ingestion-rules... - [Knowledge](https://soat.ttoss.dev/sdk/services/knowledge.md): SDK methods for the Knowledge module, accessed via `soat.knowledge`. See the [Knowledge module docs](/docs/modules/knowledge) for permissions and d... - [Memories](https://soat.ttoss.dev/sdk/services/memories.md): SDK methods for the Memories module, accessed via `soat.memories`. See the [Memories module docs](/docs/modules/memories) for permissions and data ... - [Memory Entries](https://soat.ttoss.dev/sdk/services/memory-entries.md): SDK methods for the Memory Entries module, accessed via `soat.memoryEntries`. See the [Memory Entries module docs](/docs/modules/memories) for perm... - [Model Routes](https://soat.ttoss.dev/sdk/services/model-routes.md): SDK methods for the Model Routes module, accessed via `soat.modelRoutes`. See the [Model Routes module docs](/docs/modules/model-routes) for permis... - [OAuth](https://soat.ttoss.dev/sdk/services/oauth.md): SDK methods for the OAuth module, accessed via `soat.oauth`. See the [OAuth module docs](/docs/modules/oauth) for permissions and data model, and e... - [Orchestrations](https://soat.ttoss.dev/sdk/services/orchestrations.md): SDK methods for the Orchestrations module, accessed via `soat.orchestrations`. See the [Orchestrations module docs](/docs/modules/orchestrations) f... - [Policies](https://soat.ttoss.dev/sdk/services/policies.md): SDK methods for the Policies module, accessed via `soat.policies`. See the [Policies module docs](/docs/modules/policies) for permissions and data ... - [Projects](https://soat.ttoss.dev/sdk/services/projects.md): SDK methods for the Projects module, accessed via `soat.projects`. See the [Projects module docs](/docs/modules/projects) for permissions and data ... - [Quotas](https://soat.ttoss.dev/sdk/services/quotas.md): SDK methods for the Quotas module, accessed via `soat.quotas`. See the [Quotas module docs](/docs/modules/quotas) for permissions and data model, a... - [Secrets](https://soat.ttoss.dev/sdk/services/secrets.md): SDK methods for the Secrets module, accessed via `soat.secrets`. See the [Secrets module docs](/docs/modules/secrets) for permissions and data mode... - [Sessions](https://soat.ttoss.dev/sdk/services/sessions.md): SDK methods for the Sessions module, accessed via `soat.sessions`. See the [Sessions module docs](/docs/modules/sessions) for permissions and data ... - [Tasks](https://soat.ttoss.dev/sdk/services/tasks.md): SDK methods for the Tasks module, accessed via `soat.tasks`. See the [Tasks module docs](/docs/modules/workflows) for permissions and data model, a... - [Tools](https://soat.ttoss.dev/sdk/services/tools.md): SDK methods for the Tools module, accessed via `soat.tools`. See the [Tools module docs](/docs/modules/tools) for permissions and data model, and e... - [Traces](https://soat.ttoss.dev/sdk/services/traces.md): SDK methods for the Traces module, accessed via `soat.traces`. See the [Traces module docs](/docs/modules/traces) for permissions and data model, a... - [Triggers](https://soat.ttoss.dev/sdk/services/triggers.md): SDK methods for the Triggers module, accessed via `soat.triggers`. See the [Triggers module docs](/docs/modules/triggers) for permissions and data ... - [Usage](https://soat.ttoss.dev/sdk/services/usage.md): SDK methods for the Usage module, accessed via `soat.usage`. See the [Usage module docs](/docs/modules/usage) for permissions and data model, and e... - [Users](https://soat.ttoss.dev/sdk/services/users.md): SDK methods for the Users module, accessed via `soat.users`. See the [Users module docs](/docs/modules/users) for permissions and data model, and e... - [Webhooks](https://soat.ttoss.dev/sdk/services/webhooks.md): SDK methods for the Webhooks module, accessed via `soat.webhooks`. See the [Webhooks module docs](/docs/modules/webhooks) for permissions and data ... - [Workflows](https://soat.ttoss.dev/sdk/services/workflows.md): SDK methods for the Workflows module, accessed via `soat.workflows`. See the [Workflows module docs](/docs/modules/workflows) for permissions and d... - [Configuration](https://soat.ttoss.dev/docs/self-hosting/configuration.md): Reference for every SOAT server environment variable, with guidance for production deployments. - [Webhook Events](https://soat.ttoss.dev/docs/webhook-events.md): Every event SOAT emits, the resource type each belongs to, and what it means.