API overview - RIVI Software Docs

Build listener websites and mobile apps, and send now-playing metadata from external automation using the RadioTools API. This reference publishes the relevant operations from the product application’s generated contract. Download the public OpenAPI 3.1 document at /openapi.json.

First request & response handling

Working requests, pagination, conditional reads, and non-JSON responses.

Field types & empty states

Real values, nullability, timestamps, content schemas, freshness, and units.

Public delivery

Listener JSON reads, ETags, the realtime feed, and anonymous media URLs.

GraphQL

Query published data with one request, plus an in-browser playground.

Authentication

Listener tokens, push registration, and ingest credentials.

Now-playing ingest

Send reported track metadata from external automation.

Errors & versioning

Stable error codes, pagination, and contractVersion.

HTTP operations

Interactive parameters, schemas, examples, and a request playground.

API surfaces

Tag	Purpose	Authentication
Public listener	Published content, schedule, on-air, now-playing, track history, weather, traffic, GraphQL, public media, and listener push registration	`listener:read` for listener reads and GraphQL; `push:register` for device changes; published media and the realtime feed are anonymous
Ingest	Now-playing observations from external automation	Integration credential with `ingest:write`

Open HTTP operations in the API reference sidebar for endpoint schemas, examples, and Try it. Requests are sent to https://radiotools.rivi.software and require credentials with access to that operation. Station administrators issue credentials in the dashboard — see Integrations.

What each endpoint returns

Paths below are relative to /api/v1/stations/{stationSlug} unless shown in full.

Endpoint	Response contents
`GET /`	Station identity, public profile, resource links, realtime feed details, and polling policy
`GET /schemas`	Published type definitions, field kinds, and constraints
`GET /content?type=<key>`	Published records, mixed-type field values, documents, media, and pagination
`GET /content/{id}`	One published record
`GET /content/{type}/by-slug/{slug}`	One published record, looked up by its current or a previous slug
`GET /schedule` / `GET /programs`	Broadcasts, or programs with their presenters and regular slots, in an inclusive date window
`GET /broadcast/current`	Current public broadcast, or `null`
`GET /now-playing` / `GET /track-history`	Reported track observations, freshness or pagination
`GET /weather` / `GET /traffic`	Normalized provider snapshots with freshness
`GET /schedule.ics`	Calendar text
`GET`, `POST /graphql`	GraphQL queries over the same published data
`POST`, `PATCH`, `DELETE /push/devices`	Register a device, update topic preferences, or remove a device
`GET /api/media/public/{stationId}/{id}[/{variant}]`	Published media bytes; `id` is the media version UUID
`POST /api/v1/integrations/playback?stationSlug=<slug>`	Observation acceptance and ingest/follow outcome

Each operation page pairs the contract schema with curated fictional examples. Types, required fields, and bounds remain visible alongside realistic values; examples also show empty, stale, and unavailable states where relevant.

Recommended listener integration flow

Create a station credential with listener:read in the dashboard and store the secret on your server.
GET /api/v1/stations/{stationSlug} with Authorization: Bearer — discover resources links and delivery.pollIntervalSeconds.
GET …/schemas then GET …/content?type= with cursor pagination (same header on every JSON read).
Poll with If-None-Match, or subscribe to the realtime feed described in resources.realtime for updates.
Resolve media URLs from published records via /api/media/public/{stationId}/{versionId} — no token on media bytes.

SDK

The RadioTools SDKs provide typed helpers for public HTTP, GraphQL, and the realtime feed, plus playback ingest. Start with @rivi-software/radiotools-sdk for TypeScript, or use a React, Vue, Svelte, or Next.js binding. Configure the SDK on the server with a tenant token (listener:read); browser clients use your app as a bridge.

Test with sample data

Use a separate sample station and credentials to exercise empty collections, unpublished records, stale now-playing data, revoked access, and disabled API switches. The fictional RIVI FM screenshots in these guides demonstrate the workspace; they do not provide a public demo endpoint or usable credentials. The listener API delivers published station data. Staff-only editorial, planning, and preparation management operations are outside this listener reference. Use the dashboard and its authorized workflows for staff work.