SETTO External API
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.
The SETTO External API is a read-only HTTP API. With an organization API token you
can read every tournament your SETTO organization owns — its categories
(divisions), teams, rounds, groups, brackets, games and standings — and render
them wherever you want. There are six endpoints, all GET, all under
/v1/external/. This page explains what the API covers and where to go next;
the quickstart has a working request in under five minutes.
What you can read
| Resource | Endpoint |
|---|---|
| The organization and token behind the request | GET /v1/external/me |
| Tournaments owned by the organization | GET /v1/external/tournaments |
| One tournament, with optional relations | GET /v1/external/tournaments/{idx} |
| A tournament's categories (divisions) | GET /v1/external/tournaments/{idx}/divisions |
| A tournament's teams and their players | GET /v1/external/tournaments/{idx}/teams |
| One round: groups, standings, games and brackets | GET /v1/external/rounds/{idx} |
That is the whole surface. There is no write access: the API cannot create a tournament, submit a score or register a player.
Who it is for
- Clubs and federations embedding live draws, schedules and standings on their own website.
- Sponsors and media partners pulling fixtures and results for a broadcast graphic or a newsletter.
- Analysts exporting a season into a spreadsheet or a database.
- AI agents — every page here is also served as Markdown, and there is an MCP server and an Agent Skill for the same six endpoints.
Base URL
https://api-production-ea80.up.railway.app/v1Every path in this documentation is written in full (/v1/external/tournaments),
so it appends directly to the host. A friendlier api.setto.io host will replace
the Railway one later; when it does, the paths stay identical.
Authentication in one line
Send your organization token as a bearer token on every request:
GET /v1/external/tournaments HTTP/1.1
Host: api-production-ea80.up.railway.app
Authorization: Bearer setto_live_YOUR_TOKEN_HERETokens are created in the SETTO organizer dashboard and belong to an organization, not to a person. See Authentication.
What the API never returns
The External API is designed to be safe to put in front of a public website. It
never returns personal contact data (no emails, no phone numbers, no social
handles) and never returns payment or billing data. Player objects carry only
idx, firstName, lastName and avatar.
Two things it does return, which surprise people:
- Hidden divisions and rounds. They come back with
isVisible: falseinstead of being dropped, so you decide whether to render them. - Draft and archived tournaments. Filter them out with the
statusquery parameter if you only want live ones.
Where to go next
Quickstart
Create a token and make your first three requests.
Authentication
Token format, scope, rotation, and 401 vs 403.
Data model
Tournament, division, round, pool, draw, game, team.
API reference
Generated per-endpoint reference with a Try it panel.
Guides
One worked example per endpoint.
For AI agents
llms.txt, per-page Markdown, OpenAPI and MCP.