> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rivi.software/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> APIs for listener websites, mobile apps, and now-playing metadata ingestion.

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`](/radiotools/openapi.json).

<CardGroup cols={2}>
  <Card title="First request & response handling" href="/radiotools/api-reference/response-handling">
    Working requests, pagination, conditional reads, and non-JSON responses.
  </Card>

  <Card title="Field types & empty states" href="/radiotools/api-reference/field-types">
    Real values, nullability, timestamps, content schemas, freshness, and units.
  </Card>

  <Card title="Public delivery" href="/radiotools/api-reference/public-delivery">
    Listener JSON reads, ETags, the realtime feed, and anonymous media URLs.
  </Card>

  <Card title="GraphQL" href="/radiotools/api-reference/graphql">
    Query published data with one request, plus an in-browser playground.
  </Card>

  <Card title="Authentication" href="/radiotools/api-reference/authentication">
    Listener tokens, push registration, and ingest credentials.
  </Card>

  <Card title="Now-playing ingest" href="/radiotools/api-reference/now-playing-ingest">
    Send reported track metadata from external automation.
  </Card>

  <Card title="Errors & versioning" href="/radiotools/api-reference/errors-and-versioning">
    Stable error codes, pagination, and contractVersion.
  </Card>

  <Card title="HTTP operations" href="/radiotools/api-reference/public-listener/get-station">
    Interactive parameters, schemas, examples, and a request playground.
  </Card>
</CardGroup>

## 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](/radiotools/station-admin/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

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

## SDK

The [RadioTools SDKs](/radiotools/api-reference/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.


## Related topics

- [Editorial](/radiotools/daily-work/editorial.md)
- [Station settings](/radiotools/station-admin/station-settings.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.