REST API
JSON API at /api/v1 covering the same features as this site, for a mobile app or other clients. Full markdown: /api/docs. Machine catalog: GET /api.
Authentication
Every /api/v1/… route except the catalog requires an API key. Create and revoke keys on Settings (admin login). The token is shown once.
Authorization: Bearer gmk_… X-Api-Key: gmk_…
Scopes: read for GET (analytics, library, lookups, review, status, settings). write for POST/PUT/DELETE (edits, review actions, jobs, settings, key management). A write key always includes read.
Shared query parameters
Analytics endpoints accept the same filters as the website:
range—7d,30d(default),90d,1y,all,customfrom/to— ISO dates whenrange=customq— artist / track / album search (names and aliases)take— list size (default 50, max 500 on most lists)
| Website | API | Scope |
|---|---|---|
| Overview | GET /api/v1/overview | read |
| Tops | GET /api/v1/tops/{artists|tracks|albums} | read |
| Genres | GET /api/v1/tags and GET /api/v1/tags/{name} | read |
| Audio | GET /api/v1/audio, pending + PUT audio-profile | read / write |
| Discovery | GET /api/v1/discovery | read |
| Patterns | GET /api/v1/patterns | read |
| Deep cuts | GET /api/v1/deep-cuts?n=10 | read |
| Sessions | GET /api/v1/sessions?gap=30 | read |
| Wrapped | GET /api/v1/wrapped/{year} and …/html | read |
| Artist / track | GET /api/v1/artists/{id}, GET /api/v1/tracks/{id} | read |
| Recent plays | GET /api/v1/scrobbles | read |
| Library | GET /api/v1/library, PUT /api/v1/library/{id} | read / write |
| Fetch MBID | POST /api/v1/tracks/{id}/enrich | write |
| Lookups | GET /api/v1/lookups, POST …/lookups/{id}/retry | read / write |
| Review | GET /api/v1/review, accept / not-found / retry | read / write |
| Progress | GET /api/v1/status | read |
| Jobs | POST /api/v1/jobs/{sync|backfill|pause|resume|retry-lookups|seed} | write |
| Settings | GET/PUT /api/v1/settings | read / write |
| API keys | GET/POST /api/v1/keys, DELETE /api/v1/keys/{id} | read / write |
Example
curl -H "Authorization: Bearer gmk_…" http://localhost:5107/api/v1/overview?range=30d curl -H "Authorization: Bearer gmk_…" http://localhost:5107/api/v1/me
JSON uses camelCase. Enums are strings. Errors look like {"error":"…"}. 401 missing/invalid key, 403 wrong scope, 404 unknown id.