Public read API

Flag lookup

Clients can fetch the flag associated with a Twitch user ID. No authentication is required.

Endpoint

GET /api/flags/{twitchUserId}

Try it with curl:

curl https://twitchflags.live/api/flags/18063875

twitchUserId: Twitch numeric user ID. Digits only (for example 18063875).

200 OK with JSON:

{
  "twitchUserId": "18063875",
  "flag": "US"
}

All errors return JSON of the form { "error": "…" }.

Status	error	When
`400`	`invalid_twitch_user_id`	Path ID is missing or not digits-only.
`404`	`flag_not_set`	User has not saved a flag.
`429`	`rate_limited`	Request was rate limited.
`503`	`service_unavailable`	Flag storage is temporarily unavailable.

Access-Control-Allow-Origin: * on GET responses
Successful reads and 404 flag_not_set: Cache-Control: public, max-age=604800, s-maxage=604800, stale-while-revalidate=604800
Successful saves and removals invalidate the affected Twitch user ID's Vercel CDN cache tag.
Other errors: Cache-Control: no-store
OPTIONS preflight is cacheable for 24h (Access-Control-Max-Age: 86400)