---
title: OpenAPI contract
description: 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](/api) 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:

```bash
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](/developers/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 format `soljio_sk_<secret>`. Its scope requirements are in `x-required-scopes` on each operation, not in OAuth scopes.
- **200 paths.** Resource reads for `organizations`, `locations`, `programs`, `offerings`, `sessions`, `participants`, and `enrollments`, with a `HEAD` operation for each; a job read; 78 `POST /queries/...` operations; and 107 `POST /commands/...` operations.
- **Unique operation IDs.** Each operation has a `snake_case` `operationId` such as `list_programs`, `search_programs`, or `create_program`. `HEAD` operations are prefixed with `head_`.
- **Shared parts.** Reusable parameters (`Id`, `Limit`, `Cursor`, and `IdempotencyKey`), 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](/developers/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](/developers/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:

```bash
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-Key` header parameter. A generated client does not create one for you. Supply a durable key per logical operation. See [Idempotency](/developers/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}`) and `get_job` (`POST /queries/get_job`) return the same body. See [Async operations](/developers/async-operations).
- **Response envelope.** Responses wrap results in `data` and `request_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.
