{ "openapi": "3.1.0", "info": { "title": "SonoVault API", "version": "1.0.0", "description": "Music metadata API — search tracks, resolve ISRCs and cross-platform IDs, and browse artists, labels, and releases. This spec is generated from the SonoVault docs source of truth; the rendered docs at https://sonovault.now/docs are authoritative if anything diverges." }, "servers": [ { "url": "https://api.sonovault.now" } ], "tags": [ { "name": "Tracks" }, { "name": "Artists" }, { "name": "Labels" }, { "name": "Releases" }, { "name": "Genres" }, { "name": "Suggestions" }, { "name": "Streams" }, { "name": "Webhooks" } ], "security": [ { "ApiKeyAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your SonoVault API key. Get one at https://sonovault.now." } } }, "paths": { "/v1/tracks/search": { "get": { "operationId": "track-search", "summary": "Track search", "description": "Search for tracks by artist and title. Returns ISRC, genre, release dates, and full metadata.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "isrc": { "type": "string" }, "duration": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 123, "title": "One More Time", "releases": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "isrc": "GBDUW0000053", "duration": 320, "genre": [ "House" ], "subgenre": [ "French House" ] } ], "next_cursor": "eyJpZCI6MTIzfQ" } } } } }, "parameters": [ { "name": "artist", "in": "query", "required": true, "description": "Artist name.", "schema": { "type": "string" } }, { "name": "title", "in": "query", "required": true, "description": "Track title.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/tracks/isrc/{isrc}": { "get": { "operationId": "isrc-lookup", "summary": "ISRC lookup", "description": "Exact lookup by ISRC code. The ISRC is part of the path — there is no query string. Returns full track detail including genre and subgenre.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "isrc": { "type": "string" }, "duration": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } }, "example": { "id": 123, "title": "One More Time", "releases": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "isrc": "GBDUW0000053", "duration": 320, "genre": [ "House" ], "subgenre": [ "French House" ] } } } } }, "parameters": [ { "name": "isrc", "in": "path", "required": true, "description": "ISRC code (e.g. GBDUW0000053).", "schema": { "type": "string" } } ] } }, "/v1/tracks/iswc": { "get": { "operationId": "iswc-lookup", "summary": "ISWC lookup", "description": "Find the ISWC(s) — the work/composition codes — for a recording, by ISRC or SonoVault track ID. Provide exactly one of isrc or id. A recording can carry several ISWCs (medleys, samples). ISWCs are sourced from the MLC and are not part of the standard track payload.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "sonovault_id": { "type": "integer" }, "isrc": { "type": "string" }, "iswcs": { "type": "array", "items": { "type": "object", "properties": { "iswc": { "type": "string" }, "title": { "type": "string" } } } } } }, "example": { "sonovault_id": 123, "isrc": "GBDUW0000059", "iswcs": [ { "iswc": "T0701427997", "title": "HARDER BETTER FASTER STRONGER" } ] } } } } }, "parameters": [ { "name": "isrc", "in": "query", "required": false, "description": "ISRC of the recording. Provide this or id.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "SonoVault track ID. Provide this or isrc.", "schema": { "type": "integer" } } ] } }, "/v1/tracks/iswc/{iswc}": { "get": { "operationId": "tracks-by-iswc", "summary": "Recordings by ISWC", "description": "Reverse lookup: every recording of a composition, by ISWC. The ISWC is part of the path; human-readable separators (T-070142799-7) are accepted. Recordings are returned most-popular-first, each with a representative ISRC; total is the full count even when limit truncates the page.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "iswc": { "type": "string" }, "title": { "type": "string" }, "total": { "type": "integer" }, "recordings": { "type": "array", "items": { "type": "object", "properties": { "sonovault_id": { "type": "integer" }, "isrc": { "type": "string" }, "title": { "type": "string" }, "artist": { "type": "string" } } } } } }, "example": { "iswc": "T0701427997", "title": "HARDER BETTER FASTER STRONGER", "total": 2, "recordings": [ { "sonovault_id": 123, "isrc": "GBDUW0000059", "title": "Harder Better Faster Stronger", "artist": "Daft Punk" }, { "sonovault_id": 456, "isrc": "GBDUW0000182", "title": "Harder Better Faster Stronger - Radio Edit", "artist": "Daft Punk" } ] } } } } }, "parameters": [ { "name": "iswc", "in": "path", "required": true, "description": "ISWC code (e.g. T0701427997).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max recordings, 1–200. Default 50.", "schema": { "type": "integer" } } ] } }, "/v1/tracks/{id}": { "get": { "operationId": "track-by-id", "summary": "Track by ID", "description": "Get a single track by its internal SonoVault track ID. Returns the same track payload as ISRC lookup — title, artists, releases, ISRC, duration, genre, and subgenre.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "isrc": { "type": "string" }, "duration": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } }, "example": { "id": 123, "title": "One More Time", "releases": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "isrc": "GBDUW0000053", "duration": 320, "genre": [ "House" ], "subgenre": [ "French House" ] } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Internal SonoVault track ID.", "schema": { "type": "integer" } } ] } }, "/v1/tracks/links": { "get": { "operationId": "platform-links", "summary": "Platform links", "description": "Lightweight cross-platform ID resolver. Given an ISRC or a source-specific ID, returns all known external platform links.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "track_id": { "type": "integer" }, "title": { "type": "string" }, "isrc": { "type": "string" }, "links": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "external_id": { "type": "string" }, "url": { "type": "string" } } } } } }, "example": { "track_id": 123, "title": "One More Time", "isrc": "GBDUW0000053", "links": [ { "source": "spotify", "external_id": "5sICkBXVmaCQk5aISGR3x0", "url": "https://open.spotify.com/track/5sICkBXVmaCQk5aISGR3x0" }, { "source": "beatport", "external_id": "12345678", "url": "https://www.beatport.com/track/-/12345678" }, { "source": "applemusic", "external_id": "1440650", "url": "https://music.apple.com/song/1440650" }, { "source": "tidal", "external_id": "3789025", "url": "https://tidal.com/browse/track/3789025" }, { "source": "youtube", "external_id": "dQw4w9WgXcQ", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } ] } } } } }, "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Internal SonoVault track ID. Provide one lookup param at a time.", "schema": { "type": "integer" } }, { "name": "isrc", "in": "query", "required": false, "description": "ISRC code.", "schema": { "type": "string" } }, { "name": "spotify_id", "in": "query", "required": false, "description": "Spotify track ID.", "schema": { "type": "string" } }, { "name": "beatport_id", "in": "query", "required": false, "description": "Beatport track ID.", "schema": { "type": "string" } }, { "name": "discogs_id", "in": "query", "required": false, "description": "Discogs release ID.", "schema": { "type": "string" } }, { "name": "musicbrainz_id", "in": "query", "required": false, "description": "MusicBrainz recording ID.", "schema": { "type": "string" } }, { "name": "applemusic_id", "in": "query", "required": false, "description": "Apple Music track ID.", "schema": { "type": "string" } }, { "name": "tidal_id", "in": "query", "required": false, "description": "Tidal track ID.", "schema": { "type": "string" } }, { "name": "youtube_id", "in": "query", "required": false, "description": "YouTube video ID (11-char watch?v= id).", "schema": { "type": "string" } } ] } }, "/v1/tracks/resolve": { "post": { "operationId": "bulk-resolve", "summary": "Bulk resolve", "description": "Resolve up to 100 inputs in a single request — track names, ISRCs, or platform IDs — to canonical SonoVault tracks plus their cross-platform links. One credit is charged per input line. If your monthly quota runs out mid-batch the response is partial: unresolved lines come back with status `skipped_no_credits` instead of an error.\n\n**Response**\n\n- `results` — one entry per input line, in input order: `{ input, status, track, links }`, where `status` is `matched`, `not_found`, or `skipped_no_credits`.\n\n- `partial`, `processed`, `credits_used`, `credits_remaining`, `message` — the batch billing summary.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "status": { "type": "string" }, "track": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "isrc": { "type": "string" }, "duration": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } }, "links": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "external_id": { "type": "string" }, "url": { "type": "string" } } } } } } }, "partial": { "type": "boolean" }, "processed": { "type": "integer" }, "credits_used": { "type": "integer" }, "credits_remaining": { "type": "integer" }, "message": {} } }, "example": { "results": [ { "input": "GBDUW0000053", "status": "matched", "track": { "id": 123, "title": "One More Time", "releases": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "isrc": "GBDUW0000053", "duration": 320, "genre": [ "House" ], "subgenre": [ "French House" ] }, "links": [ { "source": "spotify", "external_id": "5sICkBXVmaCQk5aISGR3x0", "url": "https://open.spotify.com/track/5sICkBXVmaCQk5aISGR3x0" } ] }, { "input": "USQX91300108", "status": "not_found", "track": null, "links": [] } ], "partial": false, "processed": 2, "credits_used": 2, "credits_remaining": 968, "message": null } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input_type": { "type": "string", "description": "one of `track_name`, `isrc`, `sonovault_id`, `spotify_id`, `applemusic_id`, `tidal_id`, `beatport_id`, `discogs_id`, `musicbrainz_id`." }, "items": { "type": "string", "description": "1 to 100 entries. For `track_name`, each entry is an object `{ artist, title }`; for every other input type, each entry is a string." } }, "required": [ "input_type", "items" ] } } } } } }, "/v1/tracks/identify": { "post": { "operationId": "track-identify", "summary": "Identify (audio recognition)", "description": "Recognise a track from audio. Send a Chromaprint fingerprint (run `fpcalc -raw` client-side) — or the raw audio file and we fingerprint it for you — and get back the best-matching catalog tracks, ranked, each with a confidence score. A fingerprint costs 10 credits; raw audio costs 10 + ceil(MB). A request that would cost more credits than you have left this month is refused with a 429 before any matching runs. Paid plans only.\n\n**Requires a paid plan** — the free tier returns `403` for this endpoint.\n\n**Alternative — upload raw audio (no fpcalc needed)**\n\n- Alternatively send the file itself: `Content-Type: application/octet-stream` (or `audio/*`) with the raw bytes as the body, up to 100 MB. Any ffmpeg-decodable format works — mp3, flac, wav, m4a, mp4, ogg, opus, … (the format is detected from the content).\n\n- Optional `?length=&top_n=` query params. We analyse a ~30 s window at a time and automatically scan deeper into your audio on a miss.\n\n- Cost: **10 + ceil(MB)** credits (recognition + a per-MB surcharge). Prefer the fingerprint path when you can.\n\n**How much audio to send, cost & retries**\n\n- **Send the whole track (or a generous section), not a short clip.** The part that matches our catalog reference can sit anywhere — often the main hook a few minutes in, not the intro — so a snippet from the wrong section misses the match even though the track is in the catalog. ~10 s is the minimum; more audio is more reliable.\n\n- You're billed on the **bytes you upload** (10 + ceil(MB)), so a full ~4-min track is ~15–20 credits. To keep that small with no loss of accuracy, **downsample to mono 11025 Hz** (Chromaprint's native rate) before sending — about a quarter the size of the source. Trimming to a few seconds is cheaper but risks a miss.\n\n- On a miss, the **upload path automatically scans deeper windows** of your audio and votes across them before returning no match. On the **fingerprint path**, fingerprint a longer span (e.g. `fpcalc -length 0` for the whole file) or retry from a different part of the track.\n\n**Response**\n\n- `matched` (boolean) and `results` — the matching catalog tracks, best match first. Each result is slim: `id`, `title`, `artists`, and `confidence` (a 0–1 score; higher means a more certain match).\n\n- Need ISRC, genre, release info, or cross-platform links? Look the track up by `id` with `GET /v1/tracks/:id` (or `/v1/tracks/links`) — identify keeps its response small on purpose.\n\n- `credits_charged` — credits billed for this call.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "matched": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "confidence": { "type": "number" } } } }, "credits_charged": { "type": "integer" } } }, "example": { "matched": true, "results": [ { "id": 123, "title": "Strobe", "artists": [ { "id": 1, "name": "deadmau5", "is_primary": true, "is_remixer": false } ], "confidence": 0.98 } ], "credits_charged": 10 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fingerprint": { "type": "string", "description": "50–50000 integers from `fpcalc -raw` (Chromaprint), run client-side. ~1 KB upload. Costs 10 credits." }, "fingerprint_duration": { "type": "number", "description": "clip duration in seconds." }, "top_n": { "type": "integer", "description": "max results to return, 1–25." } }, "required": [ "fingerprint" ] } } } }, "x-paid-plan": true } }, "/v1/artists/search": { "get": { "operationId": "artist-search", "summary": "Artist search", "description": "Search for artists by name. Returns each artist with country, formation year (and full formation date when day-level precision is known), social links, and Wikidata ID where available.", "tags": [ "Artists" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "country": { "type": "string" }, "formation_year": { "type": "integer" }, "formation_date": {}, "social_links": { "type": "object", "properties": { "website": { "type": "string" }, "twitter": { "type": "string" }, "instagram": { "type": "string" }, "facebook": { "type": "string" } } }, "wikidata_id": { "type": "string" } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 1, "name": "Daft Punk", "country": "France", "formation_year": 1993, "formation_date": null, "social_links": { "website": "https://daftpunk.com/", "twitter": "daftpunk_music", "instagram": "daftpunk", "facebook": "100044021024570" }, "wikidata_id": "Q185828" } ], "next_cursor": "0:5000000:1" } } } } }, "parameters": [ { "name": "name", "in": "query", "required": true, "description": "Artist name to search.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/artists/{id}": { "get": { "operationId": "artist-by-id", "summary": "Artist by ID", "description": "Get artist by ID. Returns the public artist fields (country, formation_year + optional formation_date, social_links, wikidata_id) flattened alongside a release_count summary. For the actual release list, use /v1/artists/:id/releases — the embedded array was removed because it became huge for prolific artists.", "tags": [ "Artists" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "country": { "type": "string" }, "formation_year": { "type": "integer" }, "formation_date": {}, "social_links": { "type": "object", "properties": { "website": { "type": "string" }, "twitter": { "type": "string" }, "instagram": { "type": "string" }, "facebook": { "type": "string" } } }, "wikidata_id": { "type": "string" }, "release_count": { "type": "integer" } } }, "example": { "id": 1, "name": "Daft Punk", "country": "France", "formation_year": 1993, "formation_date": null, "social_links": { "website": "https://daftpunk.com/", "twitter": "daftpunk_music", "instagram": "daftpunk", "facebook": "100044021024570" }, "wikidata_id": "Q185828", "release_count": 14 } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Artist ID.", "schema": { "type": "integer" } } ] } }, "/v1/artists/{id}/releases": { "get": { "operationId": "artist-releases", "summary": "Releases by artist", "description": "Paginated feed of releases by a specific artist, ordered by release date (newest first). The per-item artist field is omitted (the caller already knows it).", "tags": [ "Releases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" }, "catalog_no": { "type": "string" }, "track_count": { "type": "integer" } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 1, "title": "Discovery", "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12", "catalog_no": "724384960650", "track_count": 14 } ], "next_cursor": "2001-03-12:1" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Artist ID.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/labels/search": { "get": { "operationId": "label-search", "summary": "Label search", "description": "Search for record labels by name. Returns labels sorted by relevance and release count.", "tags": [ "Labels" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "release_count": { "type": "integer" } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 1, "name": "Drumcode", "release_count": 842 } ], "next_cursor": "0:842:1" } } } } }, "parameters": [ { "name": "name", "in": "query", "required": true, "description": "Label name to search.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/labels/{id}": { "get": { "operationId": "label-by-id", "summary": "Label by ID", "description": "Get label by ID. Returns the public label fields (id, name) flattened alongside release_count and artist_count summaries. For the actual lists, use /v1/labels/:id/releases and /v1/labels/:id/artists — embedded arrays were removed because they became huge for prolific labels.", "tags": [ "Labels" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "release_count": { "type": "integer" }, "artist_count": { "type": "integer" } } }, "example": { "id": 1, "name": "Drumcode", "release_count": 842, "artist_count": 67 } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Label ID.", "schema": { "type": "integer" } } ] } }, "/v1/labels/{id}/releases": { "get": { "operationId": "label-releases", "summary": "Releases by label", "description": "Paginated feed of releases on a specific label, ordered by release date (newest first). Each result carries the primary artist, label, catalog number, and track count.", "tags": [ "Releases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" }, "catalog_no": { "type": "string" }, "track_count": { "type": "integer" } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 10, "title": "Drumcode 01", "artist": { "id": 5, "name": "Adam Beyer" }, "label": { "id": 1, "name": "Drumcode" }, "release_date": "2024-03-15", "catalog_no": "DC001", "track_count": 8 } ], "next_cursor": "2024-03-15:10" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Label ID.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/labels/{id}/artists": { "get": { "operationId": "label-artists", "summary": "Artists by label", "description": "Paginated list of artists with releases on a specific label, ordered by number of releases on that label (descending). Each artist carries the public profile fields and a release_count scoped to this label.", "tags": [ "Artists" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "country": { "type": "string" }, "formation_year": { "type": "integer" }, "formation_date": {}, "social_links": { "type": "object", "properties": { "website": { "type": "string" }, "twitter": { "type": "string" } } }, "wikidata_id": { "type": "string" }, "release_count": { "type": "integer" } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 5, "name": "Adam Beyer", "country": "Sweden", "formation_year": 1976, "formation_date": null, "social_links": { "website": "https://adambeyer.com", "twitter": "adam_beyer" }, "wikidata_id": "Q469843", "release_count": 42 } ], "next_cursor": "42:5" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Label ID.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/releases/search": { "get": { "operationId": "release-search", "summary": "Release search", "description": "Search for releases by title, optionally filtered by artist.", "tags": [ "Releases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "next_cursor": "0:85:1" } } } } }, "parameters": [ { "name": "title", "in": "query", "required": true, "description": "Release title to search.", "schema": { "type": "string" } }, { "name": "artist", "in": "query", "required": false, "description": "Artist name filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/releases/{id}": { "get": { "operationId": "release-by-id", "summary": "Release by ID", "description": "Get release by ID. Returns the release fields flat with nested artist and label objects, plus a peer tracks[] array — each track has ISRC, genre, subgenre, and artist credits.", "tags": [ "Releases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" }, "catalog_no": { "type": "string" }, "tracks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "duration": { "type": "integer" }, "isrc": { "type": "string" }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } } } } }, "example": { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12", "catalog_no": "724384960650", "tracks": [ { "id": 123, "title": "One More Time", "duration": 320, "isrc": "GBDUW0000053", "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "genre": [ "House" ], "subgenre": [ "French House" ] } ] } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Release ID.", "schema": { "type": "integer" } } ] } }, "/v1/releases/new": { "get": { "operationId": "new-releases", "summary": "New releases", "description": "Paginated feed of releases ordered by release date (newest first).\n\n**Requires a paid plan** — the free tier returns `403` for this endpoint.", "tags": [ "Releases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" }, "track_count": { "type": "integer" } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 789, "title": "Resonance EP", "artist": { "id": 3, "name": "Bicep" }, "label": { "id": 42, "name": "Ninja Tune" }, "release_date": "2026-03-22", "track_count": 4 } ], "next_cursor": "2026-03-22:78:789" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ], "x-paid-plan": true } }, "/v1/tracks/browse": { "get": { "operationId": "track-browse", "summary": "Browse tracks", "description": "Discover tracks by filtering on label, artist, genre, or year. Returns up to 20 tracks ordered by release date (newest first) by default; pass `randomize=true` to sample 20 random tracks from the top-popularity pool instead. At least one filter parameter is required — calls with no filters return `400`. Filter by genre with either `genreId` (a canonical id from `GET /v1/genres`) or `genre` (a free-text exact name) — prefer `genreId` as it is stable and unambiguous; use `genre` only to reach rare subgenres that `/v1/genres` does not list. `genre` and `genreId` are mutually exclusive — passing both returns `400`.\n\n**Requires a paid plan** — the free tier returns `403` for this endpoint.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "isrc": { "type": "string" }, "duration": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } } } } }, "example": { "results": [ { "id": 456, "title": "One More Time", "releases": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "isrc": "GBDUW0000053", "duration": 320, "genre": [ "House" ], "subgenre": [ "French House" ] } ] } } } } }, "parameters": [ { "name": "labelId", "in": "query", "required": false, "description": "Filter by label ID.", "schema": { "type": "integer" } }, { "name": "artistId", "in": "query", "required": false, "description": "Filter by artist ID.", "schema": { "type": "integer" } }, { "name": "genre", "in": "query", "required": false, "description": "Exact genre name, case-insensitive (`House` matches House but not Tech House). Free-text alternative to `genreId` — use it for rare subgenres not listed by `GET /v1/genres`. Mutually exclusive with `genreId`.", "schema": { "type": "string" } }, { "name": "genreId", "in": "query", "required": false, "description": "Canonical genre id from `GET /v1/genres` — the stable, unambiguous way to filter by genre. Mutually exclusive with `genre`.", "schema": { "type": "integer" } }, { "name": "year", "in": "query", "required": false, "description": "Release year (e.g. 2025).", "schema": { "type": "integer" } }, { "name": "randomize", "in": "query", "required": false, "description": "If `true`, return 20 random tracks sampled from the top 1000 by popularity instead of the most recent releases. Defaults to `false`.", "schema": { "type": "boolean" } } ], "x-paid-plan": true } }, "/v1/genres": { "get": { "operationId": "genre-list", "summary": "List genres", "description": "Lists every canonical genre and subgenre SonoVault recognises. Use this to find the numeric `genreId` for a genre suggestion — the suggestion endpoint validates against this exact list, so it never goes out of date.", "tags": [ "Genres" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "genres": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "parent": {} } } } } }, "example": { "genres": [ { "id": 12, "name": "House", "type": "main", "parent": null }, { "id": 47, "name": "French House", "type": "subgenre", "parent": "House" } ] } } } } } } }, "/v1/tracks/{id}/suggestions": { "post": { "operationId": "submit-suggestion", "summary": "Suggest a genre", "description": "Suggest a better genre for a track. Suggestions are reviewed by the SonoVault team before they affect the catalog — a successful call returns the suggestion with `status: \"pending\"`. Requires a paid plan.\n\n**Requires a paid plan** — the free tier returns `403` for this endpoint.\n\n**Limits**\n\n- Up to 100 suggestions per day per account. Can be increased upon request.", "tags": [ "Suggestions" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "track_id": { "type": "integer" }, "field": { "type": "string" }, "proposed_value": { "type": "object", "properties": { "genre_id": { "type": "integer" }, "genre_name": { "type": "string" } } }, "current_value": { "type": "object", "properties": { "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": {} } } }, "note": { "type": "string" }, "status": { "type": "string" }, "review_note": {}, "created_at": { "type": "string" }, "reviewed_at": {} } }, "example": { "id": 5012, "track_id": 123, "field": "genre", "proposed_value": { "genre_id": 47, "genre_name": "French House" }, "current_value": { "genre": [ "Pop" ], "subgenre": [] }, "note": "This is clearly French House, not Pop.", "status": "pending", "review_note": null, "created_at": "2026-05-15T10:32:00.000Z", "reviewed_at": null } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Internal SonoVault track ID.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "genreId": { "type": "integer", "description": "a genre id from `GET /v1/genres`." }, "note": { "type": "string", "description": "a short explanation for the reviewer, max 100 characters." } }, "required": [ "genreId" ] } } } }, "x-paid-plan": true } }, "/v1/suggestions": { "get": { "operationId": "my-suggestions", "summary": "List your suggestions", "description": "Lists the edit suggestions you have submitted and their review status (`pending`, `approved`, or `rejected`), newest first.", "tags": [ "Suggestions" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "track_id": { "type": "integer" }, "field": { "type": "string" }, "proposed_value": { "type": "object", "properties": { "genre_id": { "type": "integer" }, "genre_name": { "type": "string" } } }, "current_value": { "type": "object", "properties": { "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": {} } } }, "note": { "type": "string" }, "status": { "type": "string" }, "review_note": {}, "created_at": { "type": "string" }, "reviewed_at": { "type": "string" } } } }, "next_cursor": {} } }, "example": { "results": [ { "id": 5012, "track_id": 123, "field": "genre", "proposed_value": { "genre_id": 47, "genre_name": "French House" }, "current_value": { "genre": [ "Pop" ], "subgenre": [] }, "note": "This is clearly French House, not Pop.", "status": "approved", "review_note": null, "created_at": "2026-05-15T10:32:00.000Z", "reviewed_at": "2026-05-15T14:05:00.000Z" } ], "next_cursor": null } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/streams": { "post": { "operationId": "stream-create", "summary": "Register a stream", "description": "Register a live broadcast/radio stream URL for continuous \"now playing\" recognition. We start monitoring immediately and recognise each track as it airs. Returns the stream id you'll poll for results. Billed at €29 per active stream / month. Paid plans only.\n\n**Requires a paid plan** — the free tier returns `403` for this endpoint.\n\n**Billing**\n\n- Each active stream is €29 / month, prorated, on a subscription separate from your API plan. Stop a stream and billing stops at period end.\n\n- The /v1/streams endpoints (register, poll now-playing, history, stop) don't use API credits — they're included with the per-stream subscription.", "tags": [ "Streams" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "detection_mode": { "type": "string" }, "created_at": { "type": "string" }, "stopped_at": {} } }, "example": { "id": "9f2c8e1a-1b2c-4d5e-8f90-1a2b3c4d5e6f", "url": "https://stream.example.com/radio.mp3", "name": "My Station", "status": "active", "detection_mode": "balanced", "created_at": "2026-06-14T18:30:00.000Z", "stopped_at": null } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "the direct stream URL (HTTP/Icecast/Shoutcast mp3 or AAC). Give the audio stream itself, not a webpage or playlist page." }, "name": { "type": "string", "description": "a label for the stream, shown in your dashboard." }, "format": { "type": "string", "description": "recognition-tuning hint for the station's music. One of `electronic`, `classical`, or `pop`; omit for `auto` (all recognisers), which is safest for mixed stations. `electronic` and `classical` narrow the recognisers to the ones that work for that material (e.g. `classical` uses AcoustID only). Change it any time with `PATCH /v1/streams/:id`." }, "detection_mode": { "type": "string", "description": "how sure we must be before reporting a track, trading off accuracy vs. coverage. `precise` reports fewer tracks but almost all are correct; `balanced` (the default) is a strong mix; `broad` catches more tracks but with some wrong guesses. We auto-tune each stream toward the chosen target using the station's own now-playing data. Change it any time with `PATCH /v1/streams/:id`." } }, "required": [ "url" ] } } } }, "x-paid-plan": true }, "get": { "operationId": "stream-list", "summary": "List streams", "description": "List the streams you've registered (active and stopped), newest first.\n\n**Requires a paid plan** — the free tier returns `403` for this endpoint.", "tags": [ "Streams" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "streams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "detection_mode": { "type": "string" }, "created_at": { "type": "string" }, "stopped_at": {} } } } } }, "example": { "streams": [ { "id": "9f2c8e1a-1b2c-4d5e-8f90-1a2b3c4d5e6f", "url": "https://stream.example.com/radio.mp3", "name": "My Station", "status": "active", "detection_mode": "balanced", "created_at": "2026-06-14T18:30:00.000Z", "stopped_at": null } ] } } } } }, "x-paid-plan": true } }, "/v1/streams/{id}": { "get": { "operationId": "stream-get", "summary": "Stream status + now playing", "description": "Get a stream's status and the track playing right now. `now_playing` is null during ad breaks, talk, or unrecognised audio. The track is a plain track object — the same shape as search results.\n\n**Requires a paid plan** — the free tier returns `403` for this endpoint.", "tags": [ "Streams" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "detection_mode": { "type": "string" }, "runtime_status": { "type": "string" }, "now_playing": { "type": "object", "properties": { "track": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "isrc": { "type": "string" }, "duration": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } }, "started_at": { "type": "string" } } }, "last_recognized_at": { "type": "string" } } }, "example": { "id": "9f2c8e1a-1b2c-4d5e-8f90-1a2b3c4d5e6f", "url": "https://stream.example.com/radio.mp3", "name": "My Station", "status": "active", "detection_mode": "balanced", "runtime_status": "running", "now_playing": { "track": { "id": 123, "title": "One More Time", "releases": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "isrc": "GBDUW0000053", "duration": 320, "genre": [ "House" ], "subgenre": [ "French House" ] }, "started_at": "2026-06-14T18:42:11.000Z" }, "last_recognized_at": "2026-06-14T18:43:02.000Z" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Stream id from registration.", "schema": { "type": "string" } } ], "x-paid-plan": true }, "patch": { "operationId": "stream-format", "summary": "Update stream settings", "description": "Update a stream's `format` and/or `detection_mode`. `format` tunes which recognisers run, based on the kind of music the station plays (`electronic`, `classical`, `pop`, or `null` to clear back to `auto`) — `classical`, for example, runs AcoustID only. `detection_mode` sets your accuracy/coverage preference (`precise`, `balanced`, or `broad`). Send either field, or both. Takes effect within a minute, no need to re-register.\n\n**Requires a paid plan** — the free tier returns `403` for this endpoint.", "tags": [ "Streams" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "detection_mode": { "type": "string" } } }, "example": { "id": "9f2c8e1a-1b2c-4d5e-8f90-1a2b3c4d5e6f", "detection_mode": "precise" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Stream id.", "schema": { "type": "string" } } ], "x-paid-plan": true }, "delete": { "operationId": "stream-stop", "summary": "Stop a stream", "description": "Stop monitoring a stream. Billing for it stops at the end of the current period. Idempotent.\n\n**Requires a paid plan** — the free tier returns `403` for this endpoint.", "tags": [ "Streams" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "example": { "ok": true } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Stream id.", "schema": { "type": "string" } } ], "x-paid-plan": true } }, "/v1/streams/{id}/history": { "get": { "operationId": "stream-history", "summary": "Recognition history", "description": "The stream's recognition log, newest first. Each entry is a recognised track with the time it started. Use `since` to fetch only what's new.\n\n**Requires a paid plan** — the free tier returns `403` for this endpoint.", "tags": [ "Streams" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "plays": { "type": "array", "items": { "type": "object", "properties": { "track": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "isrc": { "type": "string" }, "duration": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } }, "started_at": { "type": "string" } } } } } }, "example": { "plays": [ { "track": { "id": 123, "title": "One More Time", "releases": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "isrc": "GBDUW0000053", "duration": 320, "genre": [ "House" ], "subgenre": [ "French House" ] }, "started_at": "2026-06-14T18:42:11.000Z" } ] } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Stream id.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "ISO-8601 timestamp — return only plays that started after it.", "schema": { "type": "string" } } ], "x-paid-plan": true } }, "/v1/streams/report": { "get": { "operationId": "stream-report", "summary": "Airplay report", "description": "Airplay/spin report over a date range — across all your streams, or one via `stream_id`. The report is grouped by stream: each `streams[]` entry carries its own per-track `summary` of play counts plus a timestamped `detail` play-by-play log, each row carrying its ISRC. Plays are de-duplicated per airing: one airing counts once, not once per recognition window. JSON only.\n\n**Requires a paid plan** — the free tier returns `403` for this endpoint.", "tags": [ "Streams" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "report": { "type": "object", "properties": { "from": { "type": "string" }, "until": { "type": "string" }, "generated_at": { "type": "string" }, "scope": { "type": "object", "properties": { "stream_id": {} } }, "streams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "summary": { "type": "array", "items": { "type": "object", "properties": { "track_id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "string" }, "isrc": { "type": "string" }, "play_count": { "type": "integer" }, "first_played_at": { "type": "string" }, "last_played_at": { "type": "string" } } } }, "detail": { "type": "array", "items": { "type": "object", "properties": { "played_at": { "type": "string" }, "ended_at": { "type": "string" }, "duration_seconds": { "type": "integer" }, "track_id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "string" }, "isrc": { "type": "string" } } } } } } } } } } }, "example": { "report": { "from": "2026-06-01T00:00:00.000Z", "until": "2026-07-01T00:00:00.000Z", "generated_at": "2026-06-24T14:42:33.000Z", "scope": { "stream_id": null }, "streams": [ { "id": "9f2c8e1a-1b2c-4d5e-8f90-1a2b3c4d5e6f", "name": "My Station", "url": "https://stream.example.com/radio.mp3", "summary": [ { "track_id": 123, "title": "Strobe", "artist": "deadmau5", "isrc": "USMC10800001", "play_count": 12, "first_played_at": "2026-06-02T08:14:00.000Z", "last_played_at": "2026-06-29T22:03:00.000Z" } ], "detail": [ { "played_at": "2026-06-02T08:14:00.000Z", "ended_at": "2026-06-02T08:19:00.000Z", "duration_seconds": 300, "track_id": 123, "title": "Strobe", "artist": "deadmau5", "isrc": "USMC10800001" } ] } ] } } } } } }, "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Start of the window (inclusive), ISO date — e.g. 2026-06-01.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": true, "description": "End of the window (exclusive), ISO date. The window must be 92 days or less.", "schema": { "type": "string" } }, { "name": "stream_id", "in": "query", "required": false, "description": "Limit the report to one stream id. Omit for an account-wide report across all your streams.", "schema": { "type": "string" } } ], "x-paid-plan": true } }, "/v1/webhooks": { "post": { "operationId": "webhook-create", "summary": "Create a webhook", "description": "Register an endpoint to receive a signed HTTP POST whenever a track is recognised on any of your monitored streams — no polling. The response includes the signing `secret` once; store it to verify deliveries. Bundled with stream monitoring (no API credits).\n\n**Verifying deliveries**\n\n- Every POST carries `SonoVault-Signature: t=,v1=` where `v1 = HMAC-SHA256(secret, \"{t}.{rawBody}\")`. Recompute over the raw body and compare; reject if `t` is too old (replay protection).\n\n- Also sent: `SonoVault-Event-Id` (stable across retries — dedupe on it) and `SonoVault-Event-Type`.\n\n- Return any 2xx to acknowledge. Non-2xx / timeouts are retried with exponential backoff (~10s → 6h, given up after 12 attempts); sustained failures auto-disable the endpoint.\n\n**Event payload**\n\n- `stream.play.started` — `{ id, type, created, data: { stream_id, started_at, track } }`. (A track-end event isn't offered yet — there's no reliable end signal.)\n\n- `track` is the standard public track object (same shape as search results).", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": {}, "event_types": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "secret": { "type": "string" }, "created_at": { "type": "string" }, "last_delivery_at": {} } }, "example": { "id": "3b1f8c2a-4d5e-6f70-8192-a3b4c5d6e7f8", "url": "https://example.com/webhooks/sonovault", "description": null, "event_types": [ "stream.play.started" ], "enabled": true, "secret": "whsec_8Kd2v…shown_once", "created_at": "2026-06-25T18:30:00.000Z", "last_delivery_at": null } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "your HTTPS endpoint; we POST events here." }, "event_types": { "type": "string", "description": "which events to receive; defaults to all currently-available events. For now there is just one: `stream.play.started`." }, "description": { "type": "string", "description": "a label shown in your dashboard." } }, "required": [ "url" ] } } } } }, "get": { "operationId": "webhook-list", "summary": "List webhooks", "description": "List your webhook endpoints. The signing secret is never returned after creation.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": {}, "event_types": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "created_at": { "type": "string" }, "last_delivery_at": { "type": "string" } } } } } }, "example": { "webhooks": [ { "id": "3b1f8c2a-4d5e-6f70-8192-a3b4c5d6e7f8", "url": "https://example.com/webhooks/sonovault", "description": null, "event_types": [ "stream.play.started" ], "enabled": true, "created_at": "2026-06-25T18:30:00.000Z", "last_delivery_at": "2026-06-25T19:02:11.000Z" } ] } } } } } } }, "/v1/webhooks/{id}": { "patch": { "operationId": "webhook-update", "summary": "Update a webhook", "description": "Update an endpoint's `url`, `event_types`, and/or `enabled`. Re-enabling a disabled endpoint clears its failure streak. Send at least one field.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": {}, "event_types": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "created_at": { "type": "string" }, "last_delivery_at": { "type": "string" } } }, "example": { "id": "3b1f8c2a-4d5e-6f70-8192-a3b4c5d6e7f8", "url": "https://example.com/webhooks/sonovault", "description": null, "event_types": [ "stream.play.started" ], "enabled": false, "created_at": "2026-06-25T18:30:00.000Z", "last_delivery_at": "2026-06-25T19:02:11.000Z" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "string" } } ] }, "delete": { "operationId": "webhook-delete", "summary": "Delete a webhook", "description": "Delete an endpoint. Delivery stops immediately; past delivery history is retained.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "example": { "ok": true } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "string" } } ] } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "webhook-test", "summary": "Send a test event", "description": "Deliver a sample `stream.play.started` event to the endpoint right now (signed exactly like a real event) and report the result.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "response_status": { "type": "integer" }, "error": {} } }, "example": { "delivered": true, "response_status": 200, "error": null } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "webhook-deliveries", "summary": "Recent deliveries", "description": "The endpoint's recent delivery attempts (status, HTTP response, attempt count) — for debugging integrations.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "response_status": { "type": "integer" }, "error": {}, "created_at": { "type": "string" }, "last_attempt_at": { "type": "string" }, "next_attempt_at": { "type": "string" } } } } } }, "example": { "deliveries": [ { "id": "7c2e…", "event_id": "a1b2c3d4-…", "event_type": "stream.play.started", "status": "success", "attempts": 1, "response_status": 200, "error": null, "created_at": "2026-06-25T19:02:11.000Z", "last_attempt_at": "2026-06-25T19:02:11.200Z", "next_attempt_at": "2026-06-25T19:02:11.000Z" } ] } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id.", "schema": { "type": "string" } } ] } }, "/v1/streams/live": { "get": { "operationId": "stream-live", "summary": "Live feed (SSE)", "description": "A Server-Sent Events stream of your stream-play events in real time, across all your streams — the push alternative to polling now-playing. Each message is an SSE `event:` line (`stream.play.started`) with the event JSON in `data:`. Authenticate with the `x-api-key` header; in the browser, proxy this through your own server so the key isn't exposed (the EventSource API can't send headers). Bundled with stream monitoring (no API credits).", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "created": { "type": "string" }, "data": { "type": "object", "properties": { "stream_id": { "type": "string" }, "started_at": { "type": "string" }, "track": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "isrc": { "type": "string" }, "duration": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } } } } } }, "example": { "id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789", "type": "stream.play.started", "created": "2026-06-25T19:02:11.000Z", "data": { "stream_id": "9f2c8e1a-1b2c-4d5e-8f90-1a2b3c4d5e6f", "started_at": "2026-06-25T19:02:10.000Z", "track": { "id": 123, "title": "One More Time", "releases": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "isrc": "GBDUW0000053", "duration": 320, "genre": [ "House" ], "subgenre": [ "French House" ] } } } } } } } } } } }