> ## 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. # List content > Read published snapshots for one content type. Send type=news (replace news with a key from schemas), follow nextCursor until null, and filter only allowlisted delivery fields. Drafts and private values are excluded. ## OpenAPI ````yaml /radiotools/openapi.json get /api/v1/stations/{stationSlug}/content openapi: 3.1.0 info: title: RadioTools API version: 1.0.0 description: >- RadioTools APIs for listener websites and apps, published media, and now-playing metadata ingestion. servers: - url: https://radiotools.rivi.software description: radiotools API security: [] tags: - name: Public listener description: >- Tenant-token published delivery (listener:read; push:register for device changes). Published media remains anonymous. OPTIONS allows every origin; JSON is no-store with a strong ETag for conditional polling. - name: Ingest description: >- Automation credentials. The credential resolves the station; payloads cannot change it. paths: /api/v1/stations/{stationSlug}/content: get: tags: - Public listener summary: >- Only live published snapshots; no-store and visibility-checked conditional ETag description: >- Read published snapshots for one content type. Send type=news (replace news with a key from schemas), follow nextCursor until null, and filter only allowlisted delivery fields. Drafts and private values are excluded. parameters: - schema: type: string required: true name: stationSlug in: path description: >- Public station slug from the station settings; distinct from the internal station ID. example: radio-rivier - schema: type: string pattern: ^[a-z][a-z0-9_]{0,47}$ required: true name: type in: query description: Stable published content type key returned by the schemas endpoint. example: news - schema: type: string minLength: 1 maxLength: 400 required: false name: cursor in: query description: >- Opaque continuation value from nextCursor. Omit on the first request; pass the returned value unchanged. - schema: type: integer minimum: 1 maximum: 50 default: 25 required: false name: limit in: query description: Maximum number of items per page. See the bounds and default below. example: 25 - schema: type: string enum: - publishedAt - updatedAt default: publishedAt required: false name: sort in: query description: >- Order records by first publication (publishedAt) or by latest update (updatedAt). example: publishedAt - schema: type: string enum: - asc - desc default: desc required: false name: direction in: query description: 'Sort direction: desc for newest first, asc for oldest first.' example: desc - schema: type: array items: type: string maxItems: 10 description: >- Repeatable. field:value (exact), field.contains:value (case-insensitive substring) or field.anyOf:a,b. Text and choice delivery fields only. required: false description: >- Repeatable. field:value (exact), field.contains:value (case-insensitive substring) or field.anyOf:a,b. Text and choice delivery fields only. name: filter in: query responses: '200': description: Success; private/no-store content: application/json: schema: type: object properties: contractVersion: type: number enum: - 1 description: >- Public JSON contract version. The current version is 1; tolerate additional fields within this version. example: 1 type: type: string pattern: ^[a-z][a-z0-9_]{0,47}$ description: >- Published content type key; resolve its definition through the schemas endpoint. example: news records: type: array items: type: object properties: contractVersion: type: number enum: - 1 description: >- Public JSON contract version. The current version is 1; tolerate additional fields within this version. example: 1 id: type: string format: uuid description: >- Identifier of this resource. Use the value returned by the API for subsequent lookups. example: 5b961af1-c305-4a1e-aed4-b3dfdc72be09 publicationId: type: string format: uuid description: Identifier of the published snapshot. example: 77de95e7-3382-468c-b34a-880491592ae6 revision: type: integer exclusiveMinimum: 0 description: Revision of the published record. example: 3 type: type: string pattern: ^[a-z][a-z0-9_]{0,47}$ description: >- Published content type key; resolve its definition through the schemas endpoint. example: news schemaVersion: type: integer exclusiveMinimum: 0 description: >- Published content schema version used to interpret values. example: 1 publishedAt: type: string description: Timestamp when this snapshot was published. example: '2026-10-05T07:45:00.000Z' firstPublishedAt: type: string description: >- Timestamp when the record was first published. Later revisions keep this value. example: '2026-10-05T07:30:00.000Z' values: type: object additionalProperties: type: - object - array - string - number - boolean - 'null' description: >- Station-defined published field values, keyed by field key. Resolve definitions through type and schemaVersion; private fields are omitted. example: headline: Riverside festival opens this weekend featured: true reading_minutes: 2 category: local event_at: '2026-10-10T10:00:00.000Z' document: type: object properties: version: type: number enum: - 1 description: Version of this schema or structured document. example: 1 mode: type: string enum: - document - blocks description: Editorial document mode. example: document blocks: type: array items: oneOf: - type: object properties: id: type: string format: uuid description: >- Identifier of this resource. Use the value returned by the API for subsequent lookups. type: type: string enum: - text description: >- Discriminator describing this block or incident. Render according to the allowed values. content: type: array items: type: object properties: text: type: string maxLength: 20000 description: Text content of this span. marks: type: array items: type: string enum: - bold - italic - underline - strike maxItems: 4 description: >- Formatting marks applied to this text span. link: type: object properties: href: type: string maxLength: 2000 description: 'Absolute https: URL or mailto: address.' title: type: string maxLength: 300 description: >- Human-readable title. Track titles come from external automation. required: - href additionalProperties: false required: - text additionalProperties: false maxItems: 1000 description: >- Whether this device receives content notifications. required: - id - type - content additionalProperties: false - type: object properties: id: type: string format: uuid description: >- Identifier of this resource. Use the value returned by the API for subsequent lookups. type: type: string enum: - heading description: >- Discriminator describing this block or incident. Render according to the allowed values. level: type: integer minimum: 1 maximum: 3 description: Heading level. content: type: array items: type: object properties: text: type: string maxLength: 20000 description: Text content of this span. marks: type: array items: type: string enum: - bold - italic - underline - strike maxItems: 4 description: >- Formatting marks applied to this text span. link: type: object properties: href: type: string maxLength: 2000 description: 'Absolute https: URL or mailto: address.' title: type: string maxLength: 300 description: >- Human-readable title. Track titles come from external automation. required: - href additionalProperties: false required: - text additionalProperties: false maxItems: 1000 description: >- Whether this device receives content notifications. required: - id - type - level - content additionalProperties: false - type: object properties: id: type: string format: uuid description: >- Identifier of this resource. Use the value returned by the API for subsequent lookups. type: type: string enum: - quote description: >- Discriminator describing this block or incident. Render according to the allowed values. content: type: array items: type: object properties: text: type: string maxLength: 20000 description: Text content of this span. marks: type: array items: type: string enum: - bold - italic - underline - strike maxItems: 4 description: >- Formatting marks applied to this text span. link: type: object properties: href: type: string maxLength: 2000 description: 'Absolute https: URL or mailto: address.' title: type: string maxLength: 300 description: >- Human-readable title. Track titles come from external automation. required: - href additionalProperties: false required: - text additionalProperties: false maxItems: 1000 description: >- Whether this device receives content notifications. attribution: type: string maxLength: 300 description: Attribution for a quotation. required: - id - type - content - attribution additionalProperties: false - type: object properties: id: type: string format: uuid description: >- Identifier of this resource. Use the value returned by the API for subsequent lookups. type: type: string enum: - list description: >- Discriminator describing this block or incident. Render according to the allowed values. ordered: type: boolean items: type: array items: type: array items: type: object properties: text: type: string maxLength: 20000 description: Text content of this span. marks: type: array items: type: string enum: - bold - italic - underline - strike maxItems: 4 description: >- Formatting marks applied to this text span. link: type: object properties: href: type: string maxLength: 2000 description: 'Absolute https: URL or mailto: address.' title: type: string maxLength: 300 description: >- Human-readable title. Track titles come from external automation. required: - href additionalProperties: false required: - text additionalProperties: false maxItems: 1000 minItems: 1 maxItems: 50 description: >- Reported observations on this page. Repeated titles at different times remain separate entries. required: - id - type - ordered - items additionalProperties: false - type: object properties: id: type: string format: uuid description: >- Identifier of this resource. Use the value returned by the API for subsequent lookups. type: type: string enum: - image description: >- Discriminator describing this block or incident. Render according to the allowed values. assetId: type: string format: uuid description: >- Media asset identifier. Resolve a published rendition through the record's media list. alt: type: string maxLength: 1000 description: >- Alternative text for accessible image rendering. caption: type: string maxLength: 1000 description: Public caption for this media block. required: - id - type - assetId - alt - caption additionalProperties: false - type: object properties: id: type: string format: uuid description: >- Identifier of this resource. Use the value returned by the API for subsequent lookups. type: type: string enum: - gallery description: >- Discriminator describing this block or incident. Render according to the allowed values. images: type: array items: type: object properties: assetId: type: string format: uuid description: >- Media asset identifier. Resolve a published rendition through the record's media list. alt: type: string maxLength: 1000 description: >- Alternative text for accessible image rendering. required: - assetId - alt additionalProperties: false minItems: 1 maxItems: 20 description: >- Ordered gallery images with media asset identifiers and alternative text. required: - id - type - images additionalProperties: false - type: object properties: id: type: string format: uuid description: >- Identifier of this resource. Use the value returned by the API for subsequent lookups. type: type: string enum: - audio description: >- Discriminator describing this block or incident. Render according to the allowed values. assetId: type: string format: uuid description: >- Media asset identifier. Resolve a published rendition through the record's media list. caption: type: string maxLength: 1000 description: Public caption for this media block. required: - id - type - assetId - caption additionalProperties: false - type: object properties: id: type: string format: uuid description: >- Identifier of this resource. Use the value returned by the API for subsequent lookups. type: type: string enum: - video description: >- Discriminator describing this block or incident. Render according to the allowed values. assetId: type: string format: uuid description: >- Media asset identifier. Resolve a published rendition through the record's media list. caption: type: string maxLength: 1000 description: Public caption for this media block. required: - id - type - assetId - caption additionalProperties: false - type: object properties: id: type: string format: uuid description: >- Identifier of this resource. Use the value returned by the API for subsequent lookups. type: type: string enum: - embed description: >- Discriminator describing this block or incident. Render according to the allowed values. provider: type: string enum: - youtube - vimeo description: >- Configured push provider or embed provider; use the allowed values. externalId: type: string pattern: ^[A-Za-z0-9_-]{1,80}$ description: >- Identifier on the external embed provider. title: type: string minLength: 1 maxLength: 300 description: >- Human-readable title. Track titles come from external automation. required: - id - type - provider - externalId - title additionalProperties: false - type: object properties: id: type: string format: uuid description: >- Identifier of this resource. Use the value returned by the API for subsequent lookups. type: type: string enum: - related description: >- Discriminator describing this block or incident. Render according to the allowed values. recordIds: type: array items: type: string format: uuid minItems: 1 maxItems: 20 description: >- Related published content record identifiers. required: - id - type - recordIds additionalProperties: false example: id: 8c024c8e-0536-4a80-b3dc-b56580259efe type: text content: - text: >- The riverside festival opens on Saturday. marks: [] maxItems: 100 description: >- Ordered editorial blocks, such as text, heading, image, audio, or related records. example: - id: 8c024c8e-0536-4a80-b3dc-b56580259efe type: text content: - text: >- The riverside festival opens on Saturday. marks: [] required: - version - mode - blocks additionalProperties: false description: >- Structured public editorial document. Render blocks according to their type. example: version: 1 mode: document blocks: - id: 8c024c8e-0536-4a80-b3dc-b56580259efe type: text content: - text: The riverside festival opens on Saturday. marks: [] media: type: array items: type: object properties: assetId: type: string format: uuid description: >- Media asset identifier. Resolve a published rendition through the record's media list. example: 645b3141-69f9-439a-8d98-185439063b39 versionId: type: string format: uuid description: >- Published media version identifier used in public media URLs. example: a6286c77-6253-433b-80e9-38aed5d72a60 kind: type: string enum: - image - audio - video description: >- Field or media kind. Use the allowed values to select the appropriate renderer. example: image url: type: string description: >- Public delivery URL. Published media bytes do not require a listener token. example: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60 credits: type: string description: Public media attribution. example: Radio Rivier mime: type: string description: Media MIME type, for example image/jpeg. example: image/jpeg alt: type: string default: '' description: >- Alternative text for accessible image rendering. example: >- Stage on the riverbank before the festival opens width: type: - number - 'null' default: null description: Image width in pixels; null when unknown. example: 2400 height: type: - number - 'null' default: null description: Image height in pixels; null when unknown. example: 1600 duration: type: - number - 'null' default: null description: >- Legacy alias of durationSeconds. If both are provided, their values must match. example: null variants: type: object properties: thumb: type: - string - 'null' description: Thumbnail rendition, resized to width. example: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/thumb display: type: - string - 'null' description: Display rendition, resized to width. example: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/display card: type: - string - 'null' default: null description: 16:9 crop around the image's focal point. example: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/card square: type: - string - 'null' default: null description: >- Square crop around the image's focal point. example: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/square default: thumb: null display: null card: null square: null required: - thumb - display description: >- Public URLs of smaller image renditions for srcset. A rendition is null when it is not available. example: thumb: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/thumb display: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/display card: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/card square: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/square required: - assetId - versionId - kind - url - credits - mime example: assetId: 645b3141-69f9-439a-8d98-185439063b39 versionId: a6286c77-6253-433b-80e9-38aed5d72a60 kind: image url: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60 credits: Radio Rivier mime: image/jpeg alt: Stage on the riverbank before the festival opens width: 2400 height: 1600 duration: null variants: thumb: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/thumb display: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/display card: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/card square: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/square maxItems: 100 description: >- Published media projections referenced by this record. example: - assetId: 645b3141-69f9-439a-8d98-185439063b39 versionId: a6286c77-6253-433b-80e9-38aed5d72a60 kind: image url: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60 credits: Radio Rivier mime: image/jpeg alt: Stage on the riverbank before the festival opens width: 2400 height: 1600 duration: null variants: thumb: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/thumb display: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/display card: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/card square: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/square related: type: object properties: programIds: type: array items: type: string format: uuid example: 581497a3-e8b9-47ad-ade4-e1bf3895450a maxItems: 50 description: Identifiers of programs this record relates to. example: - 581497a3-e8b9-47ad-ade4-e1bf3895450a required: - programIds description: Station records linked to this record. example: programIds: - 581497a3-e8b9-47ad-ade4-e1bf3895450a required: - contractVersion - id - publicationId - revision - type - schemaVersion - publishedAt - values - document - media example: contractVersion: 1 id: 5b961af1-c305-4a1e-aed4-b3dfdc72be09 publicationId: 77de95e7-3382-468c-b34a-880491592ae6 revision: 3 type: news schemaVersion: 1 publishedAt: '2026-10-05T07:45:00.000Z' firstPublishedAt: '2026-10-05T07:30:00.000Z' values: headline: Riverside festival opens this weekend featured: true reading_minutes: 2 category: local event_at: '2026-10-10T10:00:00.000Z' document: version: 1 mode: document blocks: - id: 8c024c8e-0536-4a80-b3dc-b56580259efe type: text content: - text: The riverside festival opens on Saturday. marks: [] media: - assetId: 645b3141-69f9-439a-8d98-185439063b39 versionId: a6286c77-6253-433b-80e9-38aed5d72a60 kind: image url: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60 credits: Radio Rivier mime: image/jpeg alt: Stage on the riverbank before the festival opens width: 2400 height: 1600 duration: null variants: thumb: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/thumb display: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/display card: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/card square: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/square related: programIds: - 581497a3-e8b9-47ad-ade4-e1bf3895450a maxItems: 50 description: Published records matching the content type and filters. example: - contractVersion: 1 id: 5b961af1-c305-4a1e-aed4-b3dfdc72be09 publicationId: 77de95e7-3382-468c-b34a-880491592ae6 revision: 3 type: news schemaVersion: 1 publishedAt: '2026-10-05T07:45:00.000Z' firstPublishedAt: '2026-10-05T07:30:00.000Z' values: headline: Riverside festival opens this weekend featured: true reading_minutes: 2 category: local event_at: '2026-10-10T10:00:00.000Z' document: version: 1 mode: document blocks: - id: 8c024c8e-0536-4a80-b3dc-b56580259efe type: text content: - text: The riverside festival opens on Saturday. marks: [] media: - assetId: 645b3141-69f9-439a-8d98-185439063b39 versionId: a6286c77-6253-433b-80e9-38aed5d72a60 kind: image url: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60 credits: Radio Rivier mime: image/jpeg alt: Stage on the riverbank before the festival opens width: 2400 height: 1600 duration: null variants: thumb: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/thumb display: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/display card: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/card square: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/square related: programIds: - 581497a3-e8b9-47ad-ade4-e1bf3895450a nextCursor: type: - string - 'null' maxLength: 400 description: >- Continuation cursor for the next page; null means there are no more items. Do not construct or decode it. example: null page: type: object properties: limit: type: integer minimum: 1 maximum: 50 description: Maximum items requested per page. example: 25 nextCursor: type: - string - 'null' maxLength: 400 description: >- Continuation cursor for the next page; null means there are no more items. Do not construct or decode it. example: null required: - limit - nextCursor description: Content pagination metadata. example: limit: 25 nextCursor: null required: - contractVersion - type - records - nextCursor - page example: contractVersion: 1 type: news records: - contractVersion: 1 id: 5b961af1-c305-4a1e-aed4-b3dfdc72be09 publicationId: 77de95e7-3382-468c-b34a-880491592ae6 revision: 3 type: news schemaVersion: 1 publishedAt: '2026-10-05T07:45:00.000Z' firstPublishedAt: '2026-10-05T07:30:00.000Z' values: headline: Riverside festival opens this weekend featured: true reading_minutes: 2 category: local event_at: '2026-10-10T10:00:00.000Z' document: version: 1 mode: document blocks: - id: 8c024c8e-0536-4a80-b3dc-b56580259efe type: text content: - text: The riverside festival opens on Saturday. marks: [] media: - assetId: 645b3141-69f9-439a-8d98-185439063b39 versionId: a6286c77-6253-433b-80e9-38aed5d72a60 kind: image url: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60 credits: Radio Rivier mime: image/jpeg alt: Stage on the riverbank before the festival opens width: 2400 height: 1600 duration: null variants: thumb: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/thumb display: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/display card: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/card square: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/square related: programIds: - 581497a3-e8b9-47ad-ade4-e1bf3895450a nextCursor: null page: limit: 25 nextCursor: null examples: page: summary: Published news page description: >- Illustrative response using fictional station data. Replace identifiers with values returned by your station. value: contractVersion: 1 type: news records: - contractVersion: 1 id: 5b961af1-c305-4a1e-aed4-b3dfdc72be09 publicationId: 77de95e7-3382-468c-b34a-880491592ae6 revision: 3 type: news schemaVersion: 1 publishedAt: '2026-10-05T07:45:00.000Z' firstPublishedAt: '2026-10-05T07:30:00.000Z' values: headline: Riverside festival opens this weekend featured: true reading_minutes: 2 category: local event_at: '2026-10-10T10:00:00.000Z' document: version: 1 mode: document blocks: - id: 8c024c8e-0536-4a80-b3dc-b56580259efe type: text content: - text: The riverside festival opens on Saturday. marks: [] media: - assetId: 645b3141-69f9-439a-8d98-185439063b39 versionId: a6286c77-6253-433b-80e9-38aed5d72a60 kind: image url: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60 credits: Radio Rivier mime: image/jpeg alt: Stage on the riverbank before the festival opens width: 2400 height: 1600 duration: null variants: thumb: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/thumb display: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/display card: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/card square: >- /api/media/public/station-rivier/a6286c77-6253-433b-80e9-38aed5d72a60/square related: programIds: - 581497a3-e8b9-47ad-ade4-e1bf3895450a nextCursor: null page: limit: 25 nextCursor: null empty: summary: No matching records description: >- Illustrative response using fictional station data. Replace identifiers with values returned by your station. value: contractVersion: 1 type: news records: [] nextCursor: null page: limit: 25 nextCursor: null '400': description: The request contains invalid parameters or input. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - UNAUTHENTICATED - FORBIDDEN - VALIDATION_ERROR - NOT_FOUND - MODULE_DISABLED - METHOD_NOT_ALLOWED - REVISION_CONFLICT - IDEMPOTENCY_CONFLICT - RATE_LIMITED - PROVIDER_UNAVAILABLE - INTERNAL_ERROR description: >- Machine-readable code. Error codes are stable; road codes identify the watched road. example: VALIDATION_ERROR message: type: string description: >- Human-readable explanation; branch on the stable error code instead of this text. example: The request contains invalid parameters or input. requestId: type: string format: uuid description: >- Request trace identifier. Include this value or the x-request-id header when reporting an issue. example: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 issues: type: array items: type: object properties: path: type: string description: Path of the input field that failed validation. example: query message: type: string description: >- Human-readable explanation; branch on the stable error code instead of this text. example: >- Check the parameter types and bounds documented for this operation. code: type: string maxLength: 64 description: >- Machine-readable code. Error codes are stable; road codes identify the watched road. suggestion: type: string maxLength: 200 description: Short suggested fix you can show to the user. retryAfter: type: integer minimum: 1 maximum: 86400 description: >- Seconds to wait before retrying, when the issue is temporary. required: - path - message example: path: query message: >- Check the parameter types and bounds documented for this operation. description: Optional field validation details. example: - path: query message: >- Check the parameter types and bounds documented for this operation. required: - code - message - requestId description: >- Error details. Listener errors are structured; playback ingest uses a legacy error string. example: code: VALIDATION_ERROR message: The request contains invalid parameters or input. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 issues: - path: query message: >- Check the parameter types and bounds documented for this operation. required: - error example: error: code: VALIDATION_ERROR message: The request contains invalid parameters or input. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 issues: - path: query message: >- Check the parameter types and bounds documented for this operation. examples: error: summary: 400 VALIDATION_ERROR value: error: code: VALIDATION_ERROR message: The request contains invalid parameters or input. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 issues: - path: query message: >- Check the parameter types and bounds documented for this operation. '401': description: A valid station credential with the required scope is needed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - UNAUTHENTICATED - FORBIDDEN - VALIDATION_ERROR - NOT_FOUND - MODULE_DISABLED - METHOD_NOT_ALLOWED - REVISION_CONFLICT - IDEMPOTENCY_CONFLICT - RATE_LIMITED - PROVIDER_UNAVAILABLE - INTERNAL_ERROR description: >- Machine-readable code. Error codes are stable; road codes identify the watched road. example: UNAUTHENTICATED message: type: string description: >- Human-readable explanation; branch on the stable error code instead of this text. example: >- A valid station credential with the required scope is needed. requestId: type: string format: uuid description: >- Request trace identifier. Include this value or the x-request-id header when reporting an issue. example: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 issues: type: array items: type: object properties: path: type: string description: Path of the input field that failed validation. message: type: string description: >- Human-readable explanation; branch on the stable error code instead of this text. code: type: string maxLength: 64 description: >- Machine-readable code. Error codes are stable; road codes identify the watched road. suggestion: type: string maxLength: 200 description: Short suggested fix you can show to the user. retryAfter: type: integer minimum: 1 maximum: 86400 description: >- Seconds to wait before retrying, when the issue is temporary. required: - path - message description: Optional field validation details. required: - code - message - requestId description: >- Error details. Listener errors are structured; playback ingest uses a legacy error string. example: code: UNAUTHENTICATED message: >- A valid station credential with the required scope is needed. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 required: - error example: error: code: UNAUTHENTICATED message: >- A valid station credential with the required scope is needed. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 examples: error: summary: 401 UNAUTHENTICATED value: error: code: UNAUTHENTICATED message: >- A valid station credential with the required scope is needed. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 '403': description: The credential does not permit this operation. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - UNAUTHENTICATED - FORBIDDEN - VALIDATION_ERROR - NOT_FOUND - MODULE_DISABLED - METHOD_NOT_ALLOWED - REVISION_CONFLICT - IDEMPOTENCY_CONFLICT - RATE_LIMITED - PROVIDER_UNAVAILABLE - INTERNAL_ERROR description: >- Machine-readable code. Error codes are stable; road codes identify the watched road. example: FORBIDDEN message: type: string description: >- Human-readable explanation; branch on the stable error code instead of this text. example: The credential does not permit this operation. requestId: type: string format: uuid description: >- Request trace identifier. Include this value or the x-request-id header when reporting an issue. example: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 issues: type: array items: type: object properties: path: type: string description: Path of the input field that failed validation. message: type: string description: >- Human-readable explanation; branch on the stable error code instead of this text. code: type: string maxLength: 64 description: >- Machine-readable code. Error codes are stable; road codes identify the watched road. suggestion: type: string maxLength: 200 description: Short suggested fix you can show to the user. retryAfter: type: integer minimum: 1 maximum: 86400 description: >- Seconds to wait before retrying, when the issue is temporary. required: - path - message description: Optional field validation details. required: - code - message - requestId description: >- Error details. Listener errors are structured; playback ingest uses a legacy error string. example: code: FORBIDDEN message: The credential does not permit this operation. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 required: - error example: error: code: FORBIDDEN message: The credential does not permit this operation. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 examples: error: summary: 403 FORBIDDEN value: error: code: FORBIDDEN message: The credential does not permit this operation. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 '404': description: >- The resource is missing, unpublished, disabled, or unavailable for this station. A switched-off station module returns MODULE_DISABLED. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - UNAUTHENTICATED - FORBIDDEN - VALIDATION_ERROR - NOT_FOUND - MODULE_DISABLED - METHOD_NOT_ALLOWED - REVISION_CONFLICT - IDEMPOTENCY_CONFLICT - RATE_LIMITED - PROVIDER_UNAVAILABLE - INTERNAL_ERROR description: >- Machine-readable code. Error codes are stable; road codes identify the watched road. example: NOT_FOUND message: type: string description: >- Human-readable explanation; branch on the stable error code instead of this text. example: >- The resource is missing, unpublished, disabled, or unavailable for this station. A switched-off station module returns MODULE_DISABLED. requestId: type: string format: uuid description: >- Request trace identifier. Include this value or the x-request-id header when reporting an issue. example: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 issues: type: array items: type: object properties: path: type: string description: Path of the input field that failed validation. message: type: string description: >- Human-readable explanation; branch on the stable error code instead of this text. code: type: string maxLength: 64 description: >- Machine-readable code. Error codes are stable; road codes identify the watched road. suggestion: type: string maxLength: 200 description: Short suggested fix you can show to the user. retryAfter: type: integer minimum: 1 maximum: 86400 description: >- Seconds to wait before retrying, when the issue is temporary. required: - path - message description: Optional field validation details. required: - code - message - requestId description: >- Error details. Listener errors are structured; playback ingest uses a legacy error string. example: code: NOT_FOUND message: >- The resource is missing, unpublished, disabled, or unavailable for this station. A switched-off station module returns MODULE_DISABLED. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 required: - error example: error: code: NOT_FOUND message: >- The resource is missing, unpublished, disabled, or unavailable for this station. A switched-off station module returns MODULE_DISABLED. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 examples: error: summary: 404 NOT_FOUND value: error: code: NOT_FOUND message: >- The resource is missing, unpublished, disabled, or unavailable for this station. A switched-off station module returns MODULE_DISABLED. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 '409': description: The request conflicts with the current resource revision. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - UNAUTHENTICATED - FORBIDDEN - VALIDATION_ERROR - NOT_FOUND - MODULE_DISABLED - METHOD_NOT_ALLOWED - REVISION_CONFLICT - IDEMPOTENCY_CONFLICT - RATE_LIMITED - PROVIDER_UNAVAILABLE - INTERNAL_ERROR description: >- Machine-readable code. Error codes are stable; road codes identify the watched road. example: REVISION_CONFLICT message: type: string description: >- Human-readable explanation; branch on the stable error code instead of this text. example: >- The request conflicts with the current resource revision. requestId: type: string format: uuid description: >- Request trace identifier. Include this value or the x-request-id header when reporting an issue. example: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 issues: type: array items: type: object properties: path: type: string description: Path of the input field that failed validation. message: type: string description: >- Human-readable explanation; branch on the stable error code instead of this text. code: type: string maxLength: 64 description: >- Machine-readable code. Error codes are stable; road codes identify the watched road. suggestion: type: string maxLength: 200 description: Short suggested fix you can show to the user. retryAfter: type: integer minimum: 1 maximum: 86400 description: >- Seconds to wait before retrying, when the issue is temporary. required: - path - message description: Optional field validation details. required: - code - message - requestId description: >- Error details. Listener errors are structured; playback ingest uses a legacy error string. example: code: REVISION_CONFLICT message: >- The request conflicts with the current resource revision. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 required: - error example: error: code: REVISION_CONFLICT message: The request conflicts with the current resource revision. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 examples: error: summary: 409 REVISION_CONFLICT value: error: code: REVISION_CONFLICT message: >- The request conflicts with the current resource revision. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 '429': description: Too many requests. Reduce the request frequency. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - UNAUTHENTICATED - FORBIDDEN - VALIDATION_ERROR - NOT_FOUND - MODULE_DISABLED - METHOD_NOT_ALLOWED - REVISION_CONFLICT - IDEMPOTENCY_CONFLICT - RATE_LIMITED - PROVIDER_UNAVAILABLE - INTERNAL_ERROR description: >- Machine-readable code. Error codes are stable; road codes identify the watched road. example: RATE_LIMITED message: type: string description: >- Human-readable explanation; branch on the stable error code instead of this text. example: Too many requests. Reduce the request frequency. requestId: type: string format: uuid description: >- Request trace identifier. Include this value or the x-request-id header when reporting an issue. example: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 issues: type: array items: type: object properties: path: type: string description: Path of the input field that failed validation. message: type: string description: >- Human-readable explanation; branch on the stable error code instead of this text. code: type: string maxLength: 64 description: >- Machine-readable code. Error codes are stable; road codes identify the watched road. suggestion: type: string maxLength: 200 description: Short suggested fix you can show to the user. retryAfter: type: integer minimum: 1 maximum: 86400 description: >- Seconds to wait before retrying, when the issue is temporary. required: - path - message description: Optional field validation details. required: - code - message - requestId description: >- Error details. Listener errors are structured; playback ingest uses a legacy error string. example: code: RATE_LIMITED message: Too many requests. Reduce the request frequency. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 required: - error example: error: code: RATE_LIMITED message: Too many requests. Reduce the request frequency. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 examples: error: summary: 429 RATE_LIMITED value: error: code: RATE_LIMITED message: Too many requests. Reduce the request frequency. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 '503': description: An upstream service is temporarily unavailable. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - UNAUTHENTICATED - FORBIDDEN - VALIDATION_ERROR - NOT_FOUND - MODULE_DISABLED - METHOD_NOT_ALLOWED - REVISION_CONFLICT - IDEMPOTENCY_CONFLICT - RATE_LIMITED - PROVIDER_UNAVAILABLE - INTERNAL_ERROR description: >- Machine-readable code. Error codes are stable; road codes identify the watched road. example: PROVIDER_UNAVAILABLE message: type: string description: >- Human-readable explanation; branch on the stable error code instead of this text. example: An upstream service is temporarily unavailable. requestId: type: string format: uuid description: >- Request trace identifier. Include this value or the x-request-id header when reporting an issue. example: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 issues: type: array items: type: object properties: path: type: string description: Path of the input field that failed validation. message: type: string description: >- Human-readable explanation; branch on the stable error code instead of this text. code: type: string maxLength: 64 description: >- Machine-readable code. Error codes are stable; road codes identify the watched road. suggestion: type: string maxLength: 200 description: Short suggested fix you can show to the user. retryAfter: type: integer minimum: 1 maximum: 86400 description: >- Seconds to wait before retrying, when the issue is temporary. required: - path - message description: Optional field validation details. required: - code - message - requestId description: >- Error details. Listener errors are structured; playback ingest uses a legacy error string. example: code: PROVIDER_UNAVAILABLE message: An upstream service is temporarily unavailable. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 required: - error example: error: code: PROVIDER_UNAVAILABLE message: An upstream service is temporarily unavailable. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 examples: error: summary: 503 PROVIDER_UNAVAILABLE value: error: code: PROVIDER_UNAVAILABLE message: An upstream service is temporarily unavailable. requestId: 28e5d867-1f87-4ca7-bca9-4ebc09b36ba3 security: - machineToken: [] components: securitySchemes: machineToken: type: http scheme: bearer bearerFormat: rtm_… description: >- Station-scoped listener credential. Send Authorization: Bearer ``, for example Bearer rtm_…. Sending the rtm_ token alone without Bearer returns 401 UNAUTHENTICATED. In the interactive playground, enter only the raw rtm_ token; the playground adds the prefix. Listener REST and GraphQL: listener:read. Listener devices: push:register. ```` ## Related topics - [List content schemas](/radiotools/api-reference/public-listener/list-content-schemas.md) - [List programs](/radiotools/api-reference/public-listener/list-programs.md) - [List track history](/radiotools/api-reference/public-listener/list-track-history.md) - [Get content record](/radiotools/api-reference/public-listener/get-content-record.md) - [Content types](/radiotools/station-admin/content-types.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.