Skip to content

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.

RouteMax RequestsBackoff period
*50 / 10 seconds30 minutes

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

json
{
    "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

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

Error response fields

FieldTypeDescription
statusNumberHTTP status code
messageStringShort description of the error

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

TypePathFormats
Account Avatar/avatars/account_id/avatar_hash.pngPNG, JPEG, WebP, GIF
Track Artworks/tracks/artworks/track_id.jpgJPEG
Track Previews/tracks/previews/track_id.aacAAC, MP4