The pointercrate API

This is the documentation for the pointercrate API. If you dont know what an API is or have no idea how you even got to this page, this link takes you back to the demonlist.

The API can be used to retrieve data about the demonlist and interally is used to manage it. All endpoints described here are located under https://pointercrate.com/api/v1 unless a different api version is explicitly provided, in which case the v1 part of the URL needs to be amended.

It is always good practice to set the Accept header in requests to application/json (or at least give application/json a higher preference than text/html), so that in case of errors, you receive a JSON response instead of the HTML error page.

All HTTP traffic is automatically redirected to HTTPS. All urls without a trailing slash are automatically redirected to urls with one.

Errors:

These error conditions can occur at any endpoint and are thus not listed specifically for each of them. The errors with status code 500 INTERNAL SERVER ERROR should not occur and are only listed for completeness sake.

Status code Error code Description
400 40002 One of the headers was malformed and could not be parsed
415 41500 The HTTP method is not allowed for the requested URL
500 - Something so bad happened that apache had to serve the error page because pointercrate itself couldn't recover. If this happens you will not get a JSON response
500 50001 Server generated invalid error code
500 50002 The server encountered an error while dispatching an error
500 50003 Database misconfiguration error
500 50004 Unspecified internal server error
500 50005 Failure to connect to the database
503 50300 The requested endpoint is currently down for maintenance

Authentication

Basic

Endpoints involving access to your own account often require basic authentication instead of an access token (see below).

Errors:

These error conditions apply to any endpoint utilizing basic authentication and are thus not repeated for every one of them.

Status code Error code Description
401 40100 An invalid authentication method was used
401 40101 The password or username are incorrect

Access tokens

Pointercrate requires you to have a valid access token to issue requests to most endpoints. An access token for your account can be retrieved via successful call to the login endpoint.

Pointercrate access tokens are JSON Web Tokens and can be parsed by any standard compliant implementation.

Each access token is valid until you change your password, or is invalidated via a call to invalidate.

When an endpoint requires authentication via an access token, the Authorization header has to be set to the word Bearer followed by a space, followed by your access token.

Errors:

These error conditions can occur at any endpoint utilizing access tokens and are thus not listed specifically for each of them.

Status code Error code Description
401 40100 An invalid authentication method was used, or the token was invalid

Permissions

Different endpoints require different kinds of privileges to be used. A user's permissions are safed as a bitmask, and by default every user has absolutely no permissions.

A user can be granted permissions via PATCH /users/user_id/ by another user with ADMINISTRATOR permissions.

If an endpoints requires special permissions to be accessed, it's documentation will contain a notice similar to this one:

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

Available permissions:

Permission Bit Description
EXTENDED_ACCESS 0x1 Users that have access to additional data retrieval endpoints
LIST_HELPER 0x2 Users that help out in managing the demonlist by reviewing records
LIST_MODERATOR 0x4 Users that moderate the demonlist and manage the demon placements
LIST_ADMIN 0x8 Users that administrate the demonlist.
MODERATOR 0x10 Users that have access to the pointercrate user list
ADMINISTRATOR 0x20 Users that can manage other users, including granting them permissions

Errors:

These error conditions can occur at any endpoint expecting requiring specific access permissions and are thus not listed specifically for each of them.

Status code Error code Description
403 40301 You are missing required access permissions.

Pagination and Filtering

Some endpoints in the pointercrate API support or require pagination due to the potentially huge amount of data they can return. This mostly applies to the endpoints that return lists of objects, like GET /records/.

Objects returned by endpoints supporting pagination are totally ordered by an ID field, which is specified in the endpoint's documentation.

If an endpoint supports pagination, it's documentation will contain a notice similar to this one:

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

Pagination Query Parameters

Pagination is done via specific query parameters, which tell pointercrate which part of the result set to return.

Note that there is no way to get the total amount of pages, as both page bounds and size can be chosen abitrarily.

Query Parameter Description Default
limit The maximum amount of object to return. Must lie between 1 and 100 50
after The id of the last object on the previous page, thus specifying the start point of the current page The very first item in the result set
before The id of the first object on the next page, thus specifying the end point of the current page The very last item in the result set

Pagination Response Headers

Paginatable endpoints provide the Links header to simply access to the next, previous, first and last page, using the limit set on the request. The header is set to a comma-seperated list of links in the form <[link]>; rel=[page], where page is one of next, previous, first or last.

Note that links are only included when needed, meaning that there won't be a link with rel=next when on the last page (meaning on the page containing the last item in the result set).

Filtering

Some endpoints that support pagination also support filtering their results.

If this is supported, the documentation specifies the filterable fields for a given endpoint. It is then possible to specify conditions in the query string, which the returned objects must meet.

There are two ways of filtering the result set:

  • Filtering by equality: The objects returned can be filtered by a specific field's value by specifying the field and a comma seperated list of allowed values in the query string, i.e. /api/v1/records?id=1,54
  • Filtering by inequality: The objects returned can be filtered by whether a field is smaller/greater than a specific value by specifying the field, suffixed with either __lt or __gt, and the value to check for inequality against in the query string, i.e. /api/v1/records?id__gt=20

Multiple conditions can be combined, i.e. /api/v1/records?status=APPROVED&id__gt=200&id__lt=1000.

Errors:

These error conditions can occur at any endpoint supporting pagination and are thus not listed specifically for each of them.

Status code Error code Description
422 42207 The limit parameter is smaller than 1 or greater than 100
422 42208 The after parameter is greater than the before parameter
422 42209 The after parameter is smaller than 0

External Videos

Valid video formats

Pointercrate only accepts videos from a specific set of hosting services. It further normalizes all videos from a given host into one specific URL format and ensures that every video link actually leads to a valid video. All query parameters, including timestamps on youtube videos, are stripped from URLs.

The accepted URL formats are:

Video host URL formats
YouTube http[s]://www.youtube.com/watch?v={id}
YouTube http[s]://m.youtube.com/watch?v={id}
YouTube http[s]://youtu.be/{id}
Twitch http[s]://www.twitch.tv/videos/{id}
Twitch http[s]://www.twitch.tv/{name}/v/{id}
Everyplay http[s]://everyplay.com/videos/{id}
Vimeo http[s]://vimeo.com/{id}
Bilibili http[s]://www.bilibili.com/video/{id}

They are normalized into the following:

Video host URL format
YouTube https://www.youtube.com/watch?v={id}
Twitch https://www.twitch.tv/videos/{id}
Everyplay https://everyplay.com/videos/{id}
Vimeo https://vimeo.com/{id}
Bilibili https://www.bilibili.com/video/{id}

Errors:

These error conditions can occur at any endpoint expecting a video URL and are thus not listed specifically for each of them.

Status code Error code Description
400 40004 The video URL does not meet the above requirements
400 40005 The video URL has a malformed query string. This could, for example, be a trailing &t