Ctrlk
GitHubX
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Players

Get all players

get

Retrieve all players for the authenticated app

Authorizations
x-app-api-keystringRequired

App API key in format:

Responses
200

Players retrieved successfully

application/json
get/apps/players
GET /api/v1/apps/players HTTP/1.1
x-app-api-key: YOUR_API_KEY
Accept: */*

{
  "players": [
    {
      "id": "text",
      "displayName": "text",
      "userId": "text",
      "imageUrl": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Create a new player

post

Create a new player for the authenticated app. Players with duplicate names are not allowed for the same app.

Authorizations
x-app-api-keystringRequired

App API key in format:

Body
userIdstring · nullableOptional

Optional user ID

displayNamestringRequired

Player display name

Responses
201

Player created successfully

application/json
idstringRequired

Unique player identifier

displayNamestringRequired

Player display name

userIdstring · nullableOptional

Associated user ID

imageUrlstring · nullableOptional

URL to player's profile image

createdAtstring · date-timeRequired

Creation timestamp

updatedAtstring · date-timeRequired

Last update timestamp

post/apps/players
POST /api/v1/apps/players HTTP/1.1
x-app-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 38

{
  "userId": "text",
  "displayName": "text"
}
{
  "id": "text",
  "displayName": "text",
  "userId": "text",
  "imageUrl": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Delete player profile image

delete

Remove the profile image for a player

Authorizations
x-app-api-keystringRequired

App API key in format:

Path parameters
idstringRequired

Player ID

Responses
200

Profile image deleted successfully

application/json
successbooleanRequiredExample: true
delete/apps/players/{id}/profile-image
DELETE /api/v1/apps/players/{id}/profile-image HTTP/1.1
x-app-api-key: YOUR_API_KEY
Accept: */*

{
  "success": true
}

Upload or update player profile image

patch

Upload or update a player's profile image. The image must meet specific requirements:

  • Minimum dimensions: 512x512 pixels

  • Maximum dimensions: 1024x1024 pixels (larger images will be automatically resized)

  • Maximum file size: 5MB

  • Supported formats: JPEG, PNG, GIF, WebP

  • Square aspect ratio recommended for best results

Authorizations
x-app-api-keystringRequired

App API key in format:

Path parameters
idstringRequired

Player ID

Body
imagestring · binaryRequired

Profile image file

Responses
200

Profile image updated successfully

application/json
imageUrlstringRequired

URL of the uploaded image

patch/apps/players/{id}/profile-image
PATCH /api/v1/apps/players/{id}/profile-image HTTP/1.1
x-app-api-key: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 18

{
  "image": "binary"
}
{
  "imageUrl": "text"
}

Get a player by ID

get

Retrieve a specific player by their ID. Optionally include global rankings across all mini-game types.

Authorizations
x-app-api-keystringRequired

App API key in format:

Path parameters
idstringRequired

Player ID

Query parameters
includeGlobalRankingsbooleanOptional

If true, includes the player's global rankings for all mini-game types they have participated in

Default: false
Responses
200

Player retrieved successfully

application/json
or
get/apps/players/{id}
GET /api/v1/apps/players/{id} HTTP/1.1
x-app-api-key: YOUR_API_KEY
Accept: */*

{
  "id": "text",
  "displayName": "text",
  "userId": "text",
  "imageUrl": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Update a player

patch

Update a player's information (display name and user association)

Authorizations
x-app-api-keystringRequired

App API key in format:

Path parameters
idstringRequired

Player ID

Body
userIdstring · nullableOptional

Optional user ID

displayNamestringRequired

Player display name

Responses
200

Player updated successfully

application/json
idstringRequired

Unique player identifier

displayNamestringRequired

Player display name

userIdstring · nullableOptional

Associated user ID

imageUrlstring · nullableOptional

URL to player's profile image

createdAtstring · date-timeRequired

Creation timestamp

updatedAtstring · date-timeRequired

Last update timestamp

patch/apps/players/{id}
PATCH /api/v1/apps/players/{id} HTTP/1.1
x-app-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 38

{
  "userId": "text",
  "displayName": "text"
}
{
  "id": "text",
  "displayName": "text",
  "userId": "text",
  "imageUrl": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Get player's global ranking

get

Get a player's global ranking across all default games or all games for a specific mini game type

Authorizations
x-app-api-keystringRequired

App API key in format:

Path parameters
playerIdstringRequired

Player ID

Query parameters
miniGameTypeIdstringOptional

Optional mini game type ID to get ranking for a specific game type. If not provided, the ranking for all default games will be returned.

miniGameTypeNamestringOptional

Optional mini game type name to get ranking for a specific game type. If not provided, the ranking for all default games will be returned.

Responses
200

Player ranking retrieved successfully

application/json
highestScorenumberRequired

Player's highest score

rankinginteger · min: 1Required

Player's global ranking

miniGameTypeIdstring · nullableOptional

Mini game type ID (null for default game type)

miniGameTypeNamestring · nullableOptional

Mini game type name (null for default game type)

get/apps/players/{playerId}/global-ranking
GET /api/v1/apps/players/{playerId}/global-ranking HTTP/1.1
x-app-api-key: YOUR_API_KEY
Accept: */*

{
  "highestScore": 1,
  "ranking": 1,
  "miniGameTypeId": "text",
  "miniGameTypeName": "text"
}
PreviousApps
NextGame Sessions

Last updated