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

List attendance
Mark attendance
Grant makeup credits

API Reference / Attendance & Makeup Credits

Attendance & Makeup Credits

Read class check-ins, mark a swimmer present, or grant class makeup credits. Absence marking, unmarking and private-lesson attendance writes are outside this public API.

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/attendance

List attendance

Reads authoritative per-swimmer check-in/absence state from the exact occurrence roster, preserving sibling differences. Child status is present, absent or not_marked; transferred children and canceled family rows are excluded.

Access: attendance:read · MCP: get_attendance

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.
class_idstringRequired
At most 128 characters.
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/attendance" \
  -G \
  --data-urlencode 'class_id=class_example' \
  --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",
      "swimmer_ids": [
        "swimmer_example"
      ],
      "status": "active",
      "swimmers": [
        {
          "id": "swimmer_example",
          "status": "present",
          "checked_in_at": "2026-11-07T13:55:00.000Z"
        }
      ],
      "updated_at": "2026-11-07T13:55:00.000Z"
    }
  ],
  "next_cursor": null
}

POST/v1/attendance

Mark attendance

Checks in one enrolled swimmer using the same staff check-in operation as the app. Repeated check-in does not create another attendance event. There is no supported unmark/undo path.

Access: attendance:write · MCP: mark_attendance

Headers

Idempotency-KeystringRequired
Any unique string, like a UUID. Send the same key again and you get the first answer back instead of doing it twice. Keys last 24 hours.

Body

family_idstring
The family document id. Write bodies also accept parent_uid. At most 128 characters.
parent_uidstring
Alias for family_id; use one family identifier. At most 128 characters.
swimmer_idstringRequired
At most 128 characters.
class_idstringRequired
At most 128 characters.
instance_idstringRequired
The exact class occurrence id; a calendar date is not an instance id. At most 128 characters.
statusstring
Optional; present is the only supported mark. Allowed: "present". Default: "present".

Approval and retries

Ask Me First waits for owner approval; API keys and Can Act connections can execute eligible operations directly. Preserve one Idempotency-Key for identical retries. A pending proposal or queued job is not completed work.

Errors

Every error has the same shape: a type, a code you can switch on, a plain message, and a request_id for support. A param identifies the field at fault when available.

Status	Code	When
400	`invalid_parameter`	A required field is missing or malformed.
401	`invalid_token`	The key/token is invalid, revoked or expired.
403	`insufficient_scope`	The connection lacks the route’s access.
404	`not_found`	The school record is unavailable, including location-scoped reads.
409	`idempotency_conflict`	The same key was used for a different request.
422	`proposal_refused`	The existing Swum domain checks could not safely prepare this change.
429	`rate_limit_exceeded`	Wait the Retry-After interval.

Request

curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/attendance" \
  -X POST \
  -H "Authorization: Bearer ${SWUM_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${SWUM_IDEMPOTENCY_KEY}" \
  --data '{"family_id":"family_example","swimmer_id":"swimmer_example","class_id":"class_example","instance_id":"instance_example","status":"present"}'

200Executedapplication/json

{
  "status": "executed",
  "proposal_id": "7a1991ec-5e37-43a0-a581-84e817790e4b",
  "result": {
    "success": true,
    "message": "Completed.",
    "changes": {}
  }
}

202Pending owner approvalapplication/json

{
  "status": "pending_approval",
  "proposalId": "7a1991ec-5e37-43a0-a581-84e817790e4b",
  "proposal_id": "7a1991ec-5e37-43a0-a581-84e817790e4b"
}

POST/v1/credits

Grant makeup credits

Adds whole class makeup credits to an account-backed roster family. It does not grant cash, subtract credits or adjust time-bank balances.

Access: attendance:write · MCP: grant_makeup_credit

Headers

Idempotency-KeystringRequired
Any unique string, like a UUID. Send the same key again and you get the first answer back instead of doing it twice. Keys last 24 hours.

Body

family_idstring
The family document id. Write bodies also accept parent_uid. At most 128 characters.
parent_uidstring
Alias for family_id; use one family identifier. At most 128 characters.
amountintegerRequired
1–50 whole class credits. Minimum 1. Maximum 50.
notestring

Approval and retries

Errors

Every error has the same shape: a type, a code you can switch on, a plain message, and a request_id for support. A param identifies the field at fault when available.

Status	Code	When
400	`invalid_parameter`	A required field is missing or malformed.
401	`invalid_token`	The key/token is invalid, revoked or expired.
403	`insufficient_scope`	The connection lacks the route’s access.
404	`not_found`	The school record is unavailable, including location-scoped reads.
409	`idempotency_conflict`	The same key was used for a different request.
422	`proposal_refused`	The existing Swum domain checks could not safely prepare this change.
429	`rate_limit_exceeded`	Wait the Retry-After interval.

Request

curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/credits" \
  -X POST \
  -H "Authorization: Bearer ${SWUM_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${SWUM_IDEMPOTENCY_KEY}" \
  --data '{"family_id":"family_example","amount":1,"note":"School-approved makeup"}'

200Executedapplication/json

{
  "status": "executed",
  "proposal_id": "7a1991ec-5e37-43a0-a581-84e817790e4b",
  "result": {
    "success": true,
    "message": "Completed.",
    "changes": {}
  }
}

202Pending owner approvalapplication/json

{
  "status": "pending_approval",
  "proposalId": "7a1991ec-5e37-43a0-a581-84e817790e4b",
  "proposal_id": "7a1991ec-5e37-43a0-a581-84e817790e4b"
}