The pointercrate API

This is the documentation for the pointercrate application programming interface (short: 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. If you rather want to read source code of the implementation directly, head over to the github repository instead. It also contains the markdown files these documentation pages are generated from, so if you find any error here feel free to submit a pull request!

The API can be used to retrieve data about the demonlist and is internally 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. Currently, there are only a few endpoints using a v2 scheme.

It is always good practice setting 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 requests to URLs without a trailing slash are automatically redirected to URLs with one.

Errors

In case of a client or server error, the API returns an error response. Errors that are specific to a given endpoint are always listed in that endpoint’s documentation. Following is an exhaustive list of errors that can occur at any endpoint in the API. Note that the errors with status code 500 INTERNAL SERVER ERROR should (obviously) not occur and are only listed for completeness sake. An complete list of all errors can be found at the bottom on this page.

In the case that you do not receive any response at all, or receive an Apache/Nginx error page you can assume that the pointercrate server crashed and couldn’t recover. If this is the case all hope is lost.

409 versus 412

The cases in which a 409 CONFLICT error or a 412 PRECONDITION FAILED error is returned are very similar. In fact, handling for both errors should probably be identical.

Both cases need to be handled the same way: re-GET the object to retrieve its updated ETag and retry the request.

Authentication

Basic

Some endpoints in the API require HTTP Basic Authentication. Since all communication is enforced via HTTPS, this is OK.

Access tokens

Pointercrate requires a valid access token for most endpoints. Tokens are JSON Web Tokens and are retrieved via the login endpoint.

When required, set the Authorization header to: Bearer <access token>.

Cookies

Authentication via cookies is theoretically possible but not usable for API access. Attempts will result in a 401 UNAUTHORIZED.

Permissions

Different endpoints require different permissions. Permissions are stored as a bitmask, and higher permissions imply lower ones transitively.

Pagination and Filtering

Some endpoints support pagination due to large result sets. Pagination is handled via query parameters such as limit, after, and before.

Pagination Query Parameters

Filtering

• Equality filtering via ?field=value
• Inequality filtering via __lt or __gt
• Infix filtering via _contains

Example: /api/v1/records/?after=200&limit=10&status=APPROVED&progress__lt=100

External Videos

Pointercrate accepts videos from specific hosts and normalizes URLs into a single format per host.

Accepted Video Hosts

List of Errors

The API aims to provide detailed errors wherever possible. Generic errors should be rare. Suggestions for better error communication are welcome via GitHub issues.