GraphQL

The listener GraphQL endpoint returns the same published data as the HTTP API. Use it when a page needs several resources at once, such as the station, now-playing track, and today’s schedule, and you want to choose the fields.

Endpoint

POST /api/v1/stations/{stationSlug}/graphql
Content-Type: application/json
Authorization: Bearer <tenant token>

Use a credential with listener:read. See Authentication for the Bearer prefix.
POST takes a JSON body with query and optional variables, operationName, and extensions. See Query GraphQL.
GET takes the same fields as URL parameters. variables and extensions are JSON-encoded strings. See Query GraphQL with GET.
OPTIONS answers CORS preflight.
Responses are Cache-Control: no-store. GraphQL has no ETag layer; use the HTTP resources when you need conditional reads.
Unknown, inactive, or public-offline stations return HTTP 404 before the query runs.
Keep the token on your server. Browser clients should call your own origin, which forwards the request.

Make a request

curl -sS "https://radiotools.rivi.software/api/v1/stations/rivi-fm/graphql" \
  -H "Authorization: Bearer $RADIOTOOLS_LISTENER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ station { name timezone delivery { pollIntervalSeconds } } }"}'

const response = await fetch(
  "https://radiotools.rivi.software/api/v1/stations/rivi-fm/graphql",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.RADIOTOOLS_LISTENER_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: `query Week($from: String!, $through: String!) {
        schedule(fromDate: $from, throughDate: $through) {
          broadcasts { title startsAt endsAt }
        }
      }`,
      variables: { from: "2026-10-05", through: "2026-10-11" },
    }),
  },
);
const { data, errors } = await response.json();

The same read with GET. Let curl URL-encode each parameter:

curl -sS -G "https://radiotools.rivi.software/api/v1/stations/rivi-fm/graphql" \
  -H "Authorization: Bearer $RADIOTOOLS_LISTENER_TOKEN" \
  --data-urlencode 'query=query Week($from: String!, $through: String!) { schedule(fromDate: $from, throughDate: $through) { broadcasts { title startsAt } } }' \
  --data-urlencode 'variables={"from":"2026-10-05","through":"2026-10-11"}'

GET runs queries only. Send the previewEditorial mutation with POST.

Playground

Run queries against the live API with a credential for your own station. The preset examples use the fictional rivi-fm slug, so replace it with your station’s slug. The playground sends the request directly from your browser to the RadioTools API. Nothing is stored, and the token is cleared when you leave the page. Listener queries only read published data.

Queries

The table summarizes each field. The GraphQL schema reference documents every argument, type, enum, error code, and JSON shape.

Field	Returns	Bounds
`station`	Identity, `profile`, `resources`, and `delivery` policy
`schemas(type, version)`	Published content type definitions	`version` requires `type`
`content(type, cursor, limit, sort, direction, filter)`	Published records and `nextCursor`, newest first by default	`limit` 1–50, default 25; up to 10 filters
`contentRecord(id)`	One published record with `values`, `document`, and `media`
`contentBySlug(type, slug)`	The published record a slug names, including a slug it used before	`slug` up to 200 characters
`schedule(fromDate, throughDate)`	Broadcasts in an inclusive date window	At most 31 days
`programs(fromDate, throughDate)`	Programs in that window, with presenters and regular slots	At most 31 days
`currentBroadcast`	The current public broadcast, or `broadcast: null`
`nowPlaying`	Reported track, timing, and `freshness`
`trackHistory(cursor, limit)`	Reported track observations and `nextCursor`	`limit` up to 100, default 25
`weather`	Normalized snapshots, or `null` when not entitled
`traffic`	Normalized snapshot, or `null` when not entitled

Dates are local YYYY-MM-DD strings. values, document, fields, and the weather and traffic snapshots use a JSON scalar, so you cannot select sub-fields inside them. Media bytes are not inlined; use PublicMedia.url, or a smaller rendition from PublicMedia.variants. content accepts the same sort, direction, and field filters as the HTTP collection. See Requests and response handling. nowPlaying and trackHistory reflect encoder observations, not the planned rundown. artworkUrl is omitted when unknown.

