Record listing

GET /records/

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.

Allows retrieving a list of records.

Only users with ExtendedAccess or higher permissions can see non-approved records. Only users with ListHelper or higher can see the anonymized submitter ID (for all other users, the submitter field of the record objects will be set to null).

Filtering

The result can be filtered by any of the following fields: id, progress, status (only possible for users with ExtendedAccess permissions), player, video, demon (for filtering demons by name), demon_position (for filtering demons by position), demon_id (for filtering demons by id) and submitter (only possible for users with ListModerator permissions). The fields progress and demon_position support inequality based filtering.

Pagination is done via the id field.

Request

Header Expected Value Optional
Authorization Pointercrate access token true

Response: 200 OK

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

Example request

GET /api/v1/records/
Accept: application/json

Submitting Records

POST /records/

Rate Limits:
This endpoint is ratelimited at 3 successfully submitted records per 20 minutes per submitter and 20 records per hour globally. Further there are only 5 new IP adresses allowed to make submissions per hour (this limit is only relevant for your first time submitting a record).

Access Restrictions:
Unless you set status to SUBMITTED (or omit the field), access to this endpoint requires at least LIST_HELPER permissions. The raw_footage field is required unless the submitter has at least LIST_HELPER permissions.

Either adds a record directly to the list, or submits a record to the list mods for approval. The record must meet the demons requirement, and the holder in question needn’t be banned.

The video value, if provided, must meet the requirements specified here.

Request:

Header Expected Value Optional
Content-Type application/json false
Field Type Description Optional
progress integer The records progress false
player string The name of the player holding the record false
demon integer The id of the demon the record is made on false
note string Submitter-written note for the record. true
video URL The video of the record true
raw_footage URL Raw footage of the record, can be any URL. Becomes one of the first notes of the record. true
status RecordStatus The status the newly record should have, defaults to SUBMITTED true

Response: 200 OK

Note how we do not use 201 CREATED here as the submission of the record is not guaranteed: Some validity checks are deferred and might result in the submission being auto-deleted after the 200 OK response was sent.

Header Value
Content-Type application/json
Location The location of the newly created record
ETag unsigned 64 bit hash of the newly created record
Field Type Description
data Record The newly created record object

Errors:

Status code Error code Description
403 40304 You have been banned from submitting records
403 40308 You are not authorized to submit a record for this player
404 40401 The provided demon does not exist
422 42218 The record holder is banned
422 42219 The demon is on the legacy list
422 42215 The record does not meet the demons requirement
422 42220 The demon is on the extended list but the record’s progress isn’t 100
422 42217 The record has already been approved/rejected/submitted/approved
422 42232 A record without raw footage was submitted
422 42233 Provided raw footage was not a valid URL

Example request:

POST /api/v1/records/
Accept: application/json
Content-Type: application/json

{
    "progress": 79,
    "player": "stadust",
    "demon": 70
}

Record retrieval

GET /records/ record_id /

Acces Restrictions:
If the requested record is not approved, access to this endpoint requires at least ExtendedAccess permissions.

Retrieves detailed information about the record with id record_id

Request

Header Expected Value Optional
Authorization Pointercrate access token false
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 record object
Field Type Description
data Record The requested record object

Response: 304 NOT MODIFIED

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

Header Value
ETag unsigned 64 bit hash of the record object

Errors:

Status code Error code Description
404 40401 No record with id record_id was found

Example request

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

Modifying a record

PATCH /records/ record_id /

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

Modifies a given record.

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 record object false
Field Type Description Optional
progress integer Set to update the progress true
video URL Set to update the video. Can be null true
status RecordStatus Set to update the record’s status true
player string Set to update the record holder. Needs to be the name of the player true
demon string Set to update the demon the record was made on. Needs to be the name of the demon true
demon_id integer Set to update the demon the record was made on. Needs to be the id of the demon. This field conflicts with demon. true

Response: 200 OK

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

Response: 304 NOT MODIFIED

Returned when the PATCH operation did not make any changes.

Header Value
ETag unsigned 64 bit hash of the record

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 record with id record_id was found
404 40401 The updated value for demon does not exist
412 41200 The value provided in the If-Match header doesn’t match the current state of the object
418 41800 No If-Match header was provided
422 42215 The updated progress value does not meet the demons requirement
422 42216 The update status value is not a valid member of the RecordStatus enum
422 42221 The record holder is banned and you tried to set the record status to APPROVED
422 42229 Your request body tries to simultaneously use mutually exclusive fields (e.g. demon_id together with demon)

Example request

PATCH /api/v1/records/2/
Accept: application/json
Authorization: Bearer <omitted>
Content-Type: application/json
If-Match: VV4v4HlCVToXCSqxdpaV3IQGRLw=

{
    "status": "approved",
}

Deleting a record

DELETE /records/ record_id /

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

Deletes the record with the given ID. This action is irreversible. Note that if you simply want to reject a submission, you should use PATCH /records/record_id/ and change its status to REJECTED to ensure it isn’t submitted again.

Request:

Header Expected Value Optional
Authorization Pointercrate access token false
If-Match Conditional request header. Needs to be set to the current etag value of the record object false

Response: 204 NO CONTENT

Nothing

Errors:

Status code Error code Description
404 40401 No record with id record_id was found
412 41200 The value provided in the If-Match header doesn’t match the current state of the object
418 41800 No If-Match header was provided

Example request:

DELETE /api/v1/records/1/
Accept: application/json
Authorization: Bearer <omitted>
If-Match: FmdyN2c4jElWBIOVzGOuFKJhgrE=