Overview

Location

The API is available at https://api.bflist.io/.

Response metadata

By default, the API returns metadata such as pagination indicators (current page, elements per page, total pages etc.) in the response headers.

HTTP/1.1 200 OK
[...]
X-Page: 1
X-Per-Page: 50
X-Total-Items: 546
X-Total-Pages: 11

If you prefer to receive such metadata as part of the response body, send requests with include=metadata as part of the query string. With include=metadata set, the details will be added to the response body in addition to being added to the headers.

{
  "_metadata": {
    "asOf": "2022-08-10T15:14:08.267Z",
    "page": 1,
    "perPage": 50,
    "totalItems": 546,
    "totalPages": 11
  },
  "data": [
    // 50 servers
  ]
}

Note: If you request metadata to be included in the response body, all responses will be sent as JSON. Even simple properties such as a player's score (usually returned as plain text), will be returned as JSON with their usual data type.

{
    "_metadata": {
        "asOf": "2022-08-10T15:24:05.448Z"
    },
    "data": 52
}

Error messages

The API always returns a JSON array of errors. Even when requesting a plain text property such as /players/:name/score, you will receive a JSON response in case of an error.

{
    "errors": [
        "Player not found/not online"
    ]
}

You can force plain text errors by setting plainerr to 1 via a query parameter. For example: /players/:name/score?plainerr=1 will return any errors as plain text rather than JSON.