OpenAPI contract
Where to fetch Soljio's OpenAPI contract, how API v0 relates to OpenAPI 3.1.2, and how to use the contract for clients and tool definitions.
The Soljio API is described by an OpenAPI contract. It is the complete reference for paths, parameters, request and response schemas, scopes, and errors. The API reference on this site is generated from the same document, so the two never disagree.
Fetch the contract
Both addresses return the same JSON document and need no authentication:
curl -sS https://api.soljio.com/v0/openapi.json -o soljio-openapi.json
curl -sS https://soljio.com/openapi.json -o soljio-openapi.json
The document is cacheable for five minutes (Cache-Control: public, max-age=300). The copy on soljio.com also allows cross-origin reads, so a browser tool can load it directly.
Agents can read it through the documentation MCP server at https://soljio.com/mcp/docs without downloading the file. See Agents and MCP.
Versions
Three different version numbers are involved:
| What | Value | Where it appears |
|---|---|---|
| API version | v0 |
The first path segment, as in https://api.soljio.com/v0, and in how idempotency keys are scoped |
| OpenAPI format | 3.1.2 |
The openapi field. It says how the document is written, using JSON Schema 2020-12 |
| Contract document version | 0.1.0 |
info.version in the document |
They are independent. A new format release of OpenAPI does not change the API, and a change to the contract does not change the path.
Pin your client to a copy of the contract and regenerate it when you want new operations. The contract’s info.title is Soljio Organization API. It covers one school’s operations. Family self-service and platform administration are outside this API.
What the contract contains
- One server.
https://api.soljio.com/v0. - One security scheme.
serviceToken, an HTTP bearer scheme with the formatsoljio_sk_<secret>. Its scope requirements are inx-required-scopeson each operation, not in OAuth scopes. - 200 paths. Resource reads for
organizations,locations,programs,offerings,sessions,participants, andenrollments, with aHEADoperation for each; a job read; 78POST /queries/...operations; and 107POST /commands/...operations. - Unique operation IDs. Each operation has a
snake_caseoperationIdsuch aslist_programs,search_programs, orcreate_program.HEADoperations are prefixed withhead_. - Shared parts. Reusable parameters (
Id,Limit,Cursor, andIdempotencyKey), typed error responses for each status, and the response schemas. - Soljio extensions. Fields starting with
x-are described below.
Extensions
| Extension | On | Meaning |
|---|---|---|
x-required-scopes |
Every operation | The scopes the operation needs unconditionally. See Scopes |
x-scope-rules |
Commands with conditional grants | Extra scopes and the condition under which each applies |
x-mcp |
Every operation | expose, readOnly, and approval. They drive how the operation appears as an MCP tool. See Agents and MCP |
x-max-request-bytes |
Commands | The largest request body the operation accepts, in bytes, where the operation declares one |
Other x- fields can appear in the document. Ignore any that you do not recognize.
Generate a client or types
The contract is OpenAPI 3.1, so use a generator that supports 3.1. For TypeScript types, for example:
npx openapi-typescript https://api.soljio.com/v0/openapi.json -o soljio.d.ts
Keep these points in mind when you wire up a generated client:
- Authentication. Configure the bearer token once. A token starts with
soljio_sk_. - Idempotency. Each command lists an
Idempotency-Keyheader parameter. A generated client does not create one for you. Supply a durable key per logical operation. See Idempotency. - Strict schemas. Request bodies reject unknown fields, so do not add fields that are not in the schema.
- Two ways to read some data. Resource reads (
GET) and filtered queries (POST) are separate operations. Use the one that fits. - Job reads.
get_job_resource(GET /jobs/{id}) andget_job(POST /queries/get_job) return the same body. See Async operations. - Response envelope. Responses wrap results in
dataandrequest_id. Use the response schemas to type them.
Use the contract for agent tools
Every operation has an operationId, a description, and typed request and response schemas, so you can load the contract into an LLM function-calling or tool definition. If you build your own agent tools on the HTTP API, filter by x-mcp.expose and use x-mcp.readOnly and x-mcp.approval the way Soljio’s own MCP server does: require a person’s confirmation before calling any operation marked approval: required.
Troubleshooting
- The generator rejects the document. Use a version that supports OpenAPI 3.1 and JSON Schema 2020-12.
- A scope in the document does not seem to apply. Check
x-scope-rules. Some scopes apply only when a request includes certain fields.