Players

Get all players

get

Retrieve all players for the authenticated app

Authorizations

AppAPIKey

x-app-api-keystringRequired

App API key in format:

Responses

200

Players retrieved successfully

application/json

401

Unauthorized - invalid or missing API key

application/json

500

Internal server error

application/json

get

/apps/players

HTTPcURLJavaScriptPython

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-03-21T01:12:14.227Z",
      "updatedAt": "2026-03-21T01:12:14.227Z"
    }
  ]
}

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

AppAPIKey

x-app-api-keystringRequired

App API key in format:

Body

application/json

userIdstring · nullableOptional

Optional user ID

displayNamestringRequired

Player display name

Responses

201

Player created successfully

application/json

400

Invalid request data

application/json

401

Unauthorized - invalid or missing API key

application/json

500

Internal server error

application/json

post

/apps/players

HTTPcURLJavaScriptPython

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-03-21T01:12:14.227Z",
  "updatedAt": "2026-03-21T01:12:14.227Z"
}

Delete player profile image

delete

Remove the profile image for a player

Authorizations

AppAPIKey

x-app-api-keystringRequired

App API key in format:

Path parameters

idstringRequired

Player ID

Responses

200

Profile image deleted successfully

application/json

successbooleanRequiredExample: true

401

Unauthorized - invalid or missing API key

application/json

404

Player not found

application/json

500

Internal server error

application/json

delete

/apps/players/{id}/profile-image

HTTPcURLJavaScriptPython

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

AppAPIKey

x-app-api-keystringRequired

App API key in format:

Path parameters

idstringRequired

Player ID

Body

multipart/form-data

imagestring · binaryRequired

Profile image file

Responses

200

Profile image updated successfully

application/json

imageUrlstringRequired

URL of the uploaded image

400

Invalid request

application/json

401

Unauthorized - invalid or missing API key

application/json

404

Player not found

application/json

500

Internal server error

application/json

patch

/apps/players/{id}/profile-image

HTTPcURLJavaScriptPython

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

AppAPIKey

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

401

Unauthorized - invalid or missing API key

application/json

404

Player not found

application/json

500

Internal server error

application/json

get

/apps/players/{id}

HTTPcURLJavaScriptPython

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-03-21T01:12:14.227Z",
  "updatedAt": "2026-03-21T01:12:14.227Z"
}

Update a player

patch

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

Authorizations

AppAPIKey

x-app-api-keystringRequired

App API key in format:

Path parameters

idstringRequired

Player ID

Body

application/json

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

400

Invalid request data

application/json

401

Unauthorized - invalid or missing API key

application/json

403

Forbidden - can only update players belonging to your app

application/json

404

Player not found

application/json

500

Internal server error

application/json

patch

/apps/players/{id}

HTTPcURLJavaScriptPython

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-03-21T01:12:14.227Z",
  "updatedAt": "2026-03-21T01:12:14.227Z"
}

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

AppAPIKey

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)

401

Unauthorized - invalid or missing API key

application/json

404

Player not found or has no ranking

application/json

500

Internal server error

application/json

get

/apps/players/{playerId}/global-ranking

HTTPcURLJavaScriptPython

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"
}