Requests and responses
Paths, required headers, body limits, the response envelope, success status codes, and value conventions for the Soljio HTTP API.
This page collects the conventions every operation shares. The base URL is https://api.soljio.com/v0. Each operation’s exact fields are in the API reference.
Three kinds of request
| Kind | Method and path | Use it to |
|---|---|---|
| Resource read | GET /v0/{resource} and GET /v0/{resource}/{id} |
List or fetch organizations, locations, programs, offerings, sessions, participants, and enrollments |
| Job read | GET /v0/jobs/{id} |
Follow an async operation |
| Query | POST /v0/queries/{operation} |
Read with filters, searches, and richer views |
| Command | POST /v0/commands/{operation} |
Change data or start work |
Resource reads also answer HEAD with the same status and headers and no body. A HEAD error has no body either.
An unknown path returns 404. A known path with the wrong method returns 405 and an Allow header: GET, HEAD for reads and POST for queries and commands.
Request headers
| Header | When | Notes |
|---|---|---|
Authorization: Bearer soljio_sk_... |
Every request except fetching the contract | See Authentication |
Content-Type: application/json |
Every POST |
Parameters such as charset are accepted. Anything else returns 415 |
Idempotency-Key |
Every command | 1 to 128 visible ASCII characters. See Idempotency |
Request bodies
- The body is a JSON object in UTF-8. A missing body, invalid JSON, or invalid UTF-8 returns
400. For a query with no filters, send{}. - The limit is 16,384 bytes. The two import commands,
dry_run_importandapply_import, allow 524,288 bytes and at most 250 rows per batch. A larger body returns413withpayload_too_large. - Bodies are strict. Unknown fields are rejected.
- Queries and commands take no query-string parameters. Adding one returns
400. - Resource reads accept only
limitandcursorin the query string. Anything else, or a repeated parameter, returns400. - A command takes its idempotency key from the header only. There is no key field in the JSON body.
Response envelope
Every success is a JSON object with request_id, a UUID that identifies the request. Quote it when you contact Soljio.
| Operation | Fields |
|---|---|
| Resource list | data (array), next_cursor (string or null), request_id |
| Resource detail | data (object), request_id |
| Query | data, request_id |
| Command | data, idempotent_replay (boolean), request_id |
data can be a resource, an opaque ID, null, or a typed result, as the operation defines.
Every response, including errors, carries these headers:
| Header | Value |
|---|---|
Content-Type |
application/json; charset=utf-8 |
Cache-Control |
no-store |
X-Request-Id |
The identifier of this HTTP attempt |
X-Content-Type-Options |
nosniff |
RateLimit-Policy |
The request budgets. See Rate limits |
X-Request-Id names the current attempt. When a command is replayed, the body keeps the original request_id while X-Request-Id identifies the new attempt.
Success status codes
| Status | Meaning |
|---|---|
200 |
The request succeeded |
201 |
A resource was created. Location is its path, such as /v0/programs/PROGRAM_ID |
202 |
Background work was accepted. Location is the job path, such as /v0/jobs/JOB_ID |
These commands return 201: create_program, create_offering, create_session, create_participant, and create_enrollment. create_participant returns 201 even when it also queues an invitation.
These commands return 202 with a job: invite_staff, resend_staff_invitation, request_custom_domain, refresh_custom_domain, disable_custom_domain, sync_payment_connection, disconnect_payment_connection, and preview_notification_template. send_household_claim returns 202 when it queues an invitation and 200 when the household is already claimed.
To follow a Location you need the read scope for that resource or job.
Value conventions
- Names. JSON properties use
snake_case. - IDs. Identifiers are opaque strings of 1 to 256 characters. Do not parse them or construct them. An ID from another school and an ID that does not exist both return
404, so you cannot probe for other schools’ records. - Instants. Timestamps are RFC 3339 UTC strings, such as
2026-01-05T17:04:11.000Z. - Local schedules. Recurring and explicit schedules carry local dates and times together with an IANA timezone, such as
America/Los_Angeles. - Optional values. Optional fields are omitted when empty. Send an explicit
nullonly where the contract declares it is allowed. - Imports. In an import command,
rows[].valuesis a dictionary keyed by column. Use the exact keys thatget_import_templatesreturns. It also describes required columns and sample rows.
Minimized reads
The basic resource reads return minimized models. Contact details, dates of birth, notes, message contents, and payment details are available only from richer queries, and only with their specific sensitive scopes. See Scopes.
Caching
Authenticated responses are never cacheable. The contract itself, at /v0/openapi.json, is public and cacheable for five minutes. See OpenAPI contract.