The API is currently in beta and subject to change. FMDB is a non-commercial,
privacy-first platform.
Base URL
All endpoints are served from the production host:Authentication
Authentication is required for all endpoints unless stated otherwise. The API uses bearer tokens.Obtaining an access token
1
Register an account
Sign up at www.fmdb.net. API access uses the same
account as the website.
2
Open your settings
Once signed in, go to your account settings and find the
API Access Tokens section.
3
Create a token
Generate a token there and store it somewhere safe — treat it like a
password.
Using the token
Send the token in theAuthorization header on every request:
401 and a
WWW-Authenticate: Bearer challenge; a credential the API rejects is answered
the same way with an RFC 6750 error code.
Rate limits
Every request under/api is counted against a quota.
Several policies are in force at once, each a sliding window, and a request has
to fit all of them. Reads are the safe methods (GET, HEAD); everything that
changes data counts as a write.
Reads are counted per tier:
Writes are the same on both tiers:
The budget belongs to your account and the tier of the credential you are using,
not to the credential itself — issuing a second token does not give you a second
budget. Every credential starts on the standard tier. Elevated access is granted
by FMDB for an approved application; there is no way to raise your own tier.
Reading the headers
Every response reports the quota with the standardizedRateLimit fields, so
you never have to guess which window you are close to:
RateLimit-Policy names each policy in force with the requests it grants (q)
over its window in seconds (w). RateLimit reports what is left of each
(r) and in how many seconds it admits another request (t).
These fields replace the earlier
X-RateLimit-Limit, X-RateLimit-Remaining
and X-RateLimit-Reset headers, which are no longer sent.When you exceed a quota
The request is refused with429 Too Many Requests, a Retry-After header
giving the seconds to wait, and a JSON:API error document naming the quota that
refused it:
Retry-After rather than retrying immediately.
The OAuth endpoints are throttled separately, per client and per address: a
refused token or revocation request answers 429 with Retry-After and the
OAuth error code slow_down instead of a JSON:API document.
Content type
The API follows the JSON:API conventions. Requests and responses use theapplication/vnd.api+json media type.
What you can access
Catalog
Releases, release formats, tracks, recordings, and packaging types.
Productions
Films and other productions, their entries and recordings.
People and companies
Artists, aliases, group memberships, roles, labels, and organizations.
Your account
Personal collection and wishlist items.