Docs/REST API

API Reference

REST API

REST API reference for TurnKit server endpoints.

Base URL

https://api.turnkit.dev

Auth

Use the API key or bearer token scheme defined in the OpenAPI document for each secured endpoint.

Raw Spec

Open OpenAPI document

API Overview

OpenAPI

3.1.0

Version

1.0.0

Endpoints

TurnKit game backend.

Client — Leaderboards

POST/v1/client/leaderboards/{slug}/scores

Submit a score

Operation

submitScore

Parameters

Name	In	Type	Required
slug	path	string	Yes

Request Body

Required · application/json

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

GET/v1/client/ping

Ping endpoint

Health check endpoint that returns current game key status and CCU

Operation

ping

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

GET/v1/client/leaderboards/{slug}/top

Get top scores

Operation

getTopScores

Parameters

Name	In	Type	Required
slug	path	string	Yes
limit	query	integer · int32	No

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

GET/v1/client/leaderboards/{slug}/me

Get player rank and surrounding scores

Operation

getPlayerScore

Parameters

Name	In	Type	Required
slug	path	string	Yes
surrounding	query	integer · int32	No

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

GET/v1/client/leaderboards/{slug}/combined

Get top scores + player context in one request

Operation

getCombined

Parameters

Name	In	Type	Required
slug	path	string	Yes
topLimit	query	integer · int32	No
surrounding	query	integer · int32	No

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

Dev — Dashboard

POST/v1/dev/dashboard/{gameKeyId}/upgrade/confirm

Confirm upgrade

Confirms an upgrade after the frontend shows the proration preview

Operation

confirmUpgrade

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes

Request Body

Required · application/json

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

POST/v1/dev/dashboard/{gameKeyId}/upgrade/checkout

Create upgrade checkout

Creates a checkout for new subscriptions or a proration preview for existing subscriptions

Operation

createUpgradeCheckout

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes

Request Body

Required · application/json

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

POST/v1/dev/dashboard/{gameKeyId}/auto-upgrade

Toggle auto-upgrade

Enables or disables automatic tier upgrades when limits are exceeded

Operation

toggleAutoUpgrade

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes

Request Body

Required · application/json

Responses

Status	Description	Content
200	OK	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

GET/v1/dev/dashboard

Get dashboard overview

Retrieves overview of all game keys with current CCU, tiers, and billing status

Operation

getOverview

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

GET/v1/dev/dashboard/{gameKeyId}/ccu

Get CCU chart data

Retrieves hourly CCU peak data for the last 7 days for a specific game key

Operation

getCcuChart

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

GET/v1/dev/dashboard/{gameKeyId}/billing

Get billing information

Retrieves billing status, tiers, and limits for a specific game key

Operation

getBilling

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

Dev — Game Keys

GET/v1/dev/game-keys

List game keys

Retrieves all game keys owned by the authenticated developer

Operation

listGameKeys

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

POST/v1/dev/game-keys

Create game key

Creates a new game key with the specified name for the authenticated developer

Operation

createGameKey

Parameters

Name	In	Type	Required
name	query	string	Yes

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

GET/v1/dev/game-keys/{gameKeyId}/client-keys

List client keys

Retrieves all active client keys for the specified game key

Operation

list

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

POST/v1/dev/game-keys/{gameKeyId}/client-keys

Generate client key

Generates a new client key for the specified game key

Operation

generate

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes
displayName	query	string	No

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

GET/v1/dev/game-keys/{gameKeyId}/dashboard

Get combined dashboard data

Retrieves the summary data needed to render the dashboard for a single game key

Operation

getDashboard

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

DELETE/v1/dev/game-keys/{gameKeyId}

Delete game key

Permanently deletes a game key and all associated data

Operation

deleteGameKey

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes

Responses

Status	Description	Content
200	OK	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

DELETE/v1/dev/game-keys/{gameKeyId}/client-keys/{clientKeyId}

Revoke client key

Revokes a client key, making it invalid for future API calls

Operation

revoke

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes
clientKeyId	path	string · uuid	Yes

Responses

Status	Description	Content
200	OK	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

Dev — Leaderboards

GET/v1/dev/game-keys/{gameKeyId}/leaderboards

List all leaderboards