Example queries

Published records for one content type, newest first:

query NewsPage($cursor: ID) {
  content(type: "news", limit: 10, cursor: $cursor) {
    nextCursor
    records {
      id
      publishedAt
      firstPublishedAt
      values
    }
  }
}

Filter and sort records. Several filters must all match:

query RegionalSport {
  content(
    type: "news"
    sort: updatedAt
    direction: desc
    filter: [
      { field: "category", value: "sports" }
      { field: "regions", op: anyOf, values: ["noord", "zuid"] }
    ]
  ) {
    nextCursor
    records {
      id
      values
    }
  }
}

A record by its slug, with media for a responsive image:

query NewsArticle($slug: String!) {
  contentBySlug(type: "news", slug: $slug) {
    id
    revision
    firstPublishedAt
    publishedAt
    values
    document
    media {
      versionId
      kind
      url
      alt
      width
      height
      variants {
        thumb
        display
        card
        square
      }
    }
  }
}

A slug the record used before still resolves. Compare values.slug with the slug you requested, and redirect to the current URL when they differ. Use contentRecord(id:) when you already have the record ID. Now playing with recent tracks:

query OnAirTrack {
  nowPlaying {
    track {
      artist
      title
      artworkUrl
      isPlaying
      observedAt
    }
    freshness {
      status
      ageSeconds
    }
  }
  trackHistory(limit: 20) {
    items {
      id
      artist
      title
      observedAt
    }
    nextCursor
  }
}

Errors

Failures return a standard GraphQL errors array. Branch on errors[0].extensions.code, which uses the same stable codes as the REST API, and read issues for validation details.

{
  "errors": [
    {
      "message": "Invalid arguments",
      "extensions": {
        "code": "VALIDATION_ERROR",
        "issues": [{ "path": "limit", "message": "Too big: expected number to be <=50" }]
      }
    }
  ]
}

Each issue has a path and a message. An issue can also carry a stable code and a suggestion, a value you could send instead. The HTTP status follows the most severe error code, for example 400 for VALIDATION_ERROR, 401 for UNAUTHENTICATED, 404 for NOT_FOUND, and 429 for RATE_LIMITED. A resource that is disabled for the station returns NOT_FOUND, except weather and traffic, which return null. See Errors and versioning.

Editorial preview

The previewEditorial mutation renders a draft revision for a headless site’s preview mode. Send it with POST. It needs the listener Bearer token and an X-Preview-Grant header holding a 15-minute preview grant. The playground does not send that header; use it from your server.

POST /api/v1/stations/{stationSlug}/graphql
Authorization: Bearer <tenant token>
X-Preview-Grant: <preview grant>
Content-Type: application/json

mutation Preview($input: PreviewInput!) {
  previewEditorial(input: $input) {
    revision
    values
    document
    media {
      url
    }
  }
}

PreviewInput takes stationId, recordId, revision, and audience. Never put the grant in a URL.

Live updates

GraphQL has no subscriptions. For live now-playing, on-air, schedule, and content changes, follow the station’s public realtime feed, which station.resources.realtime describes. The TypeScript SDK subscribes for you. See Public realtime feed.

Introspection

The endpoint accepts standard introspection queries, so GraphQL clients and code generators can read the schema from it. The TypeScript SDK provides typed helpers for the same operations; set transport: "graphql" to use them.

Guides

SDKs

HTTP operations

Endpoint

Make a request

Playground

Queries

Example queries

Errors

Editorial preview

Live updates

Introspection

​Endpoint

​Make a request

​Playground

​Queries

​Example queries

​Errors

​Editorial preview

​Live updates

​Introspection

Endpoint

Make a request

Playground

Queries

Example queries

Errors

Editorial preview

Live updates

Introspection