MyCup API — Reference

One API over everything MyCup does, for three audiences.

Platform credentials reach the whole estate and are issued to MyCup staff. Partner credentials are attached to an explicit list of tournaments; one credential can serve many. Public publishable keys are read-only and safe to embed in a front-end.

Platform and partner credentials use the client_credentials grant: POST your client_id and client_secret to /api/v1/oauth/token and send the returned access token as a bearer. Public keys are presented directly in the X-MyCup-Key header.

The rules are the panel's rules

The API is a second front-end, not a second back-end. Every restriction it applies is read from the same service the MyCup panel reads, so the two cannot drift:

Scopes narrow, they never widen. Every scope also requires the tournament permission behind it, so a credential can be narrower than any human role and never wider.
Plan limits answer 402 with the plan you would need, not 403.
A finished tournament freezes its structure and keeps its record editable: you can still correct a score or a kickoff time, but not add a team.
The public surface mirrors the website, page-visibility included. A page the organiser switched off returns 404 here too.

Conventions

Responses are {"data": …}, with meta and links on collections. Times are ISO-8601 with an offset. Errors carry a stable error.code — branch on that, never on the message, which is localised. Unsafe requests accept an Idempotency-Key header, which matters most on the destructive ones: regenerating a match list refuses with 409 and a list of what would be lost unless you pass confirm_destructive.

Quickstart

Exchange your credentials, then call an endpoint with the token:

# 1. Get a token (valid one hour by default)
curl -X POST https://mycup.me/api/v1/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"mc_cl_…","client_secret":"mc_sk_…"}'

# 2. Use it
curl https://mycup.me/api/v1/tournaments/<url_key>/matches \
  -H 'Authorization: Bearer <access_token>'

# A publishable key needs no exchange
curl https://mycup.me/api/v1/public/tournaments/<url_key>/standings \
  -H 'X-MyCup-Key: mc_pk_…'

Errors

Every refusal has the same shape. Branch on error.code, which is stable; error.message is localised to your Accept-Language and will change.

{
  "error": {
    "code": "plan_limit_reached",
    "message": "This tournament's plan allows 16 participants.",
    "details": { "limit": 16, "current": 16, "required_plan": "Pro" }
  }
}

Status	Means
401	No credential, or one that has been revoked or has expired.
402	Not on this tournament's plan, or a cap is full. `details` names the plan you need.
403	The credential lacks the scope, the permission, or access to this tournament.
404	Not found — or, publicly, a page this tournament does not publish.
409	Conflicts with the tournament's state: finished, roster locked, or a destructive action awaiting confirmation.
422	Validation failed. `details.fields` names each failing field.
429	Rate limited. `Retry-After` says when to try again.

Authentication

Exchanging credentials for an access token.

GET /api/v1/me Describe the calling credential and the tournaments it reaches

Authentication

Bearer token

POST /api/v1/oauth/revoke Revoke the presented access token

Authentication

Bearer token

POST /api/v1/oauth/token Exchange credentials for an access token

The client_credentials grant, and the only grant. Credentials may travel in the body or as HTTP Basic. An unknown client_id and a wrong secret return the same error on purpose.

Authentication

None — this is where credentials are exchanged

Request body

Field	Type	Description
grant_type	string
client_id	string
client_secret	string
scope	string	Optional space-separated narrowing. Must be a subset of the grant.

Public

Read-only tournament data, authenticated with a publishable key. Mirrors the public website, page-visibility rules included: a page the organiser switched off returns 404 here too.

GET /api/v1/public/tournaments/{tournament} Get the tournament