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.
Route | Max Requests | Backoff period |
---|---|---|
* | 50 / 10 seconds | 30 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
{
"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
Field | Type | Description |
---|---|---|
status | Number | HTTP status code |
message | String | Short 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
Type | Path | Formats |
---|---|---|
Account Avatar | /avatars/account_id/avatar_hash .png | PNG, JPEG, WebP, GIF |
Track Artworks | /tracks/artworks/track_id .jpg | JPEG |
Track Previews | /tracks/previews/track_id .aac | AAC, MP4 |