OpenAPI Spec
The machine-readable contract for the CodeSpar API. Served without a key, so you can generate a client and read the surface before you have an account.
OpenAPI Spec
The API publishes an OpenAPI 3.1 document. It needs no credential, so you can read the contract and generate a client before you sign up.
https://api.codespar.dev/openapi.json
https://codespar.dev/openapi.json # same document, marketing origin
https://api.codespar.dev/v1/openapi.json # same document, original pathcurl -s https://api.codespar.dev/openapi.json | jq '.info.version, (.paths | keys)'The document declares its servers entry and a bearerAuth security scheme, so a generated client knows both the host to dial and that it must send Authorization: Bearer csk_....
npx @openapitools/openapi-generator-cli generate \
-i https://api.codespar.dev/openapi.json \
-g python \
-o ./codespar-clientNothing in the document varies by caller. It is built at boot from the same Zod schemas the routes validate with, so it is identical for everyone and safe to cache. The routes it describes still require a key.
What it covers today
Twenty-three operations across six surfaces:
| Surface | Operations |
|---|---|
| Sessions | POST /v1/sessions, GET /v1/sessions |
| Tool calls | GET /v1/tool-calls |
| Triggers | POST /v1/triggers, GET /v1/triggers |
| Identity | GET /v1/whoami |
| Policies | list, create, update, delete, reorder, plus GET /v1/evaluations |
| Wallets | create, list, get, ledger, funding sources, execute, reconciliation anomalies |
That is 23 of the 197 routes an API key can reach. The rest of this reference section documents the others in prose, and the gap is tracked in CI: a route added to the API must be described in the spec, or recorded by name in a ledger that says it is not. The number can shrink and cannot silently grow.
Request bodies and query parameters in the spec are generated from the routes' own validation schemas, so they track the implementation. Response schemas are written by hand against each handler and nothing tests them for drift yet. Treat a generated response type as documentation, not as a guarantee, and check the endpoint page in this section when the shape matters.
What it deliberately leaves out
Operator endpoints. /v1/api-keys, /v1/billing, /v1/team, /v1/usage and project membership answer only to a service key. An API key gets 401 on all of them, so describing them in a client contract would document a console you cannot call. They are reached from the dashboard.
The /mcp endpoint. POST /mcp and its session-scoped twin are not described here: the response is often a long-lived stream, and OpenAPI has no useful shape for it. What the endpoint speaks, and how to connect to it, is on the provider page; the wire contract is the protocol specification. Discovery is at /.well-known/oauth-protected-resource.
Internal routes. The /internal/* paths are operational probes gated on an environment token. They are not part of the API.
Related
- Authentication for how keys, environments and projects resolve
- SDK Reference if you are on TypeScript, and the Python quickstart if you are on Python
- Agent-Ready check, which scores
/openapi.jsonas a criterion for any API an agent has to discover