Overview

The SonoVault API gives you access to music metadata for 90 million tracks and counting. Look up ISRC codes, ISWC work codes, artist credits, label, genre tags, release dates, and cross-platform IDs — all from a single REST endpoint.

Use it to power music discovery apps, catalog management, sync and royalty tools, or any workflow that needs accurate track-level data.

All responses are JSON. Every request requires an API key in the x-api-key header. There are no SDKs to install — any HTTP client works.

What you can do

• Search tracks by artist and title — returns ISRC, duration, genre, and artist credits.
• Look up by ISRC — get full metadata for a specific recording.
• Resolve ISWC work codes — find the composition code(s) behind a recording, or list every recording of a work by its ISWC.
• Resolve cross-platform IDs — given a Spotify, Beatport, Apple Music, Tidal, Discogs, or MusicBrainz ID, get matching IDs on all other platforms.
• Search artists and releases — find artists by name or browse their discography.
• New releases — paginated feed of the latest releases, sorted by artist popularity.

Try it without signing up

Every endpoint on this page has a Try it out button that opens the API explorer. It uses a public demo key so you can make real requests and see live responses — no account required. Click Try it out on any endpoint to get started.

Quickstart

Get from zero to your first API response in under 5 minutes. Create a free account to get an API key — no credit card required.

1. Sign up and verify your email

Create a free account at sonovault.now. We send a verification link to your inbox — click it before making API calls. Until your email is verified, every /v1 request returns 403 Email not verified.

2. Get your API key

Once verified, grab your key from the dashboard. All requests must include it in the x-api-key header.

3. Make your first request

Search for a track by artist and title. The response includes ISRC, duration, genre, and full artist credits.

curl https://api.sonovault.now/v1/tracks/search \
  -H "x-api-key: YOUR_API_KEY" \
  -G   -d "artist=Daft Punk" \
  -d "title=One More Time"

4. Explore the API

Now that you have your first result, try looking up the ISRC with the ISRC lookup endpoint or resolve cross-platform links with Platform links.

Authentication

All API requests require a valid API key passed in the x-api-key header.

x-api-key: svk_live_xxxxxxxxxxxxxxxxxx

Test keys prefixed svk_test_ return mocked data. Live keys prefixed svk_live_ hit the real database.

Base URL

All API requests use the following base URL:

https://api.sonovault.now

All endpoints return JSON with Content-Type: application/json. Request parameters are passed as query strings for GET requests.

Rate limits

Rate limits are enforced per API key on a rolling 60-second window. If you exceed your limit, requests return 429 Too Many Requests.

Every response includes rate limit headers so you can track your usage and avoid hitting limits:

When you receive a 429 response, wait the number of seconds in RateLimit-Reset before retrying. For batch workloads, check RateLimit-Remaining and throttle proactively rather than waiting for a rejection.

Errors

All errors return a JSON object with an error string:

{
  "error": "Not found"
}

Webhooks & events

For live broadcast monitoring you don't have to poll — SonoVault can push every recognised play to you in real time. Two delivery options, both bundled with stream monitoring (no API credits):

• Webhooks — register an endpoint and we POST a signed event whenever a track is recognised on any of your streams. Best for server-to-server integrations (logging, royalties, automation).
• Live feed (SSE) — open a GET /v1/streams/live connection and receive events as a Server-Sent Events stream. Best for dashboards and live displays.

Event types

track is the standard public track object (same shape as search results). id is the event id — stable across retries, so use it to deduplicate. Manage endpoints with the Webhooks API, or from your dashboard. A track-*end* event isn't offered yet — there's no reliable signal for when a track stops.

Verifying signatures

Every webhook POST carries a SonoVault-Signature header: t=<unix-timestamp>,v1=<hex>, where v1 is HMAC-SHA256(secret, "{t}.{rawBody}") using the signing secret shown once when you created the endpoint. Recompute it over the raw request body and compare in constant time; reject if the timestamp is too old to block replays.

import crypto from "crypto";

// Express: needs the RAW body, e.g. app.use(express.raw({ type: "application/json" }))
function verify(rawBody: Buffer, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // replay window
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody.toString()}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Delivery & retries

• Return any 2xx to acknowledge. A non-2xx response or a timeout is retried with exponential backoff (~10s → 6h), given up on after 12 attempts.
• Deliveries are at-least-once — dedupe on SonoVault-Event-Id.
• An endpoint that keeps failing is automatically disabled; re-enable it from the dashboard or PATCH /v1/webhooks/:id.
• Inspect recent attempts (status, HTTP code, error) via GET /v1/webhooks/:id/deliveries or send a sample with POST /v1/webhooks/:id/test.

Live feed (SSE)

