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

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_import and apply_import, allow 524,288 bytes and at most 250 rows per batch. A larger body returns 413 with payload_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 limit and cursor in the query string. Anything else, or a repeated parameter, returns 400.
  • 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 null only where the contract declares it is allowed.
  • Imports. In an import command, rows[].values is a dictionary keyed by column. Use the exact keys that get_import_templates returns. 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.

Was this page helpful?