API overview

Aurral has two HTTP APIs:

• The JSON API under /api. The web app uses it. You can also use it for scripts, dashboards, and homepage widgets.
• The Subsonic API under /rest. Music players use it.

GET /api/health/bootstrap reports api.version and api.features without sign-in. Version 1 keeps the app API contract stable. A breaking contract change increments the version. New optional fields and capabilities are additive, so clients ignore unknown fields and check the feature list before using a capability. appVersion identifies the build, not API compatibility.

Authenticate with the API key

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

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

Aurral also accepts the key in the api_key query parameter:

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

Use the header when you can. Browsers keep URLs in their history, and reverse proxies write them to access logs.

With the API key, you do not need to sign in first. The key gives administrator access. It has no read-only mode.

The key belongs to the Aurral installation, not to a user. For actions on user data, use a user’s sign-in session instead. These actions include linking Last.fm, ListenBrainz, or Koito, recording plays, and changing favorites. When the API key calls one of them, Aurral returns 403.

Keep the key in a secret store. If an integration only needs to read, send only GET requests. To replace the key, select Rotate API key in Settings > System. The old key stops working at once.

Do not put the key in public browser JavaScript. Call Aurral from a server-side widget or a same-origin proxy instead.

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 from 1 to 10000, and offset
GET /api/library/artists/:mbid	One library artist	MusicBrainz artist ID in the path
GET /api/library/canonical	One page of Library items	Required kind, and pageSize from 1 to 100. Optional source, availableOnly, page, query, genre, sort, direction, artistId, and albumId.
GET /api/library/favorites	The current user’s favorites	None
GET /api/library/albums	The albums of an artist	Required artistId
GET /api/library/albums/:id	One library album	Lidarr album ID in the path
GET /api/library/tracks	The tracks of an album	albumId or releaseGroupMbid
GET /api/library/recent	The 20 artists with the newest library files	None
GET /api/library/recent-releases	Recent and upcoming releases that are not in the Library	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 a request without a supported kind and a pageSize. Send separate requests for artists, albums, tracks, and genres.

For every route, see the endpoint reference.

Example homepage request

This request gets five library 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

By default, Aurral does not allow browser requests to the JSON API from another origin. To allow them, set CORS_ORIGIN to a comma-separated list of origins.

The CORS preflight allows the Content-Type and Authorization headers. It does not allow X-Api-Key. For a browser widget on another origin, use a server-side proxy. The api_key query parameter needs no custom header, but browser history and access logs can expose the key.

Browser Subsonic clients such as Feishin can use /rest without CORS_ORIGIN.

Responses and limits

• A successful request returns a JSON object or array.
• An error returns JSON with an error field. Some errors also have a message or code field.
• Missing or invalid authentication returns 401.
• A valid account without the needed permission returns 403.
• The API key calling a user-only action returns 403.
• Each client can send 5,000 API requests in each 15-minute period.
• Sign-in routes accept 10 attempts in each 15-minute period.

Subsonic authentication

The Subsonic API at /rest uses Aurral user accounts, not the API key. It supports both Subsonic sign-in methods:

• Password authentication sends the username and password. Clients often call it legacy authentication.
• Token authentication sends a salted token made from the password.

Token authentication needs a password that Aurral stored for Subsonic. When it fails, Aurral returns error 41, Token authentication failed, with a link to this section. To fix it:

1. Turn on password authentication in the client. In Music Assistant, turn on legacy authentication. In Feishin, set LEGACY_AUTHENTICATION=true.
2. Or make sure that the account has a local password. An account created before Aurral stored Subsonic credentials needs one Aurral sign-in. An account created by OIDC or a reverse proxy needs an admin to set a password.

A wrong username or password returns error 40.

See Navidrome and Subsonic for the supported client features.