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
API Reference / Messages
Messages
Send an in-app message to an exact list of account-backed roster families. Reading conversation history, sending email and SMS are outside these public routes.
Retry-After and X-RateLimit-RemainingPer key or agent connection, on the Enterprise plan.
/v1/messagesSend a message
Sends through Swummy’s existing in-app broadcast handler. Every recipient must be on the owner’s roster and have a Swum account. Can Act supports up to 50 named families; the daily cap counts recipients.
Access: messages:write
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. - 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_idsstring[]Required
1–50 distinct family ids. At most 50 items.
- bodystring
1–2000 characters. At most 2000 characters.
- messagestring
Alias for body. At most 2000 characters.
Approval and retries
Always requires owner approval in Swum, including for API keys and Can Act agents. 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. |
curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/messages" \
-X POST \
-H "Authorization: Bearer ${SWUM_API_KEY}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ${SWUM_IDEMPOTENCY_KEY}" \
--data '{"family_ids":["family_example"],"body":"See you Saturday at 09:00."}'{
"status": "pending_approval",
"proposalId": "7a1991ec-5e37-43a0-a581-84e817790e4b",
"proposal_id": "7a1991ec-5e37-43a0-a581-84e817790e4b"
}