GET /v1/streams/live returns a text/event-stream of the same events across all your streams. Each message is an SSE event: line (the event type) with the event JSON in data:. Authenticate with the x-api-key header. In the browser, the EventSource API can't send headers — proxy the request through your own server so your key isn't exposed.

Track search

Search for tracks by artist and title. Returns ISRC, genre, release dates, and full metadata.

Parameters

Pagination

When more results are available, the response includes a next_cursor string. Pass it as the cursor parameter to fetch the next page:

curl https://api.sonovault.now/v1/tracks/search \
  -H "x-api-key: YOUR_API_KEY" \
  -G   -d "artist=Daft Punk" \
  -d "title=Around" \
  -d "cursor=eyJpZCI6MTIzfQ"

When next_cursor is null, you have reached the last page.

ISRC lookup

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.

Path parameters

ISWC lookup

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.

Parameters

Recordings by ISWC

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.

Path parameters

Query parameters

Track by ID

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.

Path parameters

Platform links

Lightweight cross-platform ID resolver. Given an ISRC or a source-specific ID, returns all known external platform links.

Parameters

Provide exactly one lookup parameter per request: isrc, spotify, beatport, discogs, musicbrainz, applemusic, or tidal.

Bulk resolve

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.

Identify (audio recognition)

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.

Upload raw audio (no fpcalc)

Instead of a fingerprint, send the raw audio file itself — any ffmpeg-decodable format (mp3, flac, wav, m4a, ogg, opus…), up to 100 MB. Set Content-Type: application/octet-stream and put the file bytes in the request body; we fingerprint it server-side.

curl -X POST https://api.sonovault.now/v1/tracks/identify \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @track.mp3

Browse tracks

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.

Parameters

Artist search

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.

Parameters

Pagination

When more results are available, the response includes a next_cursor string. Pass it as the cursor parameter to fetch the next page:

curl https://api.sonovault.now/v1/artists/search \
  -H "x-api-key: YOUR_API_KEY" \
  -G   -d "name=Daft Punk" \
  -d "cursor=0:5000000:1"

When next_cursor is null, you have reached the last page.

Artist by ID

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.

Path parameters

Artists by label

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.

Path parameters

Query parameters

Label search

Search for record labels by name. Returns labels sorted by relevance and release count.

Parameters

Pagination

When more results are available, the response includes a next_cursor string. Pass it as the cursor parameter to fetch the next page:

curl https://api.sonovault.now/v1/labels/search \
  -H "x-api-key: YOUR_API_KEY" \
  -G   -d "name=Drumcode" \
  -d "cursor=0:42:1"

When next_cursor is null, you have reached the last page.

Label by ID

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.

Path parameters

Releases by artist

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).

Path parameters

Query parameters

Releases by label

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.

Path parameters

Query parameters

Release search

Search for releases by title, optionally filtered by artist.

Parameters

Pagination

When more results are available, the response includes a next_cursor string. Pass it as the cursor parameter to fetch the next page:

curl https://api.sonovault.now/v1/releases/search \
  -H "x-api-key: YOUR_API_KEY" \
  -G   -d "title=Discovery" \
  -d "cursor=0:85:1"

When next_cursor is null, you have reached the last page.

Release by ID

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.

Path parameters

New releases

Paginated feed of releases ordered by release date (newest first).

Parameters

Pagination

When more results are available, the response includes a next_cursor string. Pass it as the cursor parameter to fetch the next page:

curl https://api.sonovault.now/v1/releases/new \
  -H "x-api-key: YOUR_API_KEY" \
  -G   -d "limit=20" \
  -d "cursor=2026-03-22:78:789"

When next_cursor is null, you have reached the last page.

List genres

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.

Suggest a genre

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.

Path parameters

List your suggestions

Lists the edit suggestions you have submitted and their review status (pending, approved, or rejected), newest first.

Parameters

Register a stream

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.

List streams

List the streams you've registered (active and stopped), newest first.

Stream status + now playing

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.

Path parameters

Update stream settings

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.

Path parameters

Recognition history

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.

Path parameters

Query parameters

Airplay report

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.

Parameters

Stop a stream

Stop monitoring a stream. Billing for it stops at the end of the current period. Idempotent.

Path parameters

Create a webhook

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).

List webhooks

List your webhook endpoints. The signing secret is never returned after creation.

Update a webhook

Update an endpoint's url, event_types, and/or enabled. Re-enabling a disabled endpoint clears its failure streak. Send at least one field.

Path parameters

Delete a webhook

Delete an endpoint. Delivery stops immediately; past delivery history is retained.

Path parameters

Send a test event

Deliver a sample stream.play.started event to the endpoint right now (signed exactly like a real event) and report the result.

Path parameters

Recent deliveries

The endpoint's recent delivery attempts (status, HTTP response, attempt count) — for debugging integrations.

Path parameters

Live feed (SSE)

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).