KRKplaysTennis API

The KRKplaysTennis API rates amateur tennis players in Kraków from the results of league and tournament matches. Use it to show players their rating, explain why it changed, suggest fair opponents, or submit results for a competition you run.

A fictional API

KRKplaysTennis is a fictional API, built as a technical writing portfolio. The players, venues, and competitions are invented. You can run every example in these docs against a local mock server.

How ratings work

• A new player picks a starting level on the NTRP self-rating scale, from 1.5 to 5.5. The API converts it to a starting rating between 1000 and 1800.
• Each rated match moves the rating up or down, based on the result and on the opponent’s rating.
• A confidence value from 0 to 100 shows how settled the rating is. A new rating moves quickly, and a settled rating moves slowly.

The rating comes from results, not from the self-assessment. The self-assessed level is only the starting point. For the full model, with worked examples, see How ratings work.

What you can do

Task	Guide	Operations
Read player profiles and ratings	Quickstart	List players, Get a player’s rating
See why a rating changed	Explain a rating change	List a player’s rating history
Find opponents for a player	Find opponents for a player	List match suggestions
Browse competitions, venues, and results		List competitions, List venues, List matches
Submit a match result, as a competition organizer	Submit a match result	Submit a match result

Which credential you need

To	You need	Guide
Read any data	An API key	Authenticate with an API key
Submit match results	An OAuth 2.0 access token with the matches:write scope	Get an access token

Conventions

• Base URL: https://api.krkplaystennis.example/v1
• Format: requests and responses are JSON.
• Pagination: list operations return data and a next_cursor. Pass next_cursor as cursor to get the next page.
• Errors: every error is an RFC 9457 problem details object, with a type URL for each kind of error. See Errors.
• Times: timestamps follow RFC 3339. Availability windows use local time in Kraków (Europe/Warsaw).

Next steps

QuickstartStart the mock and make your first request in under 5 minutes.

Authenticate with an API keySend your API key with every read request.

Submit a match resultSend a result as a competition organizer and check that it's rated.

API referenceEvery operation, parameter, and schema, generated from the OpenAPI spec.