API Reference
API Reference
Selected REST resource endpoints, grouped the way your school is. Each page has parameters and illustrative requests. The MCP catalog and server OpenAPI table cover the expanded owner workflows.
Base URL
https://api.swum.ai/v1Use the deployment base URL supplied for your school. The address above is the intended production origin. Set SWUM_API_BASE and SWUM_API_KEY for the examples; before writing, set SWUM_IDEMPOTENCY_KEY once per logical operation and keep it through retries. Authenticate with Authorization: Bearer <token> (see Authentication). Every POST, PATCH and DELETE resource write needs an Idempotency-Key. The public GET /v1/openapi.json exposes the server route table; proposal status is also available at GET /v1/proposals/{id}.
Documented resource endpoints
These pages retain the resource examples below. For the expanded owner workflows, use the complete MCP tool catalog; each tool lists its actual route, input schema, scope and approval behavior. The live GET /v1/openapi.json is the server's complete route table.
Families
- GET/v1/familiesList families
- GET/v1/families/{id}Get a family
- POST/v1/familiesCreate a family
- PATCH/v1/families/{id}Update a family
- POST/v1/families/{id}/notesAdd a family note
Swimmers
- GET/v1/swimmersList swimmers
- GET/v1/swimmers/{id}Get a swimmer
- POST/v1/swimmers/{id}/groupMove a swimmer group
- POST/v1/families/{familyId}/swimmersAdd a swimmer
- PATCH/v1/swimmers/{id}Update a swimmer
- POST/v1/swimmers/{swimmerId}/notesAdd a swimmer note
Classes · read only
- GET/v1/classesList classes
- GET/v1/classes/{id}Get a class
- GET/v1/classes/{id}/instancesList class instances
- GET/v1/classes/{id}/rosterGet a class roster
- GET/v1/classes/{id}/open-spotsGet open spots
Enrollments
- GET/v1/enrollmentsList enrollments
- POST/v1/classes/{id}/participants/{swimmerId}/removeRemove a class participant
- POST/v1/classes/{id}/waitlist/{swimmerId}/removeRemove from a waitlist
- POST/v1/enrollmentsRequest enrollment or add to a free occurrence
Lessons
- GET/v1/lessonsList lessons
- POST/v1/lessonsBook a lesson
- POST/v1/lessons/{id}/rescheduleReschedule a lesson
- POST/v1/lessons/{id}/cancelCancel a lesson
- GET/v1/proposals/{id}Get a proposal status
Attendance & Makeup Credits
- GET/v1/attendanceList attendance
- POST/v1/attendanceMark attendance
- POST/v1/creditsGrant makeup credits
Payments & Invoices · read only
- GET/v1/paymentsList payments
- GET/v1/invoicesList invoices
Progress
- GET/v1/levelsList levels
- GET/v1/progress/{swimmerId}Get swimmer progress
- POST/v1/progress/{swimmerId}/skills/{skillId}/completeComplete a skill
Waivers · read only
- GET/v1/waiversList family waiver status
Team & Meets
- GET/v1/staffList staff
- GET/v1/team/groupsList Team groups
- GET/v1/meetsList meets
- GET/v1/meets/{id}Get a meet
- GET/v1/meets/{id}/entriesList meet entries
- GET/v1/swimmers/{id}/timesList swimmer times
- POST/v1/meets/{id}/entriesSet a swimmer’s meet entries
Messages
- POST/v1/messagesSend a message
Locations · read only
- GET/v1/locationsList locations
App Webhooks
- POST/v1/webhook_endpointsCreate an app webhook subscription
- GET/v1/webhook_endpoints/{id}Get an app subscription
- GET/v1/webhook_endpoints/{id}/events/{eventId}Get a canonical app event
- DELETE/v1/webhook_endpoints/{id}Delete an app subscription