User objects

Each pointercrate user is represented by a User object.

If the display name is not null, it will replace a user's username wherever their name is displayed.

There is only one form of user objects:

Field Type Description
id int The user's ID
name string The user's name
permissions bitmask The user's access permissions
display_name string The user's display name. This can be null.
youtube_channel string The user's linked youtube channel. This can be null

Example object

{
  "display_name": "stadust",
  "id": 2,
  "name": "stardust1971",
  "permissions": 0,
  "youtube_channel": null
}

Nationality objects

Object representing some nation

Field Type Description
nation string The nation's name
country_code string The nation's ISO country code. Always exactly 2 characters long

Example objects

Short Form

{
  "nation": "Germany",
  "country_code": "DE"
}

Record objects

Each record on the list is represented by a Record object. The following invariants hold true for all player objects

  • The progress value lies within demon.requirement and 100
  • Every video value is unique
  • Every combination of demon, player and status values is unique
  • Every video value is in one of the formats listed here, or null

The object only contains the submitter information if the object has been requested with sufficient permissions. Requests without ExtendedAccess permissions can only retrieve approved records

Minimal Form

The minimal (formerly called embedded form) form of record objects is returned if a record object is part of another object.

Field Type Description
id integer The record's id
progress integer The progress achieved by the record holder
status RecordStatus The record's status.
video URL? The record's video.

Depending on the context the object is returned in, one (or both) of the following fields will be present:

Field Type Description
player Player The record holder
demon Demon The demon the record was made on

Listed Form

The listed form (formerly called short form) of record objects is returned by GET /records/.

Field Type Description
id integer The record's id
progress integer The progress achieved by the record holder
status RecordStatus The record's status.
video URL? The record's video.
player Player The record holder
demon Demon The demon the record was made on
submitter integer The internal ID of the submitter

Full Form

The full (formerly called long form) form of record objects is returned by GET /records/{record_id}. The notes field is always null if you do not have at least ListHelper permissions.

Field Type Description
id integer The record's id
progress integer The progress achieved by the record's holder
video URL? The record's video.
status RecordStatus The record's status.
notes string? Notes on the record
player Player The record holder
demon Demon The demon the record was made on
submitter Submitter? The person that submitted the record, as an submitter object

Enum RecordStatus

Value Description
approved The record has been approved and is displayed on the list
rejected The record has been rejected
submitted The record has been submitted and is awaiting review

Example objects

Minimal form

Here with an embedded demon object:

{
  "id": 1,
  "progress": 100,
  "demon": {
    "name": "Cadrega City",
    "position": 1
  },
  "status": "approved",
  "player": "Aquatias"
}

Full form

Here without an embedded submitter object

{
  "demon": {
    "name": "Cadrega City",
    "position": 34
  },
  "id": 2,
  "player": {
    "banned": false,
    "id": 5,
    "name": "AeonAir"
  },
  "progress": 100,
  "status": "approved",
  "submitter": null,
  "video": null
}

Demon objects

Each demon on the list is represented by a Demon object. The following assumptions can be made about these:

  • The requirement value lies between 0 and 100.
  • There are no holes in the positioning and the position value is greater than 0
  • Every video value, if provided, is in one of the formats listed here, or null

Note that although on the website the record requirement for demons on the extended list is always displayed as 100%, Demon objects still save their requirement from when they were on the main list.

Minimal Form

When embedded into other objects (for example, as part of a Record), only the following minimal representation of each demon is provided:

Field Type Description
name string The name of the demon
position integer The position of the demon
id integer The demons internal ID (has nothing to do with its level ID on the geometry dash servers)

Listed Form

When retrieving demons via GET /demons/, only the following partial representation of each demon is provided:

Field Type Description
name string The name of the demon
position integer The position of the demon
id integer The demons internal ID (has nothing to do with its level ID on the geometry dash servers)
publisher Player The player that published this demon
verifier Player The player that verified this demon
video URL? The verification video

Full Form

The listed record objects do not contain the current demon embedded into the demon field.

Field Type Description
name string The name of the demon
position integer The position of the demon
id integer The demons internal ID (has nothing to do with its level ID on the geometry dash servers)
requirement integer The minimum percentage a record on this demon has to be, to be accepted
video URL? The verification video.
verifier Player The demon's verifier
publisher Player The demon's publisher
creators List[Player] The demon's creators
records List[Record] All approved records for this demon

Example objects

Minimal form

{
  "name": "Cadrega City",
  "position": 34,
  "id": 1
}

Listed form

{
  "name": "Cadrega City",
  "position": 34,
  "id": 1,
  "publisher": {
    "name": "Pennutoh",
    "id": 123,
    "banned": false
  },
  "verifier": {
    "banned": false,
    "id": 3,
    "name": "Sunix"
  },
  "video": "https://www.youtube.com/watch?v=cHEGAqOgddA"
}

Long form

{
  "creators": [
    {
      "banned": false,
      "id": 2,
      "name": "Pennutoh"
    }
  ],
  "name": "Cadrega City",
  "position": 34,
  "id": 1,
  "publisher": {
    "banned": false,
    "id": 2,
    "name": "Pennutoh"
  },
  "records": [],
  "requirement": 54,
  "verifier": {
    "banned": false,
    "id": 3,
    "name": "Sunix"
  },
  "video": "https://www.youtube.com/watch?v=cHEGAqOgddA"
}

Player objects

Each player on the list is represented by a Player object. The following invariant holds true for any player object:

  • If the player is banned, they do not have any approved or submitted records on the list

Note that it is not possible to retrieve a player's demonlist score via the API. You can calculate it yourself based on the records list

Minimal Form

When part of the representation of another object, a player has the following fields:

Field Type Description
id integer The player's id
name string The player's name
banned boolean Value indicating whether the player is banned

Listed Form

When retrieving players via GET /players/

Field Type Description
id integer The player's id
name string The player's name
banned boolean Value indicating whether the player is banned
nationality Nationality The player's nationality, if set

Full Form

The listed record objects do not contain the current player embedded into the player field.

Field Type Description
id integer The player's id
name string The player's name
banned boolean Value indicating whether the player is banned
nationality Nationality The player's nationality, if set
created List[Demon] A list of demons the player created
records List[Record] A list of records the player has on the list
published List[Demon] A list of demons the player has published
verified List[Demon] A list of demons the player has verified

Example objects

Minimal form

{
  "id": 4,
  "name": "Pennutoh",
  "banned": false
}

Listed Form

{
  "id": 4,
  "name": "Pennutoh",
  "banned": false,
  "nationality": {
    "nation": "Andorra",
    "country_code": "AD"
  }
}

Full form

{
  "banned": false,
  "beaten": [],
  "records": [
    {
      "id": 12,
      "name": "Cadrega City",
      "progress": 100,
      "status": "approved"
    }
  ],
  "id": 2,
  "name": "Pennutoh",
  "nationality": {
    "nation": "Andorra",
    "country_code": "AD"
  },
  "published": [
    {
      "name": "Cadrega City",
      "position": 34
    }
  ],
  "verified": []
}

Submitter objects

Everyone who submits a record gets assigned an incremental submitter id, internally used to keep track of who has been banned from submitting records. The following invariant holds true for any submitter object:

  • If the submitter is banned, he cannot submit new records and all his previously submitted records are either marked as approved or rejected

Minimal/Listed Form

The short form is returned by the GET /submitters/ pagination endpoint.

Field Type Description
id int The submitter's ID
banned boolean Value indicating whether the submitter is banned

Full Form

The long form is returned by the GET /submitters/ endpoint.

Field Type Description
id int The submitter's ID
banned boolean Value indicating whether the submitter is banned
records List[Record] A list of records this submitter has submitted

Example objects

Short Form

{
  "banned": false,
  "id": 2
}

Long Form

{
  "banned": true,
  "id": 7,
  "records": [
    {
      "id": 1,
      "progress": 100,
      "demon": {
        "name": "Cadrega City",
        "position": 1
      },
      "status": "rejected",
      "player": {
        "name": "Aquatias",
        "id": 3424,
        "banned": false
      }
    }
  ]
}

Error objects

In case of a client or a (not completely fatal) server error, the API will provide an Error object with some information about what went wrong.

Although each HTTP response comes with a status code, you can still calculate the status code from the error code by performing integer division by 100

Field Type Description
message string A short message describing the error
code integer The error code
data object A JSON object containing additional data relevant to the error.

Example object

{
  "code": 42217,
  "data": {
    "existing": 13
  },
  "message": "This records has already been submitted"
}