Introduction ​

This is the official documentation of the atomic.radio API. Our API is a RESTful API and uses the JSON data format for all responses. We will document in our documentation only all public routers of our API and very few restricted routers. Our API consists of two layers, the RESTful API and our persistent WebSocket connection between client and API to update data at the client in real time.

Base URL ​

https://api.atomic.radio

https://api.atomic.radio

Authentication ​

Authentication is done via the Authorization HTTP header. The token for authentication can currently only be obtained from local storage when logged in to our site. The token is stored in the local storage under the key session and is divided by a semicolon into two parts: access_token, refresh_token. Only the access_token is needed for authentication.

Example Authorization Header ​

Authorization: Bearer <access_token>

Authorization: Bearer <access_token>

Rate Limiting ​

All requests that reach our API regardless of whether authenticated or not must respect our rate limits. If the limit is exceeded we will abort the request with the status code 429 Too Many Requests. These rate limits are in place to help prevent the abuse of our services.

Pagination ​

We have routers that return lists with more than 1000 elements as response, these support pagination to modify the number of elements as required. These responses with pagination support follow a single structure throughout the API.

Structure response with pagination ​

{
    "results": Array,
    "pagination": {
        "page": Number,
        "limit": Number,
        "total_pages": Number,
        "total_entries": Number
    }
}

{
    "results": Array,
    "pagination": {
        "page": Number,
        "limit": Number,
        "total_pages": Number,
        "total_entries": Number
    }
}

Errors ​

If a request to the API is interrupted by an error, the API returns a response with the error message and the associated status code. These answers with pagination support follow a single structure throughout the API.

Example error response ​

{
    "status": 404,
    "message": "Unknown track"
}

{
    "status": 404,
    "message": "Unknown track"
}

Error response fields ​

CDN ​

For our CDN we rely on Cloudflare which allows us to quickly provide data to all users no matter where they are. Many files are offered in different formats and images can be adjusted directly via certain query parameters of height, width and format.

CDN Base Url ​

https://assets.atomic.radio

https://assets.atomic.radio

Endpoints ​