API reference

Reference for the 4league public /v1 API. English only. Requests must be signed: see HMAC authentication. Everything on this page is generated from the same machine-readable description of the API.

Conventions

Base URL and methods

Base URL: https://api.4league.app/v1. Do not use 4league.app/api; it is not this API. Requests are signed, see HMAC authentication.

Only GET, HEAD are served. Any other method answers 405 methodNotAllowed with an Allow: GET, HEAD header, before authentication. Request bodies are rejected with 400 badRequest. OPTIONS is normally answered (204) by CORS before reaching the API.

Organization-scoped keys only. A key sees its own organization and, when created with descendants, everything below it. Anything outside the scope, hidden, or nonexistent answers the identical 404 notFound.

Pagination

List endpoints return this envelope. Defaults: page 1, limit 25 (max 100). page * limit must be <= 10000 (10000). 400 badRequest with details {field, limit}. Repeated keys and arrays are rejected.

Some paginated responses add top-level competition and/or meta (kind, truncated, competitionsIncluded). Window cap: Enforced (400 badRequest, details.field page) on the organization list routes and on /tournaments/{id}/teams and /tournaments/{id}/players (all via helpers/apiData/orgListCache.js page()). Not enforced on the other paginated routes, which slice an in-memory list: any page is accepted and an out-of-range page returns an empty data array.

Query parameters and sorting

Unknown, repeated (array) or empty query keys are 400 badRequest with details.field. Values are case-sensitive. The error carries details.field with the offending key.

Sorting: sort accepts id, name; prefix with - for descending (id, name, -id, -name). Ascending, or descending with a - prefix. Always tie-broken on id.

Time filters: from and to

• Format: ISO 8601, inclusive on both ends.
• A date-only value (YYYY-MM-DD) covers the whole UTC day: from = 00:00:00.000Z, to = 23:59:59.999Z.
• Bounds are compared in UTC. A value with an offset is converted to UTC; a value without an offset is read as UTC.
• The competition timezone is used only to place legacy matches that have no stored timestamp.
• Send full timestamps with an explicit offset (for example 2026-01-05T10:00:00+02:00).
• 400 badRequest, details.field = from | to. from after to is 400 with details.field = from.

Errors

Every error uses this body; reason, details and retryAfter are optional:

{
  "error": {
    "code": "string",
    "message": "string",
    "reason": "optional string",
    "details": "optional object",
    "retryAfter": "optional integer seconds"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid credentials",
    "reason": "malformedHeader"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid credentials"
  }
}

scopeTooLarge caps: scope above MAX_SCOPE_ORGS ({"max":5000}); players list, more than 50 organizations and no narrowing filter ({"max":50,"requiresOneOf":["clubId","associationId","competitionId","teamId"]}). Organization tree: at most 500 nodes, depth up to 3.

Scopes

Rate limits

Approximately 60 requests per minute per key, per server process. The limiter is per key and per server worker (in memory), so the effective limit is approximate: up to 60 x number of workers per minute. The standard RateLimit-* headers are not sent. Semantics read from middleware/apiAuth.js (express-rate-limit legacy headers); scripts/v1-signed-get.js prints the headers as received and defines no semantics of its own.

Monthly quota

10000 requests per resource per month (UTC calendar month). Headers: none: remaining quota is not exposed in headers. Counted per resource (organization), not per key. 429 quotaExceeded with Retry-After until the next month starts. Requests that fail authentication, the scope check or the rate limit do not consume quota; requests that pass all three do, including those that end in 404 or 400. A credential may carry its own monthlyQuota; 10000 is the default.

Caching and freshness

Data is cached for about 2 minutes at most: public data results for 30-60 seconds and the organization scope tree for 60 seconds, both per server worker, so two requests may see different states. Live matches use the shortest TTL.

Response headers

Quote X-Request-Id when you contact support about a request.

Organization aliases

• organizations: any organization type (federation, association, club)
• federations: federations only (type 2)
• associations: associations only (type 3)
• clubs: clubs only (type 4)

Wrong type: 404 notFound, identical to an unknown id.

Connectivity check

GET HEAD /ping

https://api.4league.app/v1/ping no scope

Authenticated echo, no scope required. Never cached (Cache-Control: no-store).

Parameters

No parameters.

Example request

