# SETTO API


- **Get started**
- [SETTO External API](/docs): A read-only HTTP API that lets an organizer pull their own SETTO tournaments, categories, teams, rounds, games and standings into a website, a spreadsheet or an AI agent.
- [Quickstart](/docs/quickstart): Create an organization API token in the SETTO dashboard and make your first three requests to the External API with curl, JavaScript or Python.
- [Authentication](/docs/authentication): How SETTO External API tokens work — the bearer header, live vs test prefixes, organization scope, expiry, rotation and revocation, and the difference between 401 and 403.

- **Concepts**
- [Data model](/docs/concepts/data-model): The SETTO domain tree — organization, tournament, division, round, pool, draw and game — plus the id conventions and the enum values you will switch on.
- [Populate](/docs/concepts/populate): How the populate query parameter embeds relations, the exact allow-list per endpoint, the defaults each endpoint applies, and the rules for nested paths.
- [Pagination](/docs/concepts/pagination): How limit and offset work on GET /v1/external/tournaments, what the meta envelope contains, and why the other list endpoints return everything at once.
- [Errors](/docs/concepts/errors): The error body shape, every error code the SETTO External API returns, what each one means, and whether retrying will help.
- [Rate limits](/docs/concepts/rate-limits): 120 requests per 60 seconds per token, a second per-IP ceiling, the X-RateLimit response headers, how to back off on 429, and how conditional requests with ETag save bandwidth.

- **Guides**
- [List tournaments](/docs/guides/list-tournaments): Use GET /v1/external/tournaments to find your organization's tournaments, filter them by status and sport, and page through a season archive.
- [Get a tournament](/docs/guides/get-tournament): Use GET /v1/external/tournaments/{idx} to read one tournament and embed its club, categories, rounds, sponsors, circuit and tiebreak rules with populate.
- [List divisions](/docs/guides/list-divisions): Use GET /v1/external/tournaments/{idx}/divisions to read a tournament's categories, their rounds, and optionally every team registered in each one.
- [List teams](/docs/guides/list-teams): Use GET /v1/external/tournaments/{idx}/teams to read every registered pair or player, filter by category, and embed players, captain and league team.
- [Get a round](/docs/guides/get-round): Use GET /v1/external/rounds/{idx} to read one round's groups, standings, games, scores and knockout bracket — the richest endpoint in the SETTO External API.
- API reference
  - [API reference](/docs/reference): How the generated SETTO External API reference works — one page per operation, a Try it panel you can paste a token into, and the raw OpenAPI document.
  - Organization
    - [The organization and token behind the current Bearer credential](/docs/reference/organization/get-me)
  - Tournaments
    - [List the calling organization's tournaments](/docs/reference/tournaments/list-tournaments)
    - [One tournament by identifier](/docs/reference/tournaments/get-tournament)
  - Divisions
    - [A tournament's divisions (categories)](/docs/reference/divisions/list-divisions)
  - Teams
    - [A tournament's teams (pairs, players or league teams)](/docs/reference/teams/list-teams)
  - Rounds
    - [One round by identifier, with its pools, games and draws](/docs/reference/rounds/get-round)

- **AI**
- [MCP server](/docs/ai/mcp): Connect Claude Code, Cursor or any Streamable HTTP MCP client to the SETTO External API with six read-only tools, authenticated by the same organization API token.
- [Agent Skills](/docs/ai/skills): Install the setto-api Agent Skill so Claude Code, Cursor or any AGENTS.md-aware agent knows the six SETTO External API endpoints, their populate rules and their error codes.
- [Docs for LLMs](/docs/ai/llms): Every page of these docs is available as raw Markdown, plus llms.txt, llms-full.txt and openapi.json — the machine-readable artifacts an AI agent or a RAG pipeline needs.

- **More**
- [Changelog](/docs/changelog): Version history of the SETTO External API — what shipped, what changed, and what counts as a breaking change.