Streams

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.

Requires a paid plan: the free tier returns 403 for this endpoint.

Billing

  • Each active stream is €29 / month, prorated, on a subscription separate from your API plan. Stop a stream and billing stops at period end.

  • The /v1/streams endpoints (register, poll now-playing, history, stop) don't use API credits; they're included with the per-stream subscription.

post/v1/streams

Request

  • Base URL: https://api.sonovault.now
  • URL: https://api.sonovault.now/v1/streams
  • Auth: API key in header x-api-key

Request body

urlstring required

the direct stream URL (HTTP/Icecast/Shoutcast mp3 or AAC). Give the audio stream itself, not a webpage or playlist page.

namestring

a label for the stream, shown in your dashboard.

formatstring

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_modestring

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.

Response

Successful response

idstring required

Stream ID (UUID). Every other stream endpoint takes it.

urlstring required

The audio stream URL being monitored.

namestring nullable required

Your label for the stream. null when you did not set one.

status'active' | 'stopped' required

active while monitored and billed, stopped after you stop it.

detection_mode'precise' | 'balanced' | 'broad' required

The accuracy/coverage target the matcher tunes toward.

outage_notificationsboolean required

Whether we email you when this stream goes down and when it recovers. Defaults to true; toggle it with PATCH /v1/streams/:id.

created_atstring required

When the stream was registered, ISO-8601 UTC.

stopped_atstring nullable required

When it was stopped, ISO-8601 UTC. null while active.

Changes

No recorded changes to this operation across all 1 revision of this API.