List competitions

GET

/competitions

const url = 'https://api.krkplaystennis.example/v1/competitions?limit=20&cursor=bWF0XzJ2YjZucDRrdGY&type=league&season=2026-autumn&venue_id=ven_7hk2p9wq4m';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.krkplaystennis.example/v1/competitions?limit=20&cursor=bWF0XzJ2YjZucDRrdGY&type=league&season=2026-autumn&venue_id=ven_7hk2p9wq4m' \
  --header 'X-API-Key: <X-API-Key>'

Returns leagues and tournaments, ordered by start date, newest first.

Authorizations

ApiKeyAuth

Parameters

Query Parameters

limit

integer

default: 20 >= 1 <= 100

Maximum number of items to return.

cursor

string

The next_cursor value from the previous page. Omit it to get the first page.

Example

bWF0XzJ2YjZucDRrdGY

type

league for a season-long round robin, tournament for a knockout event over a few days.

string

Allowed values: league tournament

Returns only competitions of this type.

season

A season, written as the year and a season name.

string

/^[0-9]{4}-(spring|summer|autumn|winter)$/

Returns only competitions in this season.

venue_id

A venue ID. Starts with ven_.

string

/^ven_[a-z0-9]{10}$/

Returns only competitions played at this venue.

Responses

200

A page of competitions.

application/json

object

data

required

Array<object>

object

required

A competition ID. Starts with cmp_.

string

/^cmp_[a-z0-9]{10}$/

name

required

string

type

required

league for a season-long round robin, tournament for a knockout event over a few days.

string

Allowed values: league tournament

organizer

required

The organizer. Only this organizer can submit results for the competition.

object

required

An organizer ID. Starts with org_.

string

/^org_[a-z0-9]{10}$/

name

required

string

season

required

A season, written as the year and a season name.

string

/^[0-9]{4}-(spring|summer|autumn|winter)$/

starts_on

required

The first day of the competition.

string format: date

ends_on

required

The last day of the competition.

string format: date

match_format

required

The scoring rules for every match in the competition. All matches are best of three sets.

Each field is one rule, so new formats need new fields, not new enum values.

object

games_per_set

required

Games needed to win a set.

6: a set ends at 6 games with a 2-game lead or at 7-5. At 6-6, a tiebreak decides the set, which ends 7-6.
4: short sets. A set ends at 4 games with a 2-game lead or at 5-3. At 4-4, a tiebreak decides the set, which ends 5-4.

integer

Allowed values: 4 6

no_ad

required

true when a game at deuce is decided by a single point. The API records games, not points, so this rule doesn’t affect score validation or ratings.

boolean

final_set

required

How the match is decided at one set all:

full_set: a normal third set.
match_tiebreak: a tiebreak to 10 points, with a 2-point lead, instead of a third set.

string

Allowed values: full_set match_tiebreak

venue_ids

required

Venues where the competition’s matches are played.

Array<string>

next_cursor

required

Pass this value as cursor to get the next page. null means this is the last page.

string | null

Examples

competitions

Competitions in 2026

{
  "data": [
    {
      "id": "cmp_1qv7mz3kpd",
      "name": "Nowa Huta Indoor Open 2026",
      "type": "tournament",
      "organizer": {
        "id": "org_9tn3bx6rlp",
        "name": "Nowa Huta Indoor Tennis Hall"
      },
      "season": "2026-winter",
      "starts_on": "2026-12-05",
      "ends_on": "2026-12-07",
      "match_format": {
        "games_per_set": 4,
        "no_ad": true,
        "final_set": "match_tiebreak"
      },
      "venue_ids": [
        "ven_3xr8tn5cva"
      ]
    },
    {
      "id": "cmp_6tw2hn8rxe",
      "name": "Kraków Autumn League 2026",
      "type": "league",
      "organizer": {
        "id": "org_4kd7ws2mzq",
        "name": "Kraków Amateur Tennis Association"
      },
      "season": "2026-autumn",
      "starts_on": "2026-09-01",
      "ends_on": "2026-11-30",
      "match_format": {
        "games_per_set": 6,
        "no_ad": false,
        "final_set": "match_tiebreak"
      },
      "venue_ids": [
        "ven_7hk2p9wq4m",
        "ven_3xr8tn5cva"
      ]
    }
  ],
  "next_cursor": null
}

400

The request is malformed, for example a query parameter has the wrong type.

application/problem+json

An error, as RFC 9457 problem details.

object

type

required

A URL that identifies the error type and links to its documentation.

string format: uri

title

required

A short summary of the error type. It’s the same for every error of this type.

string

status

required

The HTTP status code.

integer

>= 400 <= 599

detail

required

An explanation of this occurrence of the error.

string

instance

The request path that caused the error.

string

errors

One item per invalid field or parameter. Only for invalid-request, invalid-score, and validation-failed.

Array<object>

object

pointer

required

A JSON Pointer to the invalid field in the request body, or #/ followed by the name of an invalid query parameter.

string

detail

required

What’s wrong with the field and how to fix it.

string

Examples

invalidRequest

Limit out of range

{
  "type": "https://saverio-cirillo.com/krk-plays-tennis-api/errors/#invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request has 1 invalid parameter.",
  "instance": "/v1/players",
  "errors": [
    {
      "pointer": "#/limit",
      "detail": "limit must be between 1 and 100."
    }
  ]
}

401

The credentials are missing, invalid, or expired.

application/problem+json

An error, as RFC 9457 problem details.

object

type

required

A URL that identifies the error type and links to its documentation.

string format: uri

title

required

A short summary of the error type. It’s the same for every error of this type.

string

status

required

The HTTP status code.

integer

>= 400 <= 599

detail

required

An explanation of this occurrence of the error.

string

instance

The request path that caused the error.

string

errors

One item per invalid field or parameter. Only for invalid-request, invalid-score, and validation-failed.

Array<object>

object

pointer

required

A JSON Pointer to the invalid field in the request body, or #/ followed by the name of an invalid query parameter.

string

detail

required

What’s wrong with the field and how to fix it.

string

Examples

unauthenticated

Missing API key

{
  "type": "https://saverio-cirillo.com/krk-plays-tennis-api/errors/#unauthenticated",
  "title": "Authentication required",
  "status": 401,
  "detail": "Send a valid API key in the X-API-Key header.",
  "instance": "/v1/players/plr_2b7xq9mhk4"
}

429

You sent too many requests. Wait for the number of seconds in Retry-After, then retry.

application/problem+json

An error, as RFC 9457 problem details.

object

type

required

A URL that identifies the error type and links to its documentation.

string format: uri

title

required

A short summary of the error type. It’s the same for every error of this type.

string

status

required

The HTTP status code.

integer

>= 400 <= 599

detail

required

An explanation of this occurrence of the error.

string

instance

The request path that caused the error.

string

errors

One item per invalid field or parameter. Only for invalid-request, invalid-score, and validation-failed.

Array<object>

object

pointer

required

A JSON Pointer to the invalid field in the request body, or #/ followed by the name of an invalid query parameter.

string

detail

required

What’s wrong with the field and how to fix it.

string

Examples

rateLimited

Rate limit reached

{
  "type": "https://saverio-cirillo.com/krk-plays-tennis-api/errors/#rate-limited",
  "title": "Rate limit reached",
  "status": 429,
  "detail": "This API key is limited to 60 requests per minute. Retry after 30 seconds.",
  "instance": "/v1/matches"
}

Headers

Retry-After

integer

>= 1

Number of seconds to wait before you retry.