curl -sS "https://api.4league.app/v1/ping" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

Example response

Captured from a seeded test organization (GET /v1/ping), HTTP 200.

{
  "data": {
    "apiVersion": 1,
    "serverTime": "2026-10-13T07:22:37.759Z",
    "keyId": "key1",
    "resourceType": "organization",
    "resourceId": "64b000000000000000000001",
    "scopes": [
      "competitions:read",
      "matches:read",
      "standings:read",
      "teams:read",
      "players:read",
      "matchStatistics:read",
      "organizations:read"
    ]
  }
}

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• badRequest 400
• rateLimited 429
• quotaExceeded 429

Organizations

GET HEAD /{alias}/{id}

https://api.4league.app/v1/{alias}/{id} organizations:read

Aliases for {alias}: organizations, federations, associations, clubs.

One organization. includeDescendants=true (or a key created with descendants) is needed to address organizations below the key root.

Parameters

Example request

curl -sS "https://api.4league.app/v1/organizations/{orgId}" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

Example response

Captured from a seeded test organization (GET /v1/organizations/{orgId}), HTTP 200.

{
  "data": {
    "id": "64b000000000000000000001",
    "type": "federation",
    "name": "Fed",
    "logo": "https://cdn.test/f.png",
    "parentId": null,
    "description": "root",
    "season": null
  }
}

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /{alias}/{id}/tree

https://api.4league.app/v1/{alias}/{id}/tree organizations:read

Aliases for {alias}: organizations, federations, associations, clubs.

Hierarchy below the organization (follows the primary parent only). Capped at 500 nodes: a larger tree is cut and the response carries top-level truncated:true.

Extra top-level response fields: truncated.

Parameters

Example request

curl -sS "https://api.4league.app/v1/organizations/{orgId}/tree?depth=2" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

Example response

Captured from a seeded test organization (GET /v1/organizations/{orgId}/tree?depth=2), HTTP 200.

{
  "data": {
    "id": "64b000000000000000000001",
    "type": "federation",
    "name": "Fed",
    "logo": "https://cdn.test/f.png",
    "parentId": null,
    "description": "root",
    "season": null,
    "children": [
      {
        "id": "6acddc3d41a6e2f5682625e3",
        "type": "association",
        "name": "org-6acddc3d41a6e2f5682625e3",
        "logo": "https://cdn.test/l.png",
        "parentId": "64b000000000000000000001",
        "description": "d",
        "season": null,
        "children": [
          {
            "id": "6acddc3d41a6e2f5682625e4",
            "type": "club",
            "name": "org-6acddc3d41a6e2f5682625e4",
            "logo": "https://cdn.test/l.png",
            "parentId": "6acddc3d41a6e2f5682625e3",
            "description": "d",
            "season": null,
            "children": []
          },
          {
            "id": "6acddc3d41a6e2f5682625e5",
            "type": "club",
            "name": "org-6acddc3d41a6e2f5682625e5",
            "logo": "https://cdn.test/l.png",
            "parentId": "6acddc3d41a6e2f5682625e3",
            "description": "d",
            "season": null,
            "children": []
          }
        ]
      }
    ]
  }
}

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /{alias}/{id}/associations

https://api.4league.app/v1/{alias}/{id}/associations organizations:read

Aliases for {alias}: organizations, federations, associations, clubs.

Paginated: returns the pagination envelope.

Parameters

Example request

curl -sS "https://api.4league.app/v1/organizations/{orgId}/associations?limit=2" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

Example response

Captured from a seeded test organization (GET /v1/organizations/{orgId}/associations?limit=2), HTTP 200.

