---
title: Requests and responses
description: 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](/api).

## 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](/developers/async-operations) |
| 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.

:::note[Order of checks]
Soljio inspects a request in this order: the bearer header's shape (`401`), the path and method (`404`, `405`), the body and its headers (`415`, `413`, `400`), the credential and its scopes (`401`, `403`), the rate limit (`429`), and then the operation itself. So a request with a bad token and a missing `Content-Type` gets `415`, not `401`.
:::

## Request headers

| Header | When | Notes |
| --- | --- | --- |
| `Authorization: Bearer soljio_sk_...` | Every request except fetching the contract | See [Authentication](/developers/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](/developers/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](/developers/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](/developers/scopes).

## Caching

Authenticated responses are never cacheable. The contract itself, at `/v0/openapi.json`, is public and cacheable for five minutes. See [OpenAPI contract](/developers/openapi).
