Skip to content
Soljio Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 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
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-Key header 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}) and get_job (POST /queries/get_job) return the same body. See 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.

Was this page helpful?