# OpenAPI Specifications

> Machine-readable OpenAPI specifications for the SOAT REST API, as one merged bundle or one file per module.

# OpenAPI Specifications

The SOAT REST API is fully documented using OpenAPI 3.x specifications. They are
the source of truth for the [TypeScript SDK](./sdk/introduction.md), the
[`soat` CLI](./cli/introduction.md) and the [MCP tool surface](./mcp/introduction.md), and they
are published here for any OpenAPI-compatible tool — Postman, Swagger UI, code
generators, AI agents.

## Merged bundle

Every module in one document, with all `$ref`s resolved inside the bundle:

| Document | URL |
| -------- | --- |
| OpenAPI (JSON) | [/openapi.json](/openapi.json) |
| OpenAPI (YAML) | [/openapi.yaml](/openapi.yaml) |
| OpenAPI (YAML, `/api` path) | [/api/openapi.yaml](/api/openapi.yaml) |
| Error-code catalog (JSON) | [/errors.json](/errors.json) |

The bundle's `servers` entry is a `baseUrl` variable: SOAT is self-hosted, so
point it at your own deployment. A running deployment serves the same merged
document at `/api/v1/openapi.json` (authenticated).

Errors are documented twice over, for machines: the `ErrorResponse` schema
describes the envelope, and the `x-error-codes` extension — the same data as
[/errors.json](/errors.json) — lists every code with its HTTP status and
meaning. See [Error Responses](./api/index.md) for the contract in prose.

## Per-module specs

One YAML file per module, served at `/openapi/<module>.yaml`, for tools that
prefer a narrower surface.

| Module | URL |
| ------ | --- |
| Activity | [/openapi/activity.yaml](/openapi/activity.yaml) |
| Actors | [/openapi/actors.yaml](/openapi/actors.yaml) |
| Agents | [/openapi/agents.yaml](/openapi/agents.yaml) |
| Ai Providers | [/openapi/ai-providers.yaml](/openapi/ai-providers.yaml) |
| Api Keys | [/openapi/api-keys.yaml](/openapi/api-keys.yaml) |
| Approvals | [/openapi/approvals.yaml](/openapi/approvals.yaml) |
| Audit Log | [/openapi/audit-log.yaml](/openapi/audit-log.yaml) |
| Chains | [/openapi/chains.yaml](/openapi/chains.yaml) |
| Chats | [/openapi/chats.yaml](/openapi/chats.yaml) |
| Conversations | [/openapi/conversations.yaml](/openapi/conversations.yaml) |
| Documents | [/openapi/documents.yaml](/openapi/documents.yaml) |
| Embeddings | [/openapi/embeddings.yaml](/openapi/embeddings.yaml) |
| Evaluations | [/openapi/evaluations.yaml](/openapi/evaluations.yaml) |
| Exceptions | [/openapi/exceptions.yaml](/openapi/exceptions.yaml) |
| Files | [/openapi/files.yaml](/openapi/files.yaml) |
| Formations | [/openapi/formations.yaml](/openapi/formations.yaml) |
| Generations | [/openapi/generations.yaml](/openapi/generations.yaml) |
| Guardrails | [/openapi/guardrails.yaml](/openapi/guardrails.yaml) |
| Ingestion Rules | [/openapi/ingestion-rules.yaml](/openapi/ingestion-rules.yaml) |
| Knowledge | [/openapi/knowledge.yaml](/openapi/knowledge.yaml) |
| Memories | [/openapi/memories.yaml](/openapi/memories.yaml) |
| Memory Entries | [/openapi/memory-entries.yaml](/openapi/memory-entries.yaml) |
| Model Routes | [/openapi/model-routes.yaml](/openapi/model-routes.yaml) |
| Oauth | [/openapi/oauth.yaml](/openapi/oauth.yaml) |
| Orchestrations | [/openapi/orchestrations.yaml](/openapi/orchestrations.yaml) |
| Policies | [/openapi/policies.yaml](/openapi/policies.yaml) |
| Projects | [/openapi/projects.yaml](/openapi/projects.yaml) |
| Quotas | [/openapi/quotas.yaml](/openapi/quotas.yaml) |
| Secrets | [/openapi/secrets.yaml](/openapi/secrets.yaml) |
| Sessions | [/openapi/sessions.yaml](/openapi/sessions.yaml) |
| Tasks | [/openapi/tasks.yaml](/openapi/tasks.yaml) |
| Tools | [/openapi/tools.yaml](/openapi/tools.yaml) |
| Traces | [/openapi/traces.yaml](/openapi/traces.yaml) |
| Triggers | [/openapi/triggers.yaml](/openapi/triggers.yaml) |
| Usage | [/openapi/usage.yaml](/openapi/usage.yaml) |
| Users | [/openapi/users.yaml](/openapi/users.yaml) |
| Webhooks | [/openapi/webhooks.yaml](/openapi/webhooks.yaml) |
| Workflows | [/openapi/workflows.yaml](/openapi/workflows.yaml) |