Retrieves all leaderboards for the current game key

Operation

list

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

POST/v1/dev/game-keys/{gameKeyId}/leaderboards

Create a new leaderboard

Creates a new leaderboard with the specified configuration. Available enum values: sortOrder: ASC (for time-based where lower is better), DESC (for points where higher is better); scoreStrategy: BEST_ONLY (keeps only best score per player), MULTIPLE_ENTRIES (stores all submissions), CUMULATIVE (sums all submissions); resetFrequency: NONE, DAILY, WEEKLY, MONTHLY

Operation

create

Request Body

Required · application/json

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

POST/v1/dev/game-keys/{gameKeyId}/leaderboards/{slug}/reset

Reset leaderboard scores

Resets all scores for a leaderboard. Optionally archives scores before reset and applies a reset label

Operation

reset

Parameters

Name	In	Type	Required
slug	path	string	Yes
archive	query	boolean	No
resetLabel	query	string	No

Responses

Status	Description	Content
200	OK	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

POST/v1/dev/game-keys/{gameKeyId}/leaderboards/banned-players/{playerId}

Ban player

Bans a player from all leaderboards for the current game key

Operation

banPlayer

Parameters

Name	In	Type	Required
playerId	path	string	Yes
reason	query	string	No

Responses

Status	Description	Content
200	OK	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

DELETE/v1/dev/game-keys/{gameKeyId}/leaderboards/banned-players/{playerId}

Unban player

Removes a player from the banned list for the current game key

Operation

unbanPlayer

Parameters

Name	In	Type	Required
playerId	path	string	Yes

Responses

Status	Description	Content
200	OK	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

DELETE/v1/dev/game-keys/{gameKeyId}/leaderboards/{slug}

Delete leaderboard

Permanently deletes a leaderboard and all its scores

Operation

delete

Parameters

Name	In	Type	Required
slug	path	string	Yes

Responses

Status	Description	Content
200	OK	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

PATCH/v1/dev/game-keys/{gameKeyId}/leaderboards/{slug}

Update leaderboard display name

Updates only the display name of an existing leaderboard

Operation

update

Parameters

Name	In	Type	Required
slug	path	string	Yes
displayName	query	string	Yes

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

GET/v1/dev/game-keys/{gameKeyId}/leaderboards/{slug}/scores

Get leaderboard scores

Retrieves paginated scores for a specific leaderboard

Operation

getScores

Parameters

Name	In	Type	Required
slug	path	string	Yes
page	query	integer · int32	No
size	query	integer · int32	No

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

GET/v1/dev/game-keys/{gameKeyId}/leaderboards/banned-players

List banned players

Retrieves all banned player IDs for the current game key

Operation

listBanned

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

DELETE/v1/dev/game-keys/{gameKeyId}/leaderboards/{slug}/scores/{scoreId}

Remove specific score

Removes a specific score entry from a leaderboard

Operation

removeScore

Parameters

Name	In	Type	Required
scoreId	path	string · uuid	Yes

Responses

Status	Description	Content
200	OK	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

Dev — Project Setup

POST/v1/dev/project-setup

Get or create project setup

Creates the same default project setup used by Unity, or returns the existing setup for the authenticated developer and project name

Operation

getOrCreateProjectSetup

Request Body

Required · application/json

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

developer-auth-controller

POST/v1/dev/auth/refresh

POST /v1/dev/auth/refresh

Operation

refresh

Parameters

Name	In	Type	Required
turnkit_dev_refresh	cookie	string	No

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

POST/v1/dev/auth/logout

POST /v1/dev/auth/logout

Operation

logout

Parameters

Name	In	Type	Required
turnkit_dev_refresh	cookie	string	No

Responses

Status	Description	Content
200	OK	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

POST/v1/dev/auth/exchange

POST /v1/dev/auth/exchange

Operation

exchange

Request Body

Required · application/json

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

Player Auth

TurnKit player authentication for SIGNED and TURNKIT_AUTH modes

POST/v1/client/auth/signed/exchange

Verify a signed player proof and receive a player JWT.

Operation

exchangeSigned

Parameters

Name	In	Type	Required
Authorization	header	string	Yes

Request Body

Required · application/json

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

POST/v1/client/auth/otp/verify