{
  "data": [
    {
      "id": "6acddc3d41a6e2f5682625e3",
      "type": "association",
      "name": "org-6acddc3d41a6e2f5682625e3",
      "logo": "https://cdn.test/l.png",
      "parentId": "64b000000000000000000001",
      "description": "d",
      "season": null
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 1,
  "hasMore": false
}

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• scopeTooLarge 422
• rateLimited 429
• quotaExceeded 429

GET HEAD /{alias}/{id}/clubs

https://api.4league.app/v1/{alias}/{id}/clubs organizations:read

Aliases for {alias}: organizations, federations, associations, clubs.

Paginated: returns the pagination envelope.

Parameters

Example request

curl -sS "https://api.4league.app/v1/federations/{orgId}/clubs?includeDescendants=true&limit=2" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

Example response

Captured from a seeded test organization (GET /v1/federations/{orgId}/clubs?includeDescendants=true&limit=2), HTTP 200.

{
  "data": [
    {
      "id": "6acddc3d41a6e2f5682625e4",
      "type": "club",
      "name": "org-6acddc3d41a6e2f5682625e4",
      "logo": "https://cdn.test/l.png",
      "parentId": "6acddc3d41a6e2f5682625e3",
      "description": "d",
      "season": null
    },
    {
      "id": "6acddc3d41a6e2f5682625e5",
      "type": "club",
      "name": "org-6acddc3d41a6e2f5682625e5",
      "logo": "https://cdn.test/l.png",
      "parentId": "6acddc3d41a6e2f5682625e3",
      "description": "d",
      "season": null
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 2,
  "hasMore": false
}

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• scopeTooLarge 422
• rateLimited 429
• quotaExceeded 429

GET HEAD /{alias}/{id}/competitions

https://api.4league.app/v1/{alias}/{id}/competitions competitions:read

Aliases for {alias}: organizations, federations, associations, clubs.

Paginated: returns the pagination envelope.

Parameters

Example request

curl -sS "https://api.4league.app/v1/{alias}/{id}/competitions" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• scopeTooLarge 422
• rateLimited 429
• quotaExceeded 429

GET HEAD /{alias}/{id}/teams

https://api.4league.app/v1/{alias}/{id}/teams teams:read

Aliases for {alias}: organizations, federations, associations, clubs.

Paginated: returns the pagination envelope.

Parameters

Example request

curl -sS "https://api.4league.app/v1/{alias}/{id}/teams" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• scopeTooLarge 422
• rateLimited 429
• quotaExceeded 429

GET HEAD /{alias}/{id}/players

https://api.4league.app/v1/{alias}/{id}/players players:read

Aliases for {alias}: organizations, federations, associations, clubs.

With includeDescendants=true and more than 50 organizations in scope, one of clubId, associationId, competitionId, teamId is required, otherwise 422 scopeTooLarge with details.requiresOneOf.

Paginated: returns the pagination envelope.

Parameters

Example request

curl -sS "https://api.4league.app/v1/{alias}/{id}/players" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• scopeTooLarge 422
• rateLimited 429
• quotaExceeded 429

Tournaments

GET HEAD /tournaments/{id}

https://api.4league.app/v1/tournaments/{id} competitions:read

Parameters

Example request

curl -sS "https://api.4league.app/v1/tournaments/{tournamentId}" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

Example response

Captured from a seeded test organization (GET /v1/tournaments/{tournamentId}), HTTP 200.

{
  "data": {
    "competition": {
      "id": "6acddc3d41a6e2f5682625e6",
      "name": "c-6acddc3d41a6e2f5682625e6",
      "logo": null,
      "type": "league",
      "season": 3,
      "stage": "regular",
      "timezone": "UTC",
      "gender": null,
      "completed": false,
      "hasPlayoff": false,
      "hasPlayout": false,
      "groupCount": 2
    }
  }
}

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /tournaments/{id}/matches

https://api.4league.app/v1/tournaments/{id}/matches matches:read

Matches of the requested competition only (playoff/playout child competitions are not included, see knownLimitations).

Paginated: returns the pagination envelope.

Parameters

Example request

curl -sS "https://api.4league.app/v1/tournaments/{tournamentId}/matches?from=2026-01-05&to=2026-01-05&limit=2" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

Example response

Captured from a seeded test organization (GET /v1/tournaments/{tournamentId}/matches?from=2026-01-05&to=2026-01-05&limit=2), HTTP 200.

{
  "data": [
    {
      "id": "6acddc3d41a6e2f5682625ef",
      "status": "finished",
      "kickoffAt": "2026-01-05T12:00:00.000Z",
      "home": {
        "id": "6acddc3d41a6e2f5682625e8",
        "name": "TeamA",
        "shortName": "TEA",
        "logo": null
      },
      "away": {
        "id": "6acddc3d41a6e2f5682625ea",
        "name": "TeamB",
        "shortName": "TEA",
        "logo": null
      },
      "score": {
        "home": 1,
        "away": 1
      },
      "penalties": null,
      "leg": null,
      "twoLegs": false,
      "winner": "draw",
      "round": 1,
      "group": null
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 1,
  "hasMore": false,
  "competition": {
    "id": "6acddc3d41a6e2f5682625e6",
    "name": "c-6acddc3d41a6e2f5682625e6",
    "logo": null,
    "type": "league",
    "season": 3,
    "stage": "regular",
    "timezone": "UTC"
  }
}

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /tournaments/{id}/standings

https://api.4league.app/v1/tournaments/{id}/standings standings:read

Parameters

Example request

curl -sS "https://api.4league.app/v1/tournaments/{tournamentId}/standings" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

Example response

Captured from a seeded test organization (GET /v1/tournaments/{tournamentId}/standings), HTTP 200.

{
  "data": {
    "competition": {
      "id": "6acddc3d41a6e2f5682625e6",
      "name": "c-6acddc3d41a6e2f5682625e6",
      "logo": null,
      "type": "league",
      "season": 3,
      "stage": "regular",
      "timezone": "UTC"
    },
    "standings": [
      {
        "rank": 1,
        "team": {
          "id": "6acddc3d41a6e2f5682625e8",
          "name": "TeamA",
          "shortName": "TEA",
          "logo": null
        },
        "played": 1,
        "won": 0,
        "drawn": 1,
        "lost": 0,
        "goalsFor": 1,
        "goalsAgainst": 1,
        "goalDiff": 0,
        "points": 1,
        "startingPoints": 0,
        "group": null
      }
    ],
    "playoffStandings": null,
    "playoutStandings": null,
    "playoffFormat": null,
    "playoutFormat": null,
    "playoffCompleted": null,
    "playoutCompleted": null
  }
}

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /tournaments/{id}/groups

https://api.4league.app/v1/tournaments/{id}/groups competitions:read

Parameters

Example request

curl -sS "https://api.4league.app/v1/tournaments/{id}/groups" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /tournaments/{id}/teams

https://api.4league.app/v1/tournaments/{id}/teams teams:read

Paginated: returns the pagination envelope.

Parameters

Example request

curl -sS "https://api.4league.app/v1/tournaments/{id}/teams" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /tournaments/{id}/players

https://api.4league.app/v1/tournaments/{id}/players players:read

Paginated: returns the pagination envelope.

Parameters

Example request

curl -sS "https://api.4league.app/v1/tournaments/{id}/players" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /tournaments/{id}/statistics

https://api.4league.app/v1/tournaments/{id}/statistics competitions:read players:read

Player-level rows, so both scopes are required.

Parameters

Example request

curl -sS "https://api.4league.app/v1/tournaments/{id}/statistics" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /tournaments/{id}/top-scorers

https://api.4league.app/v1/tournaments/{id}/top-scorers players:read

Paginated: returns the pagination envelope.

Parameters

Example request

curl -sS "https://api.4league.app/v1/tournaments/{id}/top-scorers" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /tournaments/{id}/cards

https://api.4league.app/v1/tournaments/{id}/cards players:read

Paginated: returns the pagination envelope.

Parameters

Example request

curl -sS "https://api.4league.app/v1/tournaments/{id}/cards" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

Matches

GET HEAD /matches/{id}

https://api.4league.app/v1/matches/{id} matches:read

Friendlies (no competition) are returned when home or away is in scope. season, when set, must be the current season of the match competition.

Parameters

Example request

curl -sS "https://api.4league.app/v1/matches/{matchId}" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

Example response

Captured from a seeded test organization (GET /v1/matches/{matchId}), HTTP 200.

{
  "data": {
    "competition": {
      "id": "6acddc3d41a6e2f5682625e6",
      "name": "c-6acddc3d41a6e2f5682625e6",
      "logo": null,
      "type": "league",
      "season": 3,
      "stage": "regular",
      "timezone": "UTC"
    },
    "match": {
      "id": "6acddc3d41a6e2f5682625ef",
      "status": "finished",
      "kickoffAt": "2026-01-05T12:00:00.000Z",
      "home": {
        "id": "6acddc3d41a6e2f5682625e8",
        "name": "TeamA",
        "shortName": "TEA",
        "logo": null
      },
      "away": {
        "id": "6acddc3d41a6e2f5682625ea",
        "name": "TeamB",
        "shortName": "TEA",
        "logo": null
      },
      "score": {
        "home": 1,
        "away": 1
      },
      "penalties": null,
      "leg": null,
      "twoLegs": false,
      "winner": "draw",
      "round": 1,
      "group": null
    }
  }
}

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /matches/{id}/lineups

https://api.4league.app/v1/matches/{id}/lineups matches:read

Parameters

Example request

curl -sS "https://api.4league.app/v1/matches/{id}/lineups" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /matches/{id}/events

https://api.4league.app/v1/matches/{id}/events matches:read

Parameters

Example request

curl -sS "https://api.4league.app/v1/matches/{id}/events" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /matches/{id}/statistics

https://api.4league.app/v1/matches/{id}/statistics matchStatistics:read

Parameters

Example request

curl -sS "https://api.4league.app/v1/matches/{id}/statistics" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

Teams

GET HEAD /teams/{id}

https://api.4league.app/v1/teams/{id} teams:read

Parameters

Example request

curl -sS "https://api.4league.app/v1/teams/{id}" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /teams/{id}/players

https://api.4league.app/v1/teams/{id}/players players:read

Paginated: returns the pagination envelope.

Parameters

Example request

curl -sS "https://api.4league.app/v1/teams/{teamId}/players?limit=2" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

Example response

Captured from a seeded test organization (GET /v1/teams/{teamId}/players?limit=2), HTTP 200.

{
  "data": [
    {
      "id": "6acddc3d41a6e2f5682625eb",
      "name": "PlayerAna",
      "number": 9,
      "position": null,
      "photo": "https://cdn.test/photos/ana.png",
      "teamId": "6acddc3d41a6e2f5682625e7"
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 1,
  "hasMore": false
}

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /teams/{id}/matches

https://api.4league.app/v1/teams/{id}/matches matches:read

from/to are always compared in UTC. A club id expands to the club and its most recent competition copies; when capped the response carries meta.truncated:true and meta.competitionsIncluded.

Paginated: returns the pagination envelope.

Parameters

Example request

curl -sS "https://api.4league.app/v1/teams/{id}/matches" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /teams/{id}/statistics

https://api.4league.app/v1/teams/{id}/statistics teams:read

Parameters

Example request

curl -sS "https://api.4league.app/v1/teams/{id}/statistics" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

Players

GET HEAD /players/{id}

https://api.4league.app/v1/players/{id} players:read

Parameters

Example request

curl -sS "https://api.4league.app/v1/players/{playerId}" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

Example response

Captured from a seeded test organization (GET /v1/players/{playerId}), HTTP 200.

{
  "data": {
    "player": {
      "id": "6acddc3d41a6e2f5682625eb",
      "name": "PlayerAna",
      "number": 9,
      "position": null,
      "photo": "https://cdn.test/photos/ana.png",
      "team": {
        "id": "6acddc3d41a6e2f5682625e7",
        "name": "TeamA",
        "shortName": "TEA",
        "logo": "https://cdn.test/team-a.png"
      }
    }
  }
}

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /players/{id}/statistics

https://api.4league.app/v1/players/{id}/statistics players:read

Parameters

Example request

curl -sS "https://api.4league.app/v1/players/{id}/statistics" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

GET HEAD /players/{id}/matches

https://api.4league.app/v1/players/{id}/matches matches:read

from/to are always compared in UTC.

Paginated: returns the pagination envelope.

Parameters

Example request

curl -sS "https://api.4league.app/v1/players/{id}/matches" \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

No captured example for this endpoint yet.

Possible errors

Listed errors are the ones that can apply based on the endpoint's parameters; see Errors for the full table.

• unauthorized 401
• forbidden 403
• proRequired 403
• scopeMissing 403
• notFound 404
• badRequest 400
• rateLimited 429
• quotaExceeded 429

Known limitations

• Only organization-scoped keys are documented. Competition-scoped keys are a known limitation and are not part of this description.
• Playoff and playout matches are known limitations: /tournaments/{id}/matches lists the requested competition only. Standings expose the playoff/playout tables.
• The organization tree follows the primary parent only; an organization reachable only through an additional parent can be fetched directly but is absent from the tree.
• Season filters on organization lists cover the live season only; archived seasons are not searched.
• The rate limiter and the failed-authentication block are per server worker, so limits are approximate.