## SETTO External API

Read-only HTTP API for one SETTO organization's padel, tennis and pickleball
tournaments. Use it when a task mentions SETTO, a `setto_live_…` / `setto_test_…` token,
or a tournament page under `https://www.setto.io/t/<slug>`. It cannot write.

- Base URL: `https://api-production-ea80.up.railway.app/v1`
- Auth: `Authorization: Bearer $SETTO_API_TOKEN` (org token, read-only).
  Read it from the environment. Never print, log, commit or ship it to a browser.
- Prefer the MCP server at `https://docs.setto.io/mcp` (tools `me`,
  `list_tournaments`, `get_tournament`, `list_divisions`, `list_teams`,
  `get_round`) when it is connected; the HTTP calls below are the fallback.

Endpoints — all `GET`, every id is a UUID v4 named `idx`:

| Endpoint | Query |
| --- | --- |
| `/v1/external/me` | — |
| `/v1/external/tournaments` | `status`, `sport`, `populate`, `limit` (1–100, default 25), `offset` |
| `/v1/external/tournaments/{idx}` | `populate` (default `club,divisions`) |
| `/v1/external/tournaments/{idx}/divisions` | `populate` (default `rounds`) |
| `/v1/external/tournaments/{idx}/teams` | `populate` (default `playerProfiles,division`), `division` |
| `/v1/external/rounds/{idx}` | `populate` |

```bash
curl -s -G https://api-production-ea80.up.railway.app/v1/external/tournaments \
  -H "Authorization: Bearer $SETTO_API_TOKEN" -d status=IN_PROGRESS -d limit=25
```

- `populate` is comma-separated; relations appear only when asked for (or in the
  default list); nested paths imply their parents; an unknown value is a `400`
  listing the legal ones.
- Errors are `{ statusCode, code, message }` — branch on `code`. `400`
  `INVALID_ID` → malformed uuid, never a `404`. `401` → new token. `404` → wrong
  id/org. `429` → `Retry-After` (120/60 s token, 300/60 s IP). Never retry 4xx.
- Hidden divisions and rounds return `isVisible: false` instead of being dropped;
  `DRAFT`/`ARCHIVED` tournaments are included unless filtered with `status`.
- No emails, phone numbers or payment data are ever returned.

Docs <https://docs.setto.io> · OpenAPI <https://docs.setto.io/openapi.json> · Full skill <https://docs.setto.io/skills/setto-api/SKILL.md>