Skip to content
AurralAurral

API overview

Aurral provides a JSON HTTP API. The web interface uses this API. You can also use the API for scripts, dashboards, and homepage widgets.

The JSON API and the authenticated Subsonic API are separate interfaces. Use the JSON API for Aurral-specific automation. Use /rest for a Subsonic player or client.

Authentication

Section titled “Authentication”

Open Settings > System. Copy the API key. Send the key in the X-Api-Key header:

Terminal window
curl --fail \
  --header "X-Api-Key: YOUR_API_KEY" \
  https://aurral.example.com/api/library/artists

Aurral also accepts the api_key query parameter:

Terminal window
curl --fail \
  "https://aurral.example.com/api/library/recent?api_key=YOUR_API_KEY"

Use the header. A browser can save URLs in its history. A reverse proxy can save URLs in its access logs.

The API key replaces a login session token. You do not need to call the login endpoint first. The key currently gives administrator access. It does not have read-only access.

The API key identifies the Aurral installation, not a user account. Use a user’s login session for operations that create or update user-owned data, such as Last.fm, ListenBrainz, or Koito account linking, local play events, and library favorites. Aurral returns 403 when an API key calls one of these operations.

Keep the key in a secret store. If your integration needs read access, make only GET requests. After you rotate the key, the old key does not operate.

Do not put the key in public browser JavaScript. A server-side widget or same-origin proxy keeps it out of visitors’ browsers.

Useful read endpoints

Section titled “Useful read endpoints”
Endpoint Purpose Parameters
GET /api/health/live Minimal liveness check None
GET /api/health Aurral, library, discovery, and system status None
GET /api/library/artists Library artists limit (1-10000), offset
GET /api/library/artists/:mbid One library artist MusicBrainz artist ID in the path
GET /api/library/canonical A bounded canonical page Required kind and pageSize (1-100). Optional source, availableOnly, page, query, genre, sort, direction, artistId, or albumId.
GET /api/library/favorites Current user’s favorites and library None
GET /api/library/albums Albums for an artist Required artistId
GET /api/library/albums/:id One library album Lidarr album ID in the path
GET /api/library/tracks Tracks for an album albumId or releaseGroupMbid
GET /api/library/recent 20 most recently added artists None
GET /api/library/recent-releases Recent missing releases None
GET /api/requests Current artist and album requests Optional refresh=true
GET /api/library/downloads/status/all All current download states None
GET /api/search Search artists, albums, or tags Required q. Optional scope, limit, and offset

GET /api/library/canonical rejects requests without a supported kind and a bounded pageSize. Use separate requests for artists, albums, tracks, or genres.

See the endpoint reference for the complete current route index.

Example homepage request

Section titled “Example homepage request”

This request gets five recently added artists. The key stays on the server:

const response = await fetch(`${process.env.AURRAL_URL}/api/library/artists?limit=5`, {
  headers: { "X-Api-Key": process.env.AURRAL_API_KEY },
});


if (!response.ok) throw new Error(`Aurral returned ${response.status}`);
const artists = await response.json();

Cross-origin requests

Section titled “Cross-origin requests”

If a browser loads Aurral’s JSON API from another origin, set CORS_ORIGIN. Use commas to separate each permitted origin. By default, Aurral does not permit cross-origin JSON API requests. The authenticated Subsonic API at /rest is available to browser Subsonic clients such as Feishin without this setting.

The current CORS preflight allows the Content-Type and Authorization headers. It does not allow the X-Api-Key header. For a cross-origin browser widget, use a server-side proxy. When you use the api_key query parameter, you do not need a custom header. However, browser history and access logs can reveal the key.

Responses and limits

Section titled “Responses and limits”
  • For a successful request, the route returns a JSON object or array.
  • For an error, the route returns JSON with an error field. Some errors also have a message or code field.
  • If authentication is invalid or not present, Aurral returns 401.
  • If a valid account does not have the necessary permission, Aurral returns 403.
  • If an instance API key calls an operation that needs a user account, Aurral returns 403.
  • Aurral limits each client to 5,000 API requests in each 15-minute period.
  • The API key does not have a separate permission or read-only scope.

The API key gives access to administration routes and routes that change data. Before you give the key to a third-party integration, read the endpoint reference. The API key is not a Subsonic credential; Subsonic clients use the account password or token authentication described in the integration guide.