---
title: Build on Soljio
description: Connect your swim school's own systems and AI agents to Soljio with the HTTP API, service tokens, and the MCP server.
---

Soljio's developer tools connect a swim school's own systems and AI agents to its Soljio workspace. You can read programs, sessions, class dates, students, and enrollments, run filtered queries, and run the same commands staff run in the dashboard.

## What people build

- 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.

## Two ways in

Both paths reach the same operations, run the same checks, and act on exactly one school.

|  | HTTP API | MCP server |
| --- | --- | --- |
| Best for | Scripts, back-office syncs, and your own software | AI agents such as ChatGPT or Claude |
| Address | `https://api.soljio.com/v0` | `https://soljio.com/mcp` |
| Credential | A service token sent as a bearer token | An OAuth connection that a school owner or admin approves |
| Created by | An owner or admin under **Dashboard → Settings → Integrations** | An owner or admin on the **Connect an agent** page |
| Access | The scopes chosen when the token is created | The access chosen when the agent is approved, never more than that person's role allows |

The HTTP API accepts service tokens only. The MCP server accepts agent connections only. A token from one does not work on the other.

## Ground rules

- **One school per credential.** A token or agent connection belongs to a single school. Requests never name the school, and a request body cannot override it.
- **Scopes are additive.** A credential can do only what it was granted. Write access never implies read access. See [Scopes](/developers/scopes).
- **JSON in, JSON out.** Properties use `snake_case`, identifiers are opaque strings, and timestamps are RFC 3339 UTC. See [Requests and responses](/developers/requests-and-responses).
- **Writes are retry-safe.** Every command needs an `Idempotency-Key` header. See [Idempotency](/developers/idempotency).
- **Risky changes are previewed first.** Schedule-changing commands are applied with an approval token from a preview. See [Previews and approvals](/developers/previews-and-approvals).

## Names in the API

The API uses the names in its contract. The dashboard uses Soljio's everyday words for the same things.

| In the dashboard                          | In the API     |
| ----------------------------------------- | -------------- |
| Program                                   | `programs`     |
| Session (one enrollable run of a program) | `offerings`    |
| Class date (one meeting of a session)     | `sessions`     |
| Student                                   | `participants` |
| Enrollment                                | `enrollments`  |
| Instructor                                | `instructors`  |
| Location                                  | `locations`    |

Pages in this section use the API's names inside code and the dashboard's words in prose.

## Where to go next

**[Quickstart](/developers/quickstart)**

Create a token and make your first request in a few minutes.

**[Authentication](/developers/authentication)**

Create, rotate, and revoke service tokens, and send them correctly.

**[Scopes](/developers/scopes)**

Every scope, what it allows, and who can grant it.

**[Requests and responses](/developers/requests-and-responses)**

Paths, headers, body limits, response envelopes, and status codes.

**[Pagination](/developers/pagination)**

Page through lists with cursors.

**[Idempotency](/developers/idempotency)**

Retry commands without repeating their effects.

**[Previews and approvals](/developers/previews-and-approvals)**

Review a change, then apply it with an approval token.

**[Async operations](/developers/async-operations)**

Follow jobs for invitations, domains, payments, and reports.

**[Errors](/developers/errors)**

The error body, every error code, and how to respond.

**[Rate limits](/developers/rate-limits)**

Request budgets, rate-limit headers, and retrying a 429.

**[Agents and MCP](/developers/agents-and-mcp)**

The MCP server, its tools, and how tool approval works.

**[Connect an agent](/developers/connect-an-agent)**

What a school owner or admin sees when approving an agent.

**[OpenAPI contract](/developers/openapi)**

Fetch the contract, understand versions, and generate clients.

**[API reference](/api)**

Every operation with request and response schemas and code samples.
