List players

GET

/players

const url = 'https://api.krkplaystennis.example/v1/players?limit=20&cursor=bWF0XzJ2YjZucDRrdGY&min_rating=1300&max_rating=1500&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/players?limit=20&cursor=bWF0XzJ2YjZucDRrdGY&min_rating=1300&max_rating=1500&venue_id=ven_7hk2p9wq4m' \
  --header 'X-API-Key: <X-API-Key>'

Returns players ordered by display name. Filter by rating range or by preferred venue.

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

min_rating

integer

Returns only players with a rating greater than or equal to this value.

Example

max_rating

integer

Returns only players with a rating less than or equal to this value.

Example

venue_id

A venue ID. Starts with ven_.

string

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

Returns only players who list this venue as a preferred venue.

Responses

200

A page of players.

application/json

object

data

required

Array<object>

object

required

A player ID. Starts with plr_.

string

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

display_name

required

The player’s first name and last initial.

string

self_assessed_ntrp

required

The player’s self-assessed level on the NTRP scale, from 1.5 to 5.5 in steps of 0.5. It sets the starting rating as 1000 + (NTRP - 1.5) × 200 and doesn’t change afterward.

number

>= 1.5 <= 5.5 multiple of 0.5

rating

required

A player’s current rating and confidence.

object

value

required

A rating. New players start between 1000 and 1800, based on their self-assessed NTRP level.

integer

confidence

required

How settled a rating is, from 0 to 100. New players start at 20. Each rated match adds 10, up to 95. After 60 days without a rated match, confidence drops by 5 every 30 days, down to 20.

integer

<= 100

preferred_venue_ids

required

Venues where the player prefers to play.

Array<string>

availability

required

Weekly time windows when the player can usually play.

Array<object>

A weekly time window, in local time (Europe/Warsaw).

object

day

required

string

Allowed values: monday tuesday wednesday thursday friday saturday sunday

start

required

Start time, as HH:MM in 24-hour format.

string

/^([01][0-9]|2[0-3]):[0-5][0-9]$/

end

required

End time, as HH:MM in 24-hour format. Must be later than start.

string

/^([01][0-9]|2[0-3]):[0-5][0-9]$/

created_at

required

When the player joined.

string format: date-time

next_cursor

required

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

string | null

Examples

players

Players at Riverside Courts Podgórze

{
  "data": [
    {
      "id": "plr_9fz3tr6wn1",
      "display_name": "Kasia W.",
      "self_assessed_ntrp": 4,
      "rating": {
        "value": 1499,
        "confidence": 70
      },
      "preferred_venue_ids": [
        "ven_7hk2p9wq4m"
      ],
      "availability": [
        {
          "day": "saturday",
          "start": "10:00",
          "end": "14:00"
        },
        {
          "day": "sunday",
          "start": "10:00",
          "end": "12:00"
        }
      ],
      "created_at": "2026-05-11T17:30:00Z"
    },
    {
      "id": "plr_8mq4ws1yd6",
      "display_name": "Marta Z.",
      "self_assessed_ntrp": 3.5,
      "rating": {
        "value": 1382,
        "confidence": 30
      },
      "preferred_venue_ids": [
        "ven_3xr8tn5cva",
        "ven_7hk2p9wq4m"
      ],
      "availability": [
        {
          "day": "tuesday",
          "start": "19:00",
          "end": "22:00"
        }
      ],
      "created_at": "2026-09-04T19:02:00Z"
    },
    {
      "id": "plr_2b7xq9mhk4",
      "display_name": "Ola K.",
      "self_assessed_ntrp": 3.5,
      "rating": {
        "value": 1432,
        "confidence": 30
      },
      "preferred_venue_ids": [
        "ven_7hk2p9wq4m"
      ],
      "availability": [
        {
          "day": "tuesday",
          "start": "18:00",
          "end": "21:00"
        },
        {
          "day": "saturday",
          "start": "09:00",
          "end": "13:00"
        }
      ],
      "created_at": "2026-09-02T08:15:00Z"
    }
  ],
  "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.