Choosing a Client Surface
Every SOAT operation is exposed through four interchangeable client surfaces. They call the same business logic, enforce the same permission actions, and return the same response shapes — the only difference is ergonomics. Pick the surface that fits where your code runs.
| Surface | Best for | Setup guide |
|---|---|---|
| REST API | Backend services in any language, custom integrations | API Reference |
SDK (@soat/sdk) | TypeScript and JavaScript applications | SDK Introduction |
CLI (soat) | Scripts, CI pipelines, local exploration | CLI Introduction |
| MCP server | Claude Desktop, Cursor, and other MCP-aware runtimes | Connecting an MCP Client |
Rules of thumb
- Building a product on SOAT? Use the SDK if you are in TypeScript — every endpoint, parameter, and response body is fully typed and generated from the OpenAPI specs. In any other language, call the REST API directly.
- Automating or exploring? Use the CLI. Every API operation is a sub-command (
soat create-agent,soat list-documents), so anything you can do in code you can do in a shell script or CI job. - Working from an AI assistant? Connect the MCP server. Any MCP-compatible client can manage projects, agents, documents, and the rest directly from a chat or coding session.
What is identical across surfaces
- Authentication — a user JWT or an
sk_-prefixed API key works on all four surfaces. See IAM & Policies. - Permissions — each operation is gated by a single
resource:Actionpermission string (e.g.documents:CreateDocument), enforced consistently everywhere. See the Permissions Reference. - Data — a resource created on one surface is immediately visible on the others; they share one backend and one database.
Field naming
The REST API and SDK use snake_case for body fields and path parameters (project_id, {agent_id}). MCP tool schemas use camelCase (projectId). The CLI uses kebab-case flags (--project-id).