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 swimmers
Get a swimmer
Move a swimmer group
Add a swimmer
Update a swimmer
Add a swimmer note
The swimmer object

API Reference / Swimmers

Swimmers

Read account-backed or manual roster swimmers, add or update permitted identity/placement fields, and add staff-private notes. No Auth account is created or linked. Public projections do not expose medical details.

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

List swimmers

Lists roster swimmers. family_id optionally limits the scan to one family. There are no pool/group query filters beyond the connection’s own location restrictions.

Access: families:read · MCP: list_swimmers

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.
family_idstring
Optional family to inspect. 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/swimmers" \
  -G \
  --data-urlencode 'family_id=family_example' \
  -H "Authorization: Bearer ${SWUM_API_KEY}"

200Responseapplication/json

{
  "data": [
    {
      "id": "swimmer_example",
      "family_id": "family_example",
      "name": "Avery Rivera",
      "birth_date": "2019-03-15",
      "group_id": null,
      "updated_at": null
    }
  ],
  "next_cursor": null
}

GET/v1/swimmers/{id}

Get a swimmer

family_id is required to establish the swimmer’s roster relationship.

Access: families:read · MCP: get_swimmer

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.
family_idstringRequired
The family document id. Write bodies also accept parent_uid. At most 128 characters.

Request

curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/swimmers/swimmer_example" \
  -G \
  --data-urlencode 'family_id=family_example' \
  -H "Authorization: Bearer ${SWUM_API_KEY}"

200Responseapplication/json

{
  "data": {
    "id": "swimmer_example",
    "family_id": "family_example",
    "name": "Avery Rivera",
    "birth_date": "2019-03-15",
    "group_id": null,
    "updated_at": null
  }
}

POST/v1/swimmers/{id}/group

Move a swimmer group

Changes the school participant-group placement, after checking the owner’s roster and group. Linked progress levels follow the existing group-to-level sync. This does not enroll anyone in a class.

Access: progress:write · MCP: move_swimmer_group

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.

Path parameters

idstringRequired
The exact Swum document id.

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.
group_idstring | nullRequired
An owner participant-group id. null clears the placement.

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/swimmers/swimmer_example/group" \
  -X POST \
  -H "Authorization: Bearer ${SWUM_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${SWUM_IDEMPOTENCY_KEY}" \
  --data '{"family_id":"family_example","group_id":"group_example"}'

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/families/{familyId}/swimmers

Add a swimmer

Adds a swimmer to this family’s canonical school roster. name is required. birthday is a real past/present YYYY-MM-DD date; level_id and group_id must be current owner definitions. group_id:null clears placement.

Access: families:write

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.

Path parameters

familyIdstringRequired
The exact Swum document id.

Body

namestringRequired
At most 200 characters.
birthdaydate
Calendar date YYYY-MM-DD in the location's time zone.
level_idstring
At most 128 characters.
group_idstring | null
note_flagsobject

Non-medical flags

note_flags accepts only needs_attention and follow_up booleans. They are not a medical-data field. New swimmer creation has no generic delete/undo API.

Current permission and roster checks

Both approval and persistence recheck the current school, roster and connection authority. Removed access, revoked or expired grants, changed records and narrowed locations can refuse a previously prepared proposal. Do not work around a refusal by starting a duplicate operation.

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 current roster, class, entry or school policy refuses this change.
429	`rate_limit_exceeded`	Wait the Retry-After interval.

Request

curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/families/family_example/swimmers" \
  -X POST \
  -H "Authorization: Bearer ${SWUM_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${SWUM_IDEMPOTENCY_KEY}" \
  --data '{"name":"Avery Rivera","birthday":"2019-03-15","group_id":"group_example","note_flags":{"follow_up":true}}'

200Executedapplication/json

{
  "status": "executed",
  "proposal_id": "7a1991ec-5e37-43a0-a581-84e817790e4b",
  "result": {
    "success": true,
    "changes": {
      "familyId": "family_example",
      "kidId": "swimmer_example",
      "undoable": false
    }
  }
}

202Pending owner approvalapplication/json

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

PATCH/v1/swimmers/{id}

Update a swimmer

Updates only selected name, birthday, level_id, group_id or non-medical note_flags. family_id is required and at least one editable field must be supplied. Stale changes are refused. Supported office undo restores only unchanged selected fields; no public restore endpoint is exposed.

Access: families:write

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.

Path parameters

idstringRequired
The exact Swum document id.

Body

namestring
At most 200 characters.
birthdaydate
Calendar date YYYY-MM-DD in the location's time zone.
level_idstring
At most 128 characters.
group_idstring | null
note_flagsobject
family_idstringRequired
At most 128 characters.

Current permission and roster checks

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 current roster, class, entry or school policy refuses this change.
429	`rate_limit_exceeded`	Wait the Retry-After interval.

Request

curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/swimmers/swimmer_example" \
  -X PATCH \
  -H "Authorization: Bearer ${SWUM_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${SWUM_IDEMPOTENCY_KEY}" \
  --data '{"family_id":"family_example","group_id":null,"note_flags":{"follow_up":false}}'

200Executedapplication/json

{
  "status": "executed",
  "proposal_id": "7a1991ec-5e37-43a0-a581-84e817790e4b",
  "result": {
    "success": true,
    "changes": {
      "familyId": "family_example",
      "kidId": "swimmer_example",
      "undoable": true
    }
  }
}

202Pending owner approvalapplication/json

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

POST/v1/swimmers/{swimmerId}/notes

Add a swimmer note

Adds a staff-private swimmer note of 1–5,000 characters after checking the current family/swimmer relationship. Existing note contents and medical information are not exposed through this route.

Access: families:write

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.

Path parameters

swimmerIdstringRequired
The exact Swum document id.

Body

contentstringRequired
At most 5000 characters.
family_idstringRequired
At most 128 characters.

Current permission and roster checks

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 current roster, class, entry or school policy refuses this change.
429	`rate_limit_exceeded`	Wait the Retry-After interval.

Request

curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/swimmers/swimmer_example/notes" \
  -X POST \
  -H "Authorization: Bearer ${SWUM_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${SWUM_IDEMPOTENCY_KEY}" \
  --data '{"family_id":"family_example","content":"Practice floating before the next lesson."}'

200Executedapplication/json

{
  "status": "executed",
  "proposal_id": "7a1991ec-5e37-43a0-a581-84e817790e4b",
  "result": {
    "success": true,
    "changes": {
      "familyId": "family_example",
      "kidId": "swimmer_example",
      "noteId": "note_example"
    }
  }
}

202Pending owner approvalapplication/json

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

The swimmer object

idstring
family_idstring
namestring
birth_datedate | null
group_idstring | null
The owner roster placement when available, with a source-record fallback.
updated_attimestamp | null