Verify OTP and receive a player JWT. Token valid for 14 days.

Operation

verifyOtp

Parameters

Name	In	Type	Required
Authorization	header	string	Yes

Request Body

Required · application/json

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

POST/v1/client/auth/otp/request

Request an OTP for a player email. Rate limited: 3 per 10 minutes.

Operation

requestOtp

Parameters

Name	In	Type	Required
Authorization	header	string	Yes

Request Body

Required · application/json

Responses

Status	Description	Content
200	OK	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

Player ID Auth

Configure player identity verification per game key

GET/v1/dev/game-keys/{gameKeyId}/player-id/smtp

Get SMTP config (password masked)

Operation

getSmtp

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

PUT/v1/dev/game-keys/{gameKeyId}/player-id/smtp

Save SMTP config for TurnKit player auth emails

Operation

saveSmtp

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes

Request Body

Required · application/json

Responses

Status	Description	Content
200	OK	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

DELETE/v1/dev/game-keys/{gameKeyId}/player-id/smtp

Delete SMTP config

Operation

deleteSmtp

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes

Responses

Status	Description	Content
204	No Content	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

PUT/v1/dev/game-keys/{gameKeyId}/player-id/mode

Set player ID mode for a game key

Operation

setMode

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes

Request Body

Required · application/json

Responses

Status	Description	Content
200	OK	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

POST/v1/dev/game-keys/{gameKeyId}/player-id/secret/rotate

Rotate player ID secret. Previous secret immediately invalidated.

Operation

rotateSecret

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

POST/v1/dev/game-keys/{gameKeyId}/player-id/secret/generate

Generate player ID secret. Returned ONCE — store securely. Invalidates previous secret.

Operation

generateSecret

Parameters

Name	In	Type	Required
gameKeyId	path	string · uuid	Yes

Responses

Status	Description	Content
201	Created	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

Relay Configs

Manage TurnRelay match configurations

GET/v1/dev/relay-configs/{slug}

Get a relay config by slug

Operation

get

Parameters

Name	In	Type	Required
gameKeyId	query	string · uuid	Yes
slug	path	string	Yes

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

PUT/v1/dev/relay-configs/{slug}

Update a relay config — replaces lists entirely

Updates an existing relay configuration. Enum values: turnEnforcement: ROUND_ROBIN, FREE; votingMode: SYNC, ASYNC; failAction: SKIP_TURN, END_GAME

Operation

update

Parameters

Name	In	Type	Required
gameKeyId	query	string · uuid	Yes
slug	path	string	Yes

Request Body

Required · application/json

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

DELETE/v1/dev/relay-configs/{slug}

Delete a relay config

Operation

delete

Parameters

Name	In	Type	Required
gameKeyId	query	string · uuid	Yes
slug	path	string	Yes

Responses

Status	Description	Content
204	No Content	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

GET/v1/dev/relay-configs

List all relay configs for a game key

Operation

list

Parameters

Name	In	Type	Required
gameKeyId	query	string · uuid	Yes

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

POST/v1/dev/relay-configs

Create a relay config

Creates a new relay configuration with the specified parameters. Enum values: turnEnforcement: ROUND_ROBIN, FREE; votingMode: SYNC, ASYNC; failAction: SKIP_TURN, END_GAME

Operation

create

Parameters

Name	In	Type	Required
gameKeyId	query	string · uuid	Yes

Request Body

Required · application/json

Responses

Status	Description	Content
201	Created	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

Relay Queue

Join matchmaking queue

POST/v1/client/relay/queue

Join matchmaking queue for a relay config. Returns sessionId to connect WebSocket.

Operation

join

Request Body

Required · application/json

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/

DELETE/v1/client/relay/queue/{slug}

Leave the matchmaking queue

Operation

leave

Parameters

Name	In	Type	Required
slug	path	string	Yes

Responses

Status	Description	Content
200	OK	None
403	Forbidden	/
404	Not Found	/
409	Conflict	/

unity-auth-controller

GET/v1/dev/auth-status

GET /v1/dev/auth-status

Operation

getAuthStatus

Parameters

Name	In	Type	Required
pollId	query	string	Yes

Responses

Status	Description	Content
200	OK	/
403	Forbidden	/
404	Not Found	/
409	Conflict	/