Players

Get all players

get

Retrieve all players for the authenticated app

Authorizations
Responses
200

Players retrieved successfully

application/json
get
/apps/players
GET /api/v1/apps/players HTTP/1.1
Host: 
x-app-api-key: YOUR_API_KEY
Accept: */*
{
  "players": [
    {
      "id": "text",
      "displayName": "text",
      "userId": "text",
      "imageUrl": "text",
      "createdAt": "2025-10-31T04:37:30.940Z",
      "updatedAt": "2025-10-31T04:37:30.940Z"
    }
  ]
}

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
Body
userIdstring | nullableOptional

Optional user ID

displayNamestringRequired

Player display name

Responses
201

Player created successfully

application/json
post
/apps/players
POST /api/v1/apps/players HTTP/1.1
Host: 
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": "2025-10-31T04:37:30.940Z",
  "updatedAt": "2025-10-31T04:37:30.940Z"
}

Delete player profile image

delete

Remove the profile image for a player

Authorizations
Path parameters
idstringRequired

Player ID

Responses
200

Profile image deleted successfully

application/json
delete
/apps/players/{id}/profile-image
DELETE /api/v1/apps/players/{id}/profile-image HTTP/1.1
Host: 
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
Path parameters
idstringRequired

Player ID

Body
imagestring · binaryRequired

Profile image file

Responses
200

Profile image updated successfully

application/json
patch
/apps/players/{id}/profile-image
PATCH /api/v1/apps/players/{id}/profile-image HTTP/1.1
Host: 
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
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
Responseone of
or
get
/apps/players/{id}
GET /api/v1/apps/players/{id} HTTP/1.1
Host: 
x-app-api-key: YOUR_API_KEY
Accept: */*
{
  "id": "text",
  "displayName": "text",
  "userId": "text",
  "imageUrl": "text",
  "createdAt": "2025-10-31T04:37:30.940Z",
  "updatedAt": "2025-10-31T04:37:30.940Z"
}

Update a player

patch

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

Authorizations
Path parameters
idstringRequired

Player ID

Body
userIdstring | nullableOptional

Optional user ID

displayNamestringRequired

Player display name

Responses
200

Player updated successfully

application/json
patch
/apps/players/{id}
PATCH /api/v1/apps/players/{id} HTTP/1.1
Host: 
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": "2025-10-31T04:37:30.940Z",
  "updatedAt": "2025-10-31T04:37:30.940Z"
}

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
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
get
/apps/players/{playerId}/global-ranking
GET /api/v1/apps/players/{playerId}/global-ranking HTTP/1.1
Host: 
x-app-api-key: YOUR_API_KEY
Accept: */*
{
  "highestScore": 1,
  "ranking": 1,
  "miniGameTypeId": "text",
  "miniGameTypeName": "text"
}

Last updated