Player listing

GET /players/

Pagination:
This endpoint supports pagination and filtering via query parameters. Please see the documentation on pagination for information on the additional request and response fields headers.

Access Restrictions:
Access to this endpoint requires at least EXTENDED_ACCESS permissions.

Allows to retrieve a potentially filtered list of all players having records on the list, or are associated with a demon in some other way.

Filtering:

The result can be filtered by any of the following fields: id, name, name_contains, banned and nation (both by country code and country name).

Pagination is done via the id field.

Request:

Header Expected Value Optional
Authorization Pointercrate access token false

Response: 200 OK

Header Value
Content-Type application/json
Field Type Description
- List[Player] A list of players

Example request:

GET /api/v1/players/
Accept: application/json
Authorization: Bearer <omitted>

Player ranking

GET /players/ranking/

Pagination:
This endpoint supports pagination and filtering via query parameters. Please see the documentation on pagination for information on the additional request and response fields headers.

This endpoint is used by the stats viewer. It is a more limited (and slower) version of /players/. It should only be used if the additional information (player scores and ranking) is actually required.

Additionally, the endpoint uses its own special format for Player objects, which is a modified version of the listed form.

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
rank integer The player’s rank. Multiple players can have the same rank, if they have the same score. The ranking is not dense, meaning multiple player having the same rank causes a hole in the ranking.
score double The player’s score

Filtering:

The result can be filtered by nation (which accepts both country code and country name), subdivision (which only accepts the subdivision code), continent (which only accepts continent name) and by name_contains, which causes the endpoint to only return players whose name contains the given substring.

Since none of the fields have the characteristics required of a pagination field (results aren’t sorted by id, score is a floating point value and rank is not unique), pagination is done via a pseudo-field that is not contained in the response.

Request:

Header Expected Value Optional
Authorization Pointercrate access token false

Response: 200 OK

Header Value
Content-Type application/json
Field Type Description
- List[RankedPlayer] A list of players (see above for the special format)

Example request:

GET /api/v1/players/ranking/
Accept: application/json
Authorization: Bearer <omitted>

Player retrieval.

GET /players/ player_id /

Retrieves detailed information about the player with id player_id

Request:

Header Expected Value Optional
If-Match Conditional request header. If the etag value of the requested data matches any of the here provided values, the data is returned as requested. Otherwise a 412 PRECONDITION FAILED response is generated true
If-None-Match Conditional request header. If the etag value of the requested data does not match any of the here provided values, if it returned as requested. Otherwise, a 304 NOT MODIFED response is generated true

Response: 200 OK

Header Value
Content-Type application/json
ETag unsigned 64 bit hash of the player object
Field Type Description
data Player The requested player object

Response: 304 NOT MODIFIED

Returned if the If-None-Match header is set, and the etag for the player object matches one of the set values.

Header Value
ETag unsigned 64 bit hash of the player object

Errors:

Status code Error code Description
404 40401 No player with id player_id was found

Example request:

GET /api/v1/players/1/
Accept: application/json

Modifying a player

PATCH /players/ player_id /

Access Restrictions:
Access to this endpoint requires at least ListModerator permissions.

Modifies a given player.

Banning a player will hide, but not delete their records from the list. After he has been unbanned, they can be readded.

Renaming a player to the name of an already existing player will merge all their records. If the two players have a record on the same demon, the record will the higher progress will take precedence.

Request:

Header Expected Value Optional
Content-Type application/json false
Authorization Pointercrate access token false
If-Match Conditional request header. Needs to be set to the current etag value of the player object false
Field Type Description Optional
name string Set to update the player’s name true
banned boolean Set to update the player’s banned status true
nationality string Set to update the player’s nationality. Can be either the nation’s name, or its ISO countrycode true
subdivision string Set to update the player’s political subdivision true

Response: 200 OK

Header Value
Content-Type application/json
ETag unsigned 64 bit hash of the updated player
Field Type Description
data Player The updated player object

Response: 304 NOT MODIFIED

Returned when the PATCH operation did not make any changes.

Header Value
ETag unsigned 64 bit hash of the player

Errors:

Status code Error code Description
400 40003 Invalid data type for requested field
403 40302 The requested field cannot be updated via this endpoint
404 40401 No player with id player_id was found, or the specified nationality or subdivision wasn’t recognized
409 40907 A political subdivision was provided, but no nationality set

Example request:

PATCH /api/v1/players/1/
Accept: application/json
Authorization: Bearer <omitted>
Content-Type: application/json
If-Match: FfbtbML27VL1ciOI1Ar0mX20Yhc=

{
    "banned": true,
    "nationality": "US",
    "subdivision": "OH"
}