Changelog

Every change to the External API is recorded here, newest first. The API is versioned in its path (/v1/): additive changes ship inside v1, and anything that would break an existing integration would ship as a new path prefix.

What counts as a change

Build for the additive cases: ignore fields you do not recognise, and fall through on enum values you have not seen. That way a release like "pickleball individual leagues now expose a new tournament type" never reaches your on-call.

1.0.0 — 2026-09

Initial public release.

• Six read-only endpoints, all under /v1/external/: getMe, listTournaments, getTournament, listDivisions, listTeams, getRound.
• Organization API tokens. Created from app.setto.io → Organización → the API tab by the organization creator or an ADMIN member. Shown once, read-only, revocable, with an optional 30/90/365-day expiry and a maximum of 10 active tokens per organization.
• Bearer authentication with setto_live_ (production) and setto_test_ (non-production) prefixes, and the error codes MISSING_API_TOKEN, INVALID_API_TOKEN, EXPIRED_API_TOKEN and INSUFFICIENT_SCOPE.
• Organization scoping. A token reads only the tournaments its organization owns; anything else — including another organization's data and personal tournaments — answers 404, never 403, so ids cannot be probed.
• populate, an allow-listed comma-separated relation list per endpoint, with implicit parent expansion and per-endpoint defaults. Unknown values are a 400.
• Offset pagination on listTournaments: limit 1..100 (default 25), offset, and a meta envelope with limit, offset and total. Rows are ordered by startDate descending.
• Rate limiting at 120 requests per 60 seconds per token, with X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on every response and Retry-After on a 429.
• Conditional requests. Strong ETag plus If-None-Match returns 304 Not Modified so polling a round costs almost nothing.
• A privacy-safe projection. No emails, phone numbers or social handles; no payment or billing data. Player objects carry idx, firstName, lastName and avatar only.
• Hidden and draft material is returned, flagged rather than filtered — isVisible: false on divisions and rounds, and DRAFT/ARCHIVED tournaments in listTournaments.
• This documentation site, with a generated reference and a Try it playground, a published /openapi.json, a Markdown rendition of every page, /llms.txt and /llms-full.txt, a remote MCP server and an Agent Skill.