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 staff
List Team groups
List meets
Get a meet
List meet entries
List swimmer times
Set a swimmer’s meet entries

API Reference / Team & Meets

Team & Meets

Read staff, configured Team groups, meets, entries and swimmer times. Set individual meet entries through the same approved action path as Swum. Team routes require the school’s Team setting; family confirmation and any payment stay in Swum.

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

List staff

Returns active school coach records within the connection’s location scope. A standalone owner without a school directory receives an empty list.

Access: team:read

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/staff" \
  -H "Authorization: Bearer ${SWUM_API_KEY}"

200Responseapplication/json

{
  "data": [
    {
      "id": "coach_example",
      "name": "Daniela Ruiz",
      "role": "employee",
      "location_ids": [
        "pool_example"
      ],
      "updated_at": null
    }
  ],
  "next_cursor": null
}

GET/v1/team/groups

List Team groups

Lists configured Team placement groups and their practices. Location restrictions filter practices and omit groups with no permitted practice. This is not a USA Swimming registration or verification service.

Access: team:read

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.
limitinteger
Minimum 1. Maximum 200. Default: 50.
cursorstring
Opaque cursor; continue until next_cursor is null, including after empty filtered pages.

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/team/groups" \
  -H "Authorization: Bearer ${SWUM_API_KEY}"

200Responseapplication/json

{
  "data": [
    {
      "id": "group_example",
      "name": "Junior Team",
      "min_age": 8,
      "max_age": 12,
      "practices": [
        {
          "location_id": "pool_example",
          "days": [
            "Monday"
          ],
          "start": "16:00",
          "end": "17:00"
        }
      ],
      "updated_at": null
    }
  ],
  "next_cursor": null
}

GET/v1/meets

List meets

Lists this owner’s meets within the connection’s locations. Follow every next_cursor, including empty filtered pages.

Access: team:read

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.
limitinteger
Minimum 1. Maximum 200. Default: 50.
cursorstring
Opaque cursor; continue until next_cursor is null, including after empty filtered pages.

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/meets" \
  -H "Authorization: Bearer ${SWUM_API_KEY}"

200Responseapplication/json

{
  "data": [
    {
      "id": "meet_example",
      "name": "Spring Classic",
      "course": "SCY",
      "start_date": "2027-03-06",
      "end_date": "2027-03-07",
      "entry_deadline": "2027-02-27",
      "location_id": "pool_example",
      "host_team": "Example Aquatics",
      "sessions": [],
      "events": [],
      "updated_at": "2026-10-26T12:00:00.000Z"
    }
  ],
  "next_cursor": null
}

GET/v1/meets/{id}

Get a meet

Returns one owner-verified meet, its sessions and event definitions. The school’s Team setting and connection location scope apply.

Access: team:read

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/meets/meet_example" \
  -H "Authorization: Bearer ${SWUM_API_KEY}"

200Responseapplication/json

{
  "data": {
    "id": "meet_example",
    "name": "Spring Classic",
    "course": "SCY",
    "start_date": "2027-03-06",
    "end_date": "2027-03-07",
    "entry_deadline": "2027-02-27",
    "location_id": "pool_example",
    "host_team": "Example Aquatics",
    "sessions": [],
    "events": [],
    "updated_at": "2026-10-26T12:00:00.000Z"
  }
}

GET/v1/meets/{id}/entries

List meet entries

Lists canonical entries whose family/swimmer is still on the owner’s permitted roster. An entry is not evidence that the family confirmed or paid.

Access: team:read

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.
limitinteger
Minimum 1. Maximum 200. Default: 50.
cursorstring
Opaque cursor; continue until next_cursor is null, including after empty filtered pages.

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/meets/meet_example/entries" \
  -H "Authorization: Bearer ${SWUM_API_KEY}"

200Responseapplication/json

{
  "data": [
    {
      "id": "entry_example",
      "meet_id": "meet_example",
      "family_id": "family_example",
      "swimmer_id": "swimmer_example",
      "event_numbers": [
        1,
        3
      ],
      "seed_times": {},
      "family_answer": "none",
      "updated_at": null
    }
  ],
  "next_cursor": null
}

GET/v1/swimmers/{id}/times

List swimmer times

Requires family_id. Returns this school swimmer’s recorded swims, including dq, previous_best, standard and new_cut. USA Swimming membership IDs and private participant fields are excluded. These are recorded swims, not a live SWIMS sync.

Access: team:read

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.
limitinteger
Minimum 1. Maximum 200. Default: 50.
cursorstring
Opaque cursor; continue until next_cursor is null, including after empty filtered pages.
family_idstringRequired
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/swimmer_example/times" \
  -G \
  --data-urlencode 'family_id=family_example' \
  -H "Authorization: Bearer ${SWUM_API_KEY}"

200Responseapplication/json

{
  "data": [
    {
      "id": "time_example",
      "swimmer_id": "swimmer_example",
      "family_id": "family_example",
      "meet_id": "meet_example",
      "meet_name": "Spring Classic",
      "date": "2027-03-06",
      "course": "SCY",
      "distance": 50,
      "stroke": "FR",
      "seconds": 34.21,
      "dq": false,
      "previous_best": 35.1,
      "standard": null,
      "new_cut": false,
      "updated_at": null
    }
  ],
  "next_cursor": null
}

POST/v1/meets/{id}/entries

Set a swimmer’s meet entries

Sets the selected swimmer’s individual event numbers after current meet-day age, event eligibility, deadline, limits and roster checks. Family confirmation and fees happen separately in Swum. It does not submit a payment, create relays or export to a meet host.

Access: team: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

family_idstring
At most 128 characters.
parent_uidstring
At most 128 characters.
swimmer_idstringRequired
At most 128 characters.
event_numbersinteger | string[]Required
At most 50 items.

Exact event selection

event_numbers is the new full selection, not an additive patch. An empty list clears an unfrozen selection. Entries already attached to an immutable family request must be scratched in Swum before changing them. Meet creation, result-file imports, scratches, refunds and SDIF exports are app workflows, with no public endpoints beyond this reference.

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

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 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/meets/meet_example/entries" \
  -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","event_numbers":[1,3]}'

200Executedapplication/json

{
  "status": "executed",
  "proposal_id": "7a1991ec-5e37-43a0-a581-84e817790e4b",
  "result": {
    "success": true,
    "changes": {
      "meetId": "meet_example",
      "familyId": "family_example",
      "kidId": "swimmer_example",
      "eventNumbers": [
        1,
        3
      ]
    }
  }
}

202Pending owner approvalapplication/json

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