DevelopersGet API Key

Enterprise: the API, webhooks and MCP server are live for schools on the Enterprise plan. The owner allows every key and AI connection. Ask about Enterprise

On this page

API Reference / Classes

Classes

Read classes and their exact occurrences. Rosters and open spots require an instance_id. These reads do not reserve a place.

3,000requests per UTC hour
10requests a second, in bursts
429when over, with Retry-After and X-RateLimit-Remaining

Per key or agent connection, on the Enterprise plan.

GET/v1/classes

List classes

Lists classes from the owner’s class directory. No day, level or location query filter is currently applied; the connection’s location scope is always enforced.

Access: classes:read · MCP: list_classes

Headers

  • AuthorizationstringRequired

    Bearer <token>: an API key or an agent OAuth access token. App subscription routes require a dedicated app key.

  • Swum-Versiondate

    Pins the response shape. Default: 2026-10-25.

Query parameters

  • updated_sincedate-time

    Effective update time after an ISO 8601 timestamp with an explicit time zone. Follow every page, including the legacy-record suffix.

  • limitinteger

    1–200; default 50. Minimum 1. Maximum 200. Default: 50.

  • cursorstring

    Opaque next_cursor from the previous page. Keep the same filters.

Pagination

Keep calling with cursor=next_cursor until next_cursor is null. A filtered page may be short or empty while a next cursor remains.

Request
curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/classes" \
  -H "Authorization: Bearer ${SWUM_API_KEY}"
200Responseapplication/json
{
  "data": [
    {
      "id": "class_example",
      "name": "Saturday Beginners",
      "location_id": "pool_example",
      "status": "active",
      "capacity": 6,
      "start_at": "2026-11-07T14:00:00.000Z",
      "end_at": "2026-11-07T14:30:00.000Z",
      "updated_at": null
    }
  ],
  "next_cursor": null
}
GET/v1/classes/{id}

Get a class

Returns an owner-verified class.

Access: classes:read · MCP: get_class

Path parameters

  • idstringRequired

    The exact Swum document id.

Query parameters

  • updated_sincedate-time

    ISO 8601 datetime with an explicit time zone. Exclusive on lists; detail/open-spots reads validate it and return the current object.

Request
curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/classes/class_example" \
  -H "Authorization: Bearer ${SWUM_API_KEY}"
200Responseapplication/json
{
  "data": {
    "id": "class_example",
    "name": "Saturday Beginners",
    "location_id": "pool_example",
    "status": "active",
    "capacity": 6,
    "start_at": "2026-11-07T14:00:00.000Z",
    "end_at": "2026-11-07T14:30:00.000Z",
    "updated_at": null
  }
}
GET/v1/classes/{id}/instances

List class instances

Use these occurrence ids for roster, enrollment and attendance calls.

Access: classes:read · MCP: list_class_dates

Path parameters

  • idstringRequired

    The exact Swum document id.

Query parameters

  • updated_sincedate-time

    Effective update time after an ISO 8601 timestamp with an explicit time zone. Follow every page, including the legacy-record suffix.

  • limitinteger

    1–200; default 50. Minimum 1. Maximum 200. Default: 50.

  • cursorstring

    Opaque next_cursor from the previous page. Keep the same filters.

Pagination

Keep calling with cursor=next_cursor until next_cursor is null. A filtered page may be short or empty while a next cursor remains.

Request
curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/classes/class_example/instances" \
  -H "Authorization: Bearer ${SWUM_API_KEY}"
200Responseapplication/json
{
  "data": [
    {
      "id": "instance_example",
      "class_id": "class_example",
      "date": "2026-11-07",
      "start_at": "2026-11-07T14:00:00.000Z",
      "end_at": "2026-11-07T14:30:00.000Z",
      "status": "active"
    }
  ],
  "next_cursor": null
}
GET/v1/classes/{id}/roster

Get a class roster

Returns paginated participant families and per-swimmer enrollment/check-in status for one occurrence. Canceled family rows and transferred-out swimmers are excluded.

Access: classes:read · MCP: get_class_roster

Path parameters

  • idstringRequired

    The exact Swum document id.

Query parameters

  • updated_sincedate-time

    Effective update time after an ISO 8601 timestamp with an explicit time zone. Follow every page, including the legacy-record suffix.

  • limitinteger

    1–200; default 50. Minimum 1. Maximum 200. Default: 50.

  • cursorstring

    Opaque next_cursor from the previous page. Keep the same filters.

  • instance_idstringRequired

    The exact class occurrence id; a calendar date is not an instance id. At most 128 characters.

Pagination

Keep calling with cursor=next_cursor until next_cursor is null. A filtered page may be short or empty while a next cursor remains.

Request
curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/classes/class_example/roster" \
  -G \
  --data-urlencode 'instance_id=instance_example' \
  -H "Authorization: Bearer ${SWUM_API_KEY}"
200Responseapplication/json
{
  "data": [
    {
      "id": "family_example",
      "family_id": "family_example",
      "class_id": "class_example",
      "instance_id": "instance_example",
      "status": "active",
      "swimmer_ids": [
        "swimmer_example"
      ],
      "swimmers": [
        {
          "id": "swimmer_example",
          "name": "Avery Rivera",
          "status": "active",
          "absent": false,
          "enrollment_kind": "permanent",
          "checked_in_at": null,
          "scheduled_drop_date": null
        }
      ],
      "updated_at": null
    }
  ],
  "next_cursor": null
}
GET/v1/classes/{id}/open-spots

Get open spots

Returns configured capacity minus active and scheduled-drop swimmer count; absences, transferred swimmers and canceled families do not consume this count. Canceled classes/instances report zero open spots. Instances above 200 family records return roster_too_large. This is a class-occurrence view, not a private-lesson availability search or a reservation.

Access: classes:read · MCP: list_open_spots

Path parameters

  • idstringRequired

    The exact Swum document id.

Query parameters

  • updated_sincedate-time

    ISO 8601 datetime with an explicit time zone. Exclusive on lists; detail/open-spots reads validate it and return the current object.

  • instance_idstringRequired

    The exact class occurrence id; a calendar date is not an instance id. At most 128 characters.

Request
curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/classes/class_example/open-spots" \
  -G \
  --data-urlencode 'instance_id=instance_example' \
  -H "Authorization: Bearer ${SWUM_API_KEY}"
200Responseapplication/json
{
  "data": {
    "class_id": "class_example",
    "instance_id": "instance_example",
    "status": "active",
    "capacity": 6,
    "enrolled": 4,
    "open_spots": 2
  }
}

The class object

  • idstring
  • namestring
  • location_idstring | null
  • capacitynumber
  • statusstring
  • start_attimestamp | null
  • end_attimestamp | null
  • updated_attimestamp | null