API Reference

The Diskograf API serves the catalogue at https://api.diskograf.com. It is public, read-only, and needs no authentication.

Base URL

https://api.diskograf.com/v1

Response envelope

Every successful response is wrapped. List endpoints return a meta object alongside the data:

{
  "data": [{ "id": 1, "title": "Hujan" }],
  "meta": { "total": 1234, "limit": 20, "offset": 0 }
}

Detail endpoints return data alone:

{ "data": { "id": 1, "title": "Hujan" } }

Errors carry a code and a human-readable message:

{ "error": { "code": "not_found", "message": "Song not found." } }

There are three codes: not_found, bad_request and internal_error.

Pagination

List endpoints accept limit and offset. The default limit is 20 and the maximum is 80. meta.total counts every matching row, not just the current page.

Rate limits

Requests are limited to 60 per 60 seconds, per IP address. A request over the limit is rejected. No API key is required today; the envelope is shaped so keys can be introduced later without breaking existing clients.

Caching

Responses are cached at the edge and in the browser. The catalogue changes slowly, so a response may be up to five minutes old.

Stability

The response envelope and route shapes are what third parties build against. Fields are added, never removed or renamed, within a version.