---
title: "Register a stream"
method: POST
path: "/v1/streams"
tags: ["Streams"]
---

# Register a stream

`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`

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.

## Request body

- object
  - `url` string, required: the direct stream URL (HTTP/Icecast/Shoutcast mp3 or AAC). Give the audio stream itself, not a webpage or playlist page.
  - `name` string: a label for the stream, shown in your dashboard.
  - `format` string: 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` string: 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 `200`

Successful response

- Stream: A registered broadcast stream under continuous recognition.
  - `id` string, required: Stream ID (UUID). Every other stream endpoint takes it.
  - `url` string, required: The audio stream URL being monitored.
  - `name` string, 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_notifications` boolean, 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_at` string, required: When the stream was registered, ISO-8601 UTC.
  - `stopped_at` string, nullable, required: When it was stopped, ISO-8601 UTC. `null` while active.

---

[API](https://skmtc.dev/sonovault/apis/sonovault-api.md) · [All operations](https://skmtc.dev/sonovault/apis/sonovault-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sonovault/apis/sonovault-api/revisions/0152fff23f2c?raw)