Build on Swum

What you can build

The released backend declares 116 resource routes, 89 MCP tools and 17 webhook event types. Supported owner workflows cover the roster, classes, private lessons, enrollment, attendance, billing, staff, communications, calendar, school settings and reports, subject to the selected access and each operation's checks.

The API reference provides selected REST resource examples. The server's GET /v1/openapi.json gives the current route table. The full tool catalog shows every current MCP operation, exact argument names and schemas. Dedicated Zapier, Make and n8n app keys manage their own signed webhook subscriptions and selected platform actions.

Quick start

1. Use a school on the Enterprise plan. The owner creates a scoped key in Settings → Developers & Integrations, or allows an AI agent when it signs in.
2. Set SWUM_API_BASE to https://api.swum.ai and SWUM_API_KEY to the appropriate key/token. Grant classes:read for GET /v1/locations.
3. Before a REST write, set SWUM_IDEMPOTENCY_KEY once per logical operation. Reuse that same key and identical payload through retries. POST, PATCH and DELETE resource writes all require it.
4. Use a provisioned DEV sandbox for synthetic families and test keys before working with real school data.

The basics

• The production API is https://api.swum.ai. The DEV sandbox API uses https://swum-53cd2-api.web.app.
• Resource inputs use snake_case; MCP path arguments keep their exact schema names, such as familyId and swimmerId. App subscription DTOs retain the explicitly shown camelCase fields.
• Ids are exact Swum document ids with no promised prefix. Times are ISO 8601; local booking times use the selected location’s time zone.
• Send Swum-Version: 2026-10-25, or omit it for the current version. Other versions are refused.
• Lists return data and next_cursor. Follow a non-null cursor even after an empty filtered page.
• sk_test_ keys work only in a founder-provisioned DEV sandbox and are rejected by production.

Same rules as the app

Business writes use immutable server proposals and shared action handlers. Read Only cannot write; Ask Me First waits for owner approval; Can Act can execute eligible operations. Money movements, lesson cancellations/reschedules, broadcasts and guarded removals still need owner approval. Current grant, location, roster and domain checks apply at execution.

Supported enrollment and billing modes include requests, verified free occurrences and approved card/cash operations. Some modes still require family confirmation or checkout. The returned proposal, job and domain status determine what actually completed. Family payment-method management, bulk exports, owner bank-account setup and Swum administrator operations stay outside the owner connector; personal family and instructor actions retain their own identity requirements.