Soljio REST API and MCP for developers

The Soljio API lets a swim school connect its own systems and AI agents to its Soljio workspace: read programs, offerings, sessions, participants, and enrollments, run filtered queries, and run the same commands staff use in the dashboard.

When to use the Soljio API

  • Sync a school's programs, schedules, rosters, or enrollments with another system
  • Build reports or dashboards from a school's own data
  • Let an AI agent answer questions about a school's schedule, or prepare changes for staff to approve

Soljio API reference

  • Base URL: https://api.soljio.com/v0
  • OpenAPI contract: https://api.soljio.com/v0/openapi.json, also at /openapi.json. Every operation has an operationId, a description, and typed request and response schemas, so it can be loaded straight into an LLM function-calling or tool definition.
  • Formats: JSON request and response bodies with snake_case properties and RFC 3339 UTC timestamps.

Soljio API authentication

Every request except the contract itself needs an organization service token. School owners create one under Dashboard → Settings → Integrations and choose its scopes. Send it as a bearer token:

GET /v0/programs?limit=25 HTTP/1.1
Host: api.soljio.com
Authorization: Bearer <service-token>

A token belongs to exactly one school, so requests never name the school. Missing scopes return 403; grants are additive and writes do not imply reads.

Commands and retries

Commands are POST /v0/commands/<operation> and need an Idempotency-Key header. Retrying with the same key and body returns the original result without repeating the work. Schedule changes are previewed first and applied with the returned approval token.

Soljio API errors

Every REST error body is JSON with a stable code, a message, and the request ID to quote when you contact us. The Soljio OpenAPI contract references a typed error schema and an example for each 4xx and 5xx response. HEAD returns the same status and headers with no body:

{"error":{"code":"not_found","message":"The requested resource was not found."},"request_id":"uuid"}
  • 400 invalid_request: fix the fields the message names.
  • 401 unauthorized: send a valid, unexpired service token.
  • 403 forbidden: ask the school owner to add the missing scope.
  • 404 not_found: check the ID and that it belongs to this school.
  • 409 conflict: read the resource again, then retry with a new idempotency key.
  • 409 idempotency_conflict: reuse a key only with the same body.
  • 405 method_not_allowed: use a method listed in the Allow header.
  • 413 payload_too_large: reduce the request body.
  • 415 unsupported_media_type: send Content-Type: application/json.
  • 500 internal_error: retry with backoff and the same idempotency key.
  • 429 rate_limited: wait for the Retry-After seconds, then retry with the same key.

Soljio API rate limits

Each service token has a bucket of 120 requests, and each school a shared bucket of 600 requests across all of its tokens. Buckets refill continuously at 120 and 600 requests per minute. Reads, HEADs, queries, commands, and idempotent replays each cost one request.

REST responses advertise the policies in RateLimit-Policy. Once a request passes authorization and reaches quota evaluation, successful responses and errors also include a RateLimit snapshot of the remaining budget after this attempt:

RateLimit-Policy: "token";q=120;w=60, "organization";q=600;w=60
RateLimit: "token";r=119;t=60, "organization";r=599;t=60

These are Structured Fields lists following the IETF RateLimit header fields draft. Each quoted name identifies a policy: q is its quota and w its window in seconds; r is the currently available request count and t=60 is the effective window in seconds. It is not a Unix timestamp or a promise that the budget resets all at once. Other requests may consume the shared budget.

A 429 includes both headers and Retry-After as a positive integer number of seconds. Wait at least that long, then retry with backoff and the same idempotency key. Requests rejected before quota evaluation include the policy but no remaining-budget snapshot. Public documentation and the MCP resource server do not consume these authenticated REST quotas.

Soljio MCP server

Soljio runs a Model Context Protocol server at https://soljio.com/mcp over Streamable HTTP. It exposes the API contract and this guide as resources so an agent can read them before calling the API. Its server card is listed in the site's AI catalog.

More

  • llms.txt: every public page on soljio.com, for AI agents
  • Contact: questions about the API or access for your school