{ "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." }, "paths": { "/api/v1/stations/{stationSlug}/push/devices": { "patch": { "summary": "Update listener push topics", "description": "Turn alerts and content delivery on or off for a registered device. Unspecified topics keep their current setting. Turning a topic off retains the device token. Requires the same public station gate and push:register tenant credential as registration.", "security": [ { "machineToken": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 63 }, "required": true, "name": "stationSlug", "in": "path", "description": "Public station slug from the station settings; distinct from the internal station ID.", "example": "radio-rivier" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Push provider device token. This is not an API credential; never use a real device token in shared examples.", "example": "fictional-fcm-device-token" }, "topics": { "type": "object", "properties": { "alerts": { "type": "boolean", "description": "Whether this device receives station alerts.", "example": false }, "content": { "type": "boolean", "description": "Whether this device receives content notifications.", "example": true } }, "additionalProperties": false, "description": "Topic preferences to update. Omitted topics retain their existing setting.", "example": { "alerts": false, "content": true } } }, "required": [ "token", "topics" ], "additionalProperties": false, "example": { "token": "fictional-fcm-device-token", "topics": { "alerts": false, "content": true } } }, "examples": { "topics": { "summary": "Disable alerts, keep content enabled", "description": "Unspecified topics retain their current preference.", "value": { "token": "fictional-fcm-device-token", "topics": { "alerts": false, "content": true } } } } } } }, "responses": { "200": { "description": "Topic preferences updated; omitted topics are unchanged This imported contract does not specify a response body; treat the HTTP status as the documented result." }, "400": { "description": "Invalid topic update" }, "401": { "description": "Station credential missing or invalid" }, "404": { "description": "Station unavailable or device is not registered" } }, "tags": [ "Public listener" ], "x-mint": { "metadata": { "title": "Update push topics" }, "href": "/radiotools/api-reference/public-listener/update-push-topics" } }, "post": { "summary": "Register a listener push device", "description": "Requires a tenant-admin credential carrying push:register behind the active public station gate when a provider is configured. Provider must match the station configuration. The device token is stored station-scoped and never associated with a staff user.", "security": [ { "machineToken": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 63 }, "required": true, "name": "stationSlug", "in": "path", "description": "Public station slug from the station settings; distinct from the internal station ID.", "example": "radio-rivier" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Push provider device token. This is not an API credential; never use a real device token in shared examples.", "example": "fictional-fcm-device-token" }, "platform": { "type": "string", "enum": [ "ios", "android" ], "description": "Device operating system.", "example": "android" }, "provider": { "type": "string", "enum": [ "fcm", "apns", "expo" ], "description": "Configured push provider or embed provider; use the allowed values.", "example": "fcm" } }, "required": [ "token", "platform", "provider" ], "example": { "token": "fictional-fcm-device-token", "platform": "android", "provider": "fcm" } }, "examples": { "android": { "summary": "Register an Android device", "description": "Replace the fictional token with the device token from your push provider; the provider must match the station configuration.", "value": { "token": "fictional-fcm-device-token", "platform": "android", "provider": "fcm" } } } } } }, "responses": { "200": { "description": "Registered or refreshed the existing device token This imported contract does not specify a response body; treat the HTTP status as the documented result." }, "400": { "description": "Invalid registration body" }, "401": { "description": "Station credential missing or invalid" }, "404": { "description": "Station unavailable" }, "409": { "description": "Station has no configured provider or provider does not match" } }, "tags": [ "Public listener" ], "x-mint": { "metadata": { "title": "Register a push device" }, "href": "/radiotools/api-reference/public-listener/register-push-device" } }, "delete": { "summary": "Unregister a listener push device", "description": "Remove the supplied token from this station. Requires the public station gate or a station credential carrying push:register.", "security": [ { "machineToken": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 63 }, "required": true, "name": "stationSlug", "in": "path", "description": "Public station slug from the station settings; distinct from the internal station ID.", "example": "radio-rivier" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Push provider device token. This is not an API credential; never use a real device token in shared examples.", "example": "fictional-fcm-device-token" } }, "required": [ "token" ], "example": { "token": "fictional-fcm-device-token" } }, "examples": { "device": { "summary": "Remove a registered device", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "token": "fictional-fcm-device-token" } } } } } }, "responses": { "200": { "description": "Token removed if it was registered This imported contract does not specify a response body; treat the HTTP status as the documented result." }, "400": { "description": "Invalid unregister body" }, "401": { "description": "Station credential missing or invalid" }, "404": { "description": "Station unavailable" } }, "tags": [ "Public listener" ], "x-mint": { "metadata": { "title": "Unregister a push device" }, "href": "/radiotools/api-reference/public-listener/unregister-push-device" } } }, "/api/v1/stations/{stationSlug}/schemas": { "get": { "summary": "Delivery-safe schema definitions; historical versions require published snapshots", "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" }, "required": false, "name": "type", "in": "query", "description": "Stable published content type key returned by the schemas endpoint.", "example": "news" }, { "schema": { "type": "integer", "exclusiveMinimum": 0 }, "required": false, "name": "version", "in": "query", "description": "Published schema version to retrieve. Omit to use the endpoint's default version.", "example": 1 } ], "responses": { "200": { "description": "Safe definitions without private/system metadata", "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 }, "types": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$", "description": "Stable machine-readable key; use this value rather than the translated label.", "example": "news" }, "label": { "type": "string", "description": "Human-readable label for display.", "example": "News" }, "version": { "type": "integer", "exclusiveMinimum": 0, "description": "Version of this schema or structured document.", "example": 1 }, "archived": { "type": "boolean", "description": "Whether this content type is archived.", "example": false }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$", "description": "Stable machine-readable key; use this value rather than the translated label.", "example": "headline" }, "label": { "type": "string", "description": "Human-readable label for display.", "example": "Headline" }, "kind": { "type": "string", "enum": [ "text", "rich_text", "number", "boolean", "datetime", "choices", "media", "content", "group" ], "description": "Field or media kind. Use the allowed values to select the appropriate renderer.", "example": "text" }, "required": { "type": "boolean", "description": "Whether the content field requires a value in this schema version.", "example": true }, "maxLength": { "type": "number", "description": "Maximum permitted text length.", "example": 160 }, "min": { "type": "number", "description": "Minimum permitted numeric value." }, "max": { "type": "number", "description": "Maximum permitted numeric value." }, "choices": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$", "description": "Stable machine-readable key; use this value rather than the translated label." }, "label": { "type": "string", "description": "Human-readable label for display." } }, "required": [ "key", "label" ] }, "description": "Allowed choices with stable keys and display labels." }, "multiple": { "type": "boolean", "description": "Whether a choice field accepts more than one choice." }, "targetType": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$", "description": "Content type key referenced by this field." }, "maxItems": { "type": "number", "description": "Maximum number of entries in a repeated field." }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$", "description": "Stable machine-readable key; use this value rather than the translated label." }, "label": { "type": "string", "description": "Human-readable label for display." }, "kind": { "type": "string", "enum": [ "text", "rich_text", "number", "boolean", "datetime", "choices", "media", "content", "group" ], "description": "Field or media kind. Use the allowed values to select the appropriate renderer." }, "required": { "type": "boolean", "description": "Whether the content field requires a value in this schema version." }, "maxLength": { "type": "number", "description": "Maximum permitted text length." }, "min": { "type": "number", "description": "Minimum permitted numeric value." }, "max": { "type": "number", "description": "Maximum permitted numeric value." }, "choices": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$", "description": "Stable machine-readable key; use this value rather than the translated label." }, "label": { "type": "string", "description": "Human-readable label for display." } }, "required": [ "key", "label" ] }, "description": "Allowed choices with stable keys and display labels." }, "multiple": { "type": "boolean", "description": "Whether a choice field accepts more than one choice." }, "targetType": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$", "description": "Content type key referenced by this field." }, "maxItems": { "type": "number", "description": "Maximum number of entries in a repeated field." }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$", "description": "Stable machine-readable key; use this value rather than the translated label." }, "label": { "type": "string", "description": "Human-readable label for display." }, "kind": { "type": "string", "enum": [ "text", "rich_text", "number", "boolean", "datetime", "choices", "media", "content", "group" ], "description": "Field or media kind. Use the allowed values to select the appropriate renderer." }, "required": { "type": "boolean", "description": "Whether the content field requires a value in this schema version." }, "maxLength": { "type": "number", "description": "Maximum permitted text length." }, "min": { "type": "number", "description": "Minimum permitted numeric value." }, "max": { "type": "number", "description": "Maximum permitted numeric value." }, "choices": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$", "description": "Stable machine-readable key; use this value rather than the translated label." }, "label": { "type": "string", "description": "Human-readable label for display." } }, "required": [ "key", "label" ] }, "description": "Allowed choices with stable keys and display labels." }, "multiple": { "type": "boolean", "description": "Whether a choice field accepts more than one choice." }, "targetType": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$", "description": "Content type key referenced by this field." }, "maxItems": { "type": "number", "description": "Maximum number of entries in a repeated field." }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,47}$", "description": "Stable machine-readable key; use this value rather than the translated label." }, "label": { "type": "string", "description": "Human-readable label for display." }, "kind": { "type": "string", "enum": [ "text", "rich_text", "number", "boolean", "datetime", "choices", "media", "content", "group" ], "description": "Field or media kind. Use the allowed values to select the appropriate renderer." }, "required": { "type": "boolean", "description": "Whether the content field requires a value in this schema version." } }, "required": [ "key", "label", "kind", "required" ], "additionalProperties": false }, "maxItems": 0, "description": "Published field definitions. Private and system metadata are excluded." } }, "required": [ "key", "label", "kind", "required" ], "additionalProperties": false }, "description": "Published field definitions. Private and system metadata are excluded." } }, "required": [ "key", "label", "kind", "required" ], "additionalProperties": false }, "description": "Published field definitions. Private and system metadata are excluded." } }, "required": [ "key", "label", "kind", "required" ], "additionalProperties": false, "example": { "key": "headline", "label": "Headline", "kind": "text", "required": true, "maxLength": 160 } }, "description": "Published field definitions. Private and system metadata are excluded.", "example": [ { "key": "headline", "label": "Headline", "kind": "text", "required": true, "maxLength": 160 }, { "key": "featured", "label": "Featured", "kind": "boolean", "required": false }, { "key": "reading_minutes", "label": "Reading time", "kind": "number", "required": false, "min": 0, "max": 60 }, { "key": "category", "label": "Category", "kind": "choices", "required": true, "choices": [ { "key": "local", "label": "Local" }, { "key": "culture", "label": "Culture" } ] }, { "key": "event_at", "label": "Event time", "kind": "datetime", "required": false } ] } }, "required": [ "key", "label", "version", "archived", "fields" ], "example": { "key": "news", "label": "News", "version": 1, "archived": false, "fields": [ { "key": "headline", "label": "Headline", "kind": "text", "required": true, "maxLength": 160 }, { "key": "featured", "label": "Featured", "kind": "boolean", "required": false }, { "key": "reading_minutes", "label": "Reading time", "kind": "number", "required": false, "min": 0, "max": 60 }, { "key": "category", "label": "Category", "kind": "choices", "required": true, "choices": [ { "key": "local", "label": "Local" }, { "key": "culture", "label": "Culture" } ] }, { "key": "event_at", "label": "Event time", "kind": "datetime", "required": false } ] } }, "maxItems": 100, "description": "Published content type definitions available to this listener.", "example": [ { "key": "news", "label": "News", "version": 1, "archived": false, "fields": [ { "key": "headline", "label": "Headline", "kind": "text", "required": true, "maxLength": 160 }, { "key": "featured", "label": "Featured", "kind": "boolean", "required": false }, { "key": "reading_minutes", "label": "Reading time", "kind": "number", "required": false, "min": 0, "max": 60 }, { "key": "category", "label": "Category", "kind": "choices", "required": true, "choices": [ { "key": "local", "label": "Local" }, { "key": "culture", "label": "Culture" } ] }, { "key": "event_at", "label": "Event time", "kind": "datetime", "required": false } ] } ] } }, "required": [ "contractVersion", "types" ], "example": { "contractVersion": 1, "types": [ { "key": "news", "label": "News", "version": 1, "archived": false, "fields": [ { "key": "headline", "label": "Headline", "kind": "text", "required": true, "maxLength": 160 }, { "key": "featured", "label": "Featured", "kind": "boolean", "required": false }, { "key": "reading_minutes", "label": "Reading time", "kind": "number", "required": false, "min": 0, "max": 60 }, { "key": "category", "label": "Category", "kind": "choices", "required": true, "choices": [ { "key": "local", "label": "Local" }, { "key": "culture", "label": "Culture" } ] }, { "key": "event_at", "label": "Event time", "kind": "datetime", "required": false } ] } ] } }, "examples": { "news": { "summary": "Published news schema", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "types": [ { "key": "news", "label": "News", "version": 1, "archived": false, "fields": [ { "key": "headline", "label": "Headline", "kind": "text", "required": true, "maxLength": 160 }, { "key": "featured", "label": "Featured", "kind": "boolean", "required": false }, { "key": "reading_minutes", "label": "Reading time", "kind": "number", "required": false, "min": 0, "max": 60 }, { "key": "category", "label": "Category", "kind": "choices", "required": true, "choices": [ { "key": "local", "label": "Local" }, { "key": "culture", "label": "Culture" } ] }, { "key": "event_at", "label": "Event time", "kind": "datetime", "required": false } ] } ] } }, "empty": { "summary": "No published types", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "types": [] } } } } } }, "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" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "description": "Discover published content types and field definitions before rendering records. Use each field's key and kind; labels are for display. Private and system fields are excluded.", "x-mint": { "metadata": { "title": "List content schemas" }, "href": "/radiotools/api-reference/public-listener/list-content-schemas" } } }, "/api/media/public/{stationId}/{id}": { "get": { "summary": "Read authorized immutable bytes; supports a single Range, never shared-cacheable", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "stationId", "in": "path", "description": "Station ID associated with your credential. Send this or stationSlug, not both.", "example": "station-rivier" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path", "description": "Published media version UUID from the record's media list.", "example": "a6286c77-6253-433b-80e9-38aed5d72a60" } ], "responses": { "200": { "description": "Media bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Partial media bytes for one satisfiable Range request. Read Content-Range for the returned byte interval and total size; there is no JSON body." }, "400": { "description": "The request contains invalid parameters or input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "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" } }, "required": [ "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": { "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" } }, "required": [ "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": { "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" } }, "required": [ "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": { "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" } }, "required": [ "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": { "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" } }, "required": [ "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" } } } } } } }, "413": { "description": "Media request denied or unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable explanation; branch on the stable error code instead of this text." }, "requestId": { "type": "string", "format": "uuid", "description": "Request trace identifier. Include this value or the x-request-id header when reporting an issue." } }, "required": [ "message", "requestId" ], "description": "Error details. Listener errors are structured; playback ingest uses a legacy error string." } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests. Reduce the request frequency.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "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" } }, "required": [ "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": { "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" } }, "required": [ "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" } } } } } } } }, "tags": [ "Public listener" ], "security": [], "description": "Fetch published media bytes anonymously. The id is the published version UUID, not the asset ID. Only published media can be delivered. A single Range header can request part of the file; 206 returns bytes, not JSON.\n\nExample: `Range: bytes=0-1023`. Do not parse this response as JSON or store it in a shared cache.", "x-mint": { "metadata": { "title": "Get public media" }, "href": "/radiotools/api-reference/public-listener/get-public-media" } } }, "/api/media/public/{stationId}/{id}/{variant}": { "get": { "summary": "Read authorized immutable bytes; supports a single Range, never shared-cacheable", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "stationId", "in": "path", "description": "Station ID associated with your credential. Send this or stationSlug, not both.", "example": "station-rivier" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path", "description": "Published media version UUID from the record's media list.", "example": "a6286c77-6253-433b-80e9-38aed5d72a60" }, { "schema": { "type": "string", "enum": [ "thumb", "display", "card", "square" ] }, "required": true, "name": "variant", "in": "path", "description": "Published image rendition: thumb or display (resized to width), or card (16:9) or square, cropped around the image's focal point.", "example": "thumb" } ], "responses": { "200": { "description": "Media bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Partial media bytes for one satisfiable Range request. Read Content-Range for the returned byte interval and total size; there is no JSON body." }, "400": { "description": "The request contains invalid parameters or input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "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" } }, "required": [ "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": { "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" } }, "required": [ "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": { "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" } }, "required": [ "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": { "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" } }, "required": [ "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": { "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" } }, "required": [ "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" } } } } } } }, "413": { "description": "Media request denied or unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable explanation; branch on the stable error code instead of this text." }, "requestId": { "type": "string", "format": "uuid", "description": "Request trace identifier. Include this value or the x-request-id header when reporting an issue." } }, "required": [ "message", "requestId" ], "description": "Error details. Listener errors are structured; playback ingest uses a legacy error string." } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests. Reduce the request frequency.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "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" } }, "required": [ "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": { "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" } }, "required": [ "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" } } } } } } } }, "tags": [ "Public listener" ], "security": [], "description": "Fetch published media bytes anonymously. The id is the published version UUID, not the asset ID. Only published media can be delivered. A single Range header can request part of the file; 206 returns bytes, not JSON.\n\nExample: `Range: bytes=0-1023`. Do not parse this response as JSON or store it in a shared cache.", "x-mint": { "metadata": { "title": "Get public media variant" }, "href": "/radiotools/api-reference/public-listener/get-public-media-variant" } } }, "/api/v1/stations/{stationSlug}/content": { "get": { "summary": "Only live published snapshots; no-store and visibility-checked conditional ETag", "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" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "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.", "x-mint": { "metadata": { "title": "List content" }, "href": "/radiotools/api-reference/public-listener/list-content" } } }, "/api/v1/stations/{stationSlug}/content/{id}": { "get": { "summary": "Immutable published snapshot with frozen media and historical schema version", "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", "format": "uuid" }, "required": true, "name": "id", "in": "path", "description": "Published content record UUID.", "example": "5b961af1-c305-4a1e-aed4-b3dfdc72be09" } ], "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 }, "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" ] } } }, "examples": { "record": { "summary": "Published news record", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "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" ] } } } } } } }, "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" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "description": "Retrieve one published content record by its UUID. Interpret values using the matching type and schemaVersion and render the ordered document blocks. Unpublished or inaccessible records are not returned.", "x-mint": { "metadata": { "title": "Get content record" }, "href": "/radiotools/api-reference/public-listener/get-content-record" } } }, "/api/v1/stations/{stationSlug}/content/{type}/by-slug/{slug}": { "get": { "summary": "Published record by slug; a slug the record used before returns the record with its current values.slug", "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": "path", "description": "Stable published content type key returned by the schemas endpoint.", "example": "news" }, { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path", "description": "Record slug from the URL on your site. A slug the record used before still resolves; compare it with values.slug in the response.", "example": "riverside-festival-opens" } ], "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 }, "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", "slug": "riverside-festival-opens" } }, "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", "slug": "riverside-festival-opens" }, "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" ] } } }, "examples": { "record": { "summary": "Published news record", "description": "When you request a slug the record used before, the response is the same record. Compare values.slug with your URL and redirect to the current slug.", "value": { "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", "slug": "riverside-festival-opens" }, "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" ] } } } } } } }, "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" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "description": "Retrieve one published record of a content type by its slug, for routing website URLs. A slug the record used before returns the record with its current values.slug; redirect to the current slug when they differ. Only types with a slug field have slugs.", "x-mint": { "metadata": { "title": "Get content record by slug" }, "href": "/radiotools/api-reference/public-listener/get-content-record-by-slug" } } }, "/api/v1/stations/{stationSlug}/schedule.ics": { "get": { "summary": "Public schedule ICS feed", "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" } ], "responses": { "200": { "description": "iCalendar text (not JSON). Parse as a calendar feed; no-store.", "content": { "text/calendar": { "schema": { "type": "string" }, "examples": { "calendar": { "summary": "One calendar event", "value": "BEGIN:VCALENDAR\r\nVERSION:2.0\r\nPRODID:-//RadioTools//Example//EN\r\nBEGIN:VEVENT\r\nUID:faacbe14-ff20-444e-b1f0-09e8dad18cb0\r\nDTSTAMP:20261005T080000Z\r\nDTSTART:20261005T070000Z\r\nDTEND:20261005T100000Z\r\nSUMMARY:Rivier Morning\r\nEND:VEVENT\r\nEND:VCALENDAR\r\n" } } } } }, "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" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "description": "Subscribe to the station's published schedule as an iCalendar feed using the listener credential. The body is calendar text, not a JSON object. Keep credentials on your server; do not embed tokens in a calendar URL.", "x-mint": { "metadata": { "title": "Get schedule calendar feed" }, "href": "/radiotools/api-reference/public-listener/get-schedule-calendar-feed" } } }, "/api/v1/stations/{stationSlug}/programs": { "get": { "summary": "Program summaries projected from the public schedule window", "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", "format": "date" }, "required": true, "name": "fromDate", "in": "query", "description": "First calendar date in the requested window (YYYY-MM-DD). The window includes this day.", "example": "2026-10-05" }, { "schema": { "type": "string", "format": "date" }, "required": true, "name": "throughDate", "in": "query", "description": "Last calendar date in the requested window (YYYY-MM-DD). At most 31 inclusive days.", "example": "2026-10-11" } ], "responses": { "200": { "description": "Success; 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 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IANA timezone used to interpret station calendar dates, for example Europe/Amsterdam.", "example": "Europe/Amsterdam" }, "fromDate": { "type": "string", "format": "date", "description": "First date in the requested window, inclusive.", "example": "2026-10-05" }, "throughDate": { "type": "string", "format": "date", "description": "Last date in the requested window, inclusive.", "example": "2026-10-11" }, "programs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of this resource. Use the value returned by the API for subsequent lookups.", "example": "581497a3-e8b9-47ad-ade4-e1bf3895450a" }, "title": { "type": "string", "description": "Human-readable title. Track titles come from external automation.", "example": "Rivier Morning" }, "profileId": { "type": [ "string", "null" ], "format": "uuid", "description": "Linked public profile identifier, or null when there is no linked profile.", "example": null }, "presenters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of this resource. Use the value returned by the API for subsequent lookups.", "example": "94443b88-96b7-4813-8e9c-fd70dfbf8a04" }, "title": { "type": "string", "description": "Human-readable title. Track titles come from external automation.", "example": "Alex de Vries" } }, "required": [ "id", "title" ], "example": { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } }, "description": "Public presenter profiles for this broadcast.", "example": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] }, "slots": { "type": "array", "items": { "type": "object", "properties": { "weekday": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Day of the week, from 0 for Sunday to 6 for Saturday.", "example": 1 }, "startTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "Start time in the slot's timezone (HH:MM, 24-hour clock).", "example": "07:00" }, "durationMinutes": { "type": "integer", "minimum": 1, "maximum": 1440, "description": "Slot length in minutes.", "example": 180 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IANA timezone used to interpret station calendar dates, for example Europe/Amsterdam.", "example": "Europe/Amsterdam" }, "intervalWeeks": { "type": "integer", "minimum": 1, "maximum": 8, "description": "Number of weeks between occurrences; 1 means every week.", "example": 1 }, "fromDate": { "type": "string", "format": "date", "description": "First date in the requested window, inclusive.", "example": "2026-09-07" }, "throughDate": { "type": "string", "format": "date", "description": "Last date in the requested window, inclusive.", "example": "2026-12-20" }, "presenters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of this resource. Use the value returned by the API for subsequent lookups.", "example": "94443b88-96b7-4813-8e9c-fd70dfbf8a04" }, "title": { "type": "string", "description": "Human-readable title. Track titles come from external automation.", "example": "Alex de Vries" } }, "required": [ "id", "title" ], "example": { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } }, "description": "Public presenter profiles for this broadcast.", "example": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } }, "required": [ "weekday", "startTime", "durationMinutes", "timezone", "intervalWeeks", "fromDate", "throughDate", "presenters" ], "example": { "weekday": 1, "startTime": "07:00", "durationMinutes": 180, "timezone": "Europe/Amsterdam", "intervalWeeks": 1, "fromDate": "2026-09-07", "throughDate": "2026-12-20", "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } }, "maxItems": 100, "description": "Regular weekly slots of this program whose schedule overlaps the requested window.", "example": [ { "weekday": 1, "startTime": "07:00", "durationMinutes": 180, "timezone": "Europe/Amsterdam", "intervalWeeks": 1, "fromDate": "2026-09-07", "throughDate": "2026-12-20", "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } ] } }, "required": [ "id", "title", "profileId", "presenters", "slots" ], "example": { "id": "581497a3-e8b9-47ad-ade4-e1bf3895450a", "title": "Rivier Morning", "profileId": null, "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ], "slots": [ { "weekday": 1, "startTime": "07:00", "durationMinutes": 180, "timezone": "Europe/Amsterdam", "intervalWeeks": 1, "fromDate": "2026-09-07", "throughDate": "2026-12-20", "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } ] } }, "maxItems": 500, "description": "Public program summaries in the selected date window.", "example": [ { "id": "581497a3-e8b9-47ad-ade4-e1bf3895450a", "title": "Rivier Morning", "profileId": null, "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ], "slots": [ { "weekday": 1, "startTime": "07:00", "durationMinutes": 180, "timezone": "Europe/Amsterdam", "intervalWeeks": 1, "fromDate": "2026-09-07", "throughDate": "2026-12-20", "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } ] } ] }, "truncated": { "type": "boolean", "description": "True when the result was capped. Request a smaller date window to retrieve remaining data.", "example": false } }, "required": [ "contractVersion", "timezone", "fromDate", "throughDate", "programs", "truncated" ], "example": { "contractVersion": 1, "timezone": "Europe/Amsterdam", "fromDate": "2026-10-05", "throughDate": "2026-10-11", "programs": [ { "id": "581497a3-e8b9-47ad-ade4-e1bf3895450a", "title": "Rivier Morning", "profileId": null, "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ], "slots": [ { "weekday": 1, "startTime": "07:00", "durationMinutes": 180, "timezone": "Europe/Amsterdam", "intervalWeeks": 1, "fromDate": "2026-09-07", "throughDate": "2026-12-20", "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } ] } ], "truncated": false } }, "examples": { "programs": { "summary": "Programs in the requested window", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "timezone": "Europe/Amsterdam", "fromDate": "2026-10-05", "throughDate": "2026-10-11", "programs": [ { "id": "581497a3-e8b9-47ad-ade4-e1bf3895450a", "title": "Rivier Morning", "profileId": null, "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ], "slots": [ { "weekday": 1, "startTime": "07:00", "durationMinutes": 180, "timezone": "Europe/Amsterdam", "intervalWeeks": 1, "fromDate": "2026-09-07", "throughDate": "2026-12-20", "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } ] } ], "truncated": false } } } } } }, "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" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "description": "Retrieve public program summaries for the requested inclusive date window. The window is limited to 31 days; narrow it when truncated is true.", "x-mint": { "metadata": { "title": "List programs" }, "href": "/radiotools/api-reference/public-listener/list-programs" } } }, "/api/v1/stations/{stationSlug}/broadcast/current": { "get": { "summary": "Current or live broadcast derived from public schedule data only", "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" } ], "responses": { "200": { "description": "Success; 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 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IANA timezone used to interpret station calendar dates, for example Europe/Amsterdam.", "example": "Europe/Amsterdam" }, "asOf": { "type": "string", "format": "date-time", "description": "Timestamp at which this projection or reading applies.", "example": "2026-10-05T08:00:30.000Z" }, "broadcast": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of this resource. Use the value returned by the API for subsequent lookups.", "example": "faacbe14-ff20-444e-b1f0-09e8dad18cb0" }, "title": { "type": "string", "description": "Human-readable title. Track titles come from external automation.", "example": "Rivier Morning" }, "startsAt": { "type": "string", "format": "date-time", "description": "Scheduled start timestamp, including timezone offset or UTC suffix.", "example": "2026-10-05T07:00:00.000Z" }, "endsAt": { "type": "string", "format": "date-time", "description": "End timestamp. For now-playing this is derived from observedAt and durationSeconds; null when duration is unknown or the track is not playing.", "example": "2026-10-05T10:00:00.000Z" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IANA timezone used to interpret station calendar dates, for example Europe/Amsterdam.", "example": "Europe/Amsterdam" }, "localDate": { "type": "string", "format": "date", "description": "Broadcast calendar date in the station timezone (YYYY-MM-DD).", "example": "2026-10-05" }, "resolution": { "type": "string", "description": "Schedule time-resolution metadata returned by the API.", "example": "exact" }, "status": { "type": "string", "enum": [ "scheduled", "cancelled", "live", "completed" ], "description": "Public broadcast lifecycle status.", "example": "live" }, "cancellationReason": { "type": "string", "description": "Cancellation explanation, when supplied.", "example": "" }, "repeatOfId": { "type": [ "string", "null" ], "format": "uuid", "description": "Original broadcast identifier for a repeat; null for a non-repeat.", "example": null }, "nature": { "type": "string", "enum": [ "live", "prerecorded", "repeat" ], "default": "live", "description": "How the broadcast is made: live, prerecorded, or repeat.", "example": "live" }, "program": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of this resource. Use the value returned by the API for subsequent lookups.", "example": "581497a3-e8b9-47ad-ade4-e1bf3895450a" }, "title": { "type": "string", "description": "Human-readable title. Track titles come from external automation.", "example": "Rivier Morning" }, "profileId": { "type": [ "string", "null" ], "format": "uuid", "description": "Linked public profile identifier, or null when there is no linked profile.", "example": null } }, "required": [ "id", "title", "profileId" ], "description": "Public program associated with this broadcast.", "example": { "id": "581497a3-e8b9-47ad-ade4-e1bf3895450a", "title": "Rivier Morning", "profileId": null } }, "presenters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of this resource. Use the value returned by the API for subsequent lookups.", "example": "94443b88-96b7-4813-8e9c-fd70dfbf8a04" }, "title": { "type": "string", "description": "Human-readable title. Track titles come from external automation.", "example": "Alex de Vries" } }, "required": [ "id", "title" ], "example": { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } }, "description": "Public presenter profiles for this broadcast.", "example": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } }, "required": [ "id", "title", "startsAt", "endsAt", "timezone", "localDate", "resolution", "status", "cancellationReason", "repeatOfId", "program", "presenters" ], "description": "Current public broadcast; null when no broadcast is current.", "example": { "id": "faacbe14-ff20-444e-b1f0-09e8dad18cb0", "title": "Rivier Morning", "startsAt": "2026-10-05T07:00:00.000Z", "endsAt": "2026-10-05T10:00:00.000Z", "timezone": "Europe/Amsterdam", "localDate": "2026-10-05", "resolution": "exact", "status": "live", "cancellationReason": "", "repeatOfId": null, "nature": "live", "program": { "id": "581497a3-e8b9-47ad-ade4-e1bf3895450a", "title": "Rivier Morning", "profileId": null }, "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } } }, "required": [ "contractVersion", "timezone", "asOf", "broadcast" ], "example": { "contractVersion": 1, "timezone": "Europe/Amsterdam", "asOf": "2026-10-05T08:00:30.000Z", "broadcast": { "id": "faacbe14-ff20-444e-b1f0-09e8dad18cb0", "title": "Rivier Morning", "startsAt": "2026-10-05T07:00:00.000Z", "endsAt": "2026-10-05T10:00:00.000Z", "timezone": "Europe/Amsterdam", "localDate": "2026-10-05", "resolution": "exact", "status": "live", "cancellationReason": "", "repeatOfId": null, "nature": "live", "program": { "id": "581497a3-e8b9-47ad-ade4-e1bf3895450a", "title": "Rivier Morning", "profileId": null }, "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } } }, "examples": { "current": { "summary": "Current broadcast", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "timezone": "Europe/Amsterdam", "asOf": "2026-10-05T08:00:30.000Z", "broadcast": { "id": "faacbe14-ff20-444e-b1f0-09e8dad18cb0", "title": "Rivier Morning", "startsAt": "2026-10-05T07:00:00.000Z", "endsAt": "2026-10-05T10:00:00.000Z", "timezone": "Europe/Amsterdam", "localDate": "2026-10-05", "resolution": "exact", "status": "live", "cancellationReason": "", "repeatOfId": null, "nature": "live", "program": { "id": "581497a3-e8b9-47ad-ade4-e1bf3895450a", "title": "Rivier Morning", "profileId": null }, "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } } }, "empty": { "summary": "No current broadcast", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "timezone": "Europe/Amsterdam", "asOf": "2026-10-05T08:00:30.000Z", "broadcast": 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" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "description": "Read the current public broadcast. A successful response may contain broadcast: null when nothing is current; this is an empty state rather than an HTTP error.", "x-mint": { "metadata": { "title": "Get current broadcast" }, "href": "/radiotools/api-reference/public-listener/get-current-broadcast" } } }, "/api/v1/stations/{stationSlug}/schedule": { "get": { "summary": "Public schedule without internal assignments or preparation", "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", "format": "date" }, "required": true, "name": "fromDate", "in": "query", "description": "First calendar date in the requested window (YYYY-MM-DD). The window includes this day.", "example": "2026-10-05" }, { "schema": { "type": "string", "format": "date" }, "required": true, "name": "throughDate", "in": "query", "description": "Last calendar date in the requested window (YYYY-MM-DD). At most 31 inclusive days.", "example": "2026-10-11" } ], "responses": { "200": { "description": "Success; 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 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IANA timezone used to interpret station calendar dates, for example Europe/Amsterdam.", "example": "Europe/Amsterdam" }, "broadcasts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of this resource. Use the value returned by the API for subsequent lookups.", "example": "faacbe14-ff20-444e-b1f0-09e8dad18cb0" }, "title": { "type": "string", "description": "Human-readable title. Track titles come from external automation.", "example": "Rivier Morning" }, "startsAt": { "type": "string", "format": "date-time", "description": "Scheduled start timestamp, including timezone offset or UTC suffix.", "example": "2026-10-05T07:00:00.000Z" }, "endsAt": { "type": "string", "format": "date-time", "description": "End timestamp. For now-playing this is derived from observedAt and durationSeconds; null when duration is unknown or the track is not playing.", "example": "2026-10-05T10:00:00.000Z" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IANA timezone used to interpret station calendar dates, for example Europe/Amsterdam.", "example": "Europe/Amsterdam" }, "localDate": { "type": "string", "format": "date", "description": "Broadcast calendar date in the station timezone (YYYY-MM-DD).", "example": "2026-10-05" }, "resolution": { "type": "string", "description": "Schedule time-resolution metadata returned by the API.", "example": "exact" }, "status": { "type": "string", "enum": [ "scheduled", "cancelled", "live", "completed" ], "description": "Public broadcast lifecycle status.", "example": "live" }, "cancellationReason": { "type": "string", "description": "Cancellation explanation, when supplied.", "example": "" }, "repeatOfId": { "type": [ "string", "null" ], "format": "uuid", "description": "Original broadcast identifier for a repeat; null for a non-repeat.", "example": null }, "nature": { "type": "string", "enum": [ "live", "prerecorded", "repeat" ], "default": "live", "description": "How the broadcast is made: live, prerecorded, or repeat.", "example": "live" }, "program": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of this resource. Use the value returned by the API for subsequent lookups.", "example": "581497a3-e8b9-47ad-ade4-e1bf3895450a" }, "title": { "type": "string", "description": "Human-readable title. Track titles come from external automation.", "example": "Rivier Morning" }, "profileId": { "type": [ "string", "null" ], "format": "uuid", "description": "Linked public profile identifier, or null when there is no linked profile.", "example": null } }, "required": [ "id", "title", "profileId" ], "description": "Public program associated with this broadcast.", "example": { "id": "581497a3-e8b9-47ad-ade4-e1bf3895450a", "title": "Rivier Morning", "profileId": null } }, "presenters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of this resource. Use the value returned by the API for subsequent lookups.", "example": "94443b88-96b7-4813-8e9c-fd70dfbf8a04" }, "title": { "type": "string", "description": "Human-readable title. Track titles come from external automation.", "example": "Alex de Vries" } }, "required": [ "id", "title" ], "example": { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } }, "description": "Public presenter profiles for this broadcast.", "example": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } }, "required": [ "id", "title", "startsAt", "endsAt", "timezone", "localDate", "resolution", "status", "cancellationReason", "repeatOfId", "program", "presenters" ], "example": { "id": "faacbe14-ff20-444e-b1f0-09e8dad18cb0", "title": "Rivier Morning", "startsAt": "2026-10-05T07:00:00.000Z", "endsAt": "2026-10-05T10:00:00.000Z", "timezone": "Europe/Amsterdam", "localDate": "2026-10-05", "resolution": "exact", "status": "live", "cancellationReason": "", "repeatOfId": null, "nature": "live", "program": { "id": "581497a3-e8b9-47ad-ade4-e1bf3895450a", "title": "Rivier Morning", "profileId": null }, "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } }, "description": "Public broadcasts in the selected date window.", "example": [ { "id": "faacbe14-ff20-444e-b1f0-09e8dad18cb0", "title": "Rivier Morning", "startsAt": "2026-10-05T07:00:00.000Z", "endsAt": "2026-10-05T10:00:00.000Z", "timezone": "Europe/Amsterdam", "localDate": "2026-10-05", "resolution": "exact", "status": "live", "cancellationReason": "", "repeatOfId": null, "nature": "live", "program": { "id": "581497a3-e8b9-47ad-ade4-e1bf3895450a", "title": "Rivier Morning", "profileId": null }, "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } ] }, "truncated": { "type": "boolean", "description": "True when the result was capped. Request a smaller date window to retrieve remaining data.", "example": false } }, "required": [ "contractVersion", "timezone", "broadcasts", "truncated" ], "example": { "contractVersion": 1, "timezone": "Europe/Amsterdam", "broadcasts": [ { "id": "faacbe14-ff20-444e-b1f0-09e8dad18cb0", "title": "Rivier Morning", "startsAt": "2026-10-05T07:00:00.000Z", "endsAt": "2026-10-05T10:00:00.000Z", "timezone": "Europe/Amsterdam", "localDate": "2026-10-05", "resolution": "exact", "status": "live", "cancellationReason": "", "repeatOfId": null, "nature": "live", "program": { "id": "581497a3-e8b9-47ad-ade4-e1bf3895450a", "title": "Rivier Morning", "profileId": null }, "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } ], "truncated": false } }, "examples": { "schedule": { "summary": "One broadcast in the requested window", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "timezone": "Europe/Amsterdam", "broadcasts": [ { "id": "faacbe14-ff20-444e-b1f0-09e8dad18cb0", "title": "Rivier Morning", "startsAt": "2026-10-05T07:00:00.000Z", "endsAt": "2026-10-05T10:00:00.000Z", "timezone": "Europe/Amsterdam", "localDate": "2026-10-05", "resolution": "exact", "status": "live", "cancellationReason": "", "repeatOfId": null, "nature": "live", "program": { "id": "581497a3-e8b9-47ad-ade4-e1bf3895450a", "title": "Rivier Morning", "profileId": null }, "presenters": [ { "id": "94443b88-96b7-4813-8e9c-fd70dfbf8a04", "title": "Alex de Vries" } ] } ], "truncated": false } }, "empty": { "summary": "No broadcasts in the requested window", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "timezone": "Europe/Amsterdam", "broadcasts": [], "truncated": false } } } } } }, "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" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "description": "Retrieve public broadcasts for an inclusive date window of at most 31 days and at most 1000 broadcasts. Timestamps include their offset; localDate uses the station timezone. A true truncated flag means the window should be narrowed.", "x-mint": { "metadata": { "title": "Get schedule" }, "href": "/radiotools/api-reference/public-listener/get-schedule" } } }, "/api/v1/stations/{stationSlug}/weather": { "get": { "summary": "Public weather when redistribution entitlement is recorded", "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 63 }, "required": true, "name": "stationSlug", "in": "path", "description": "Public station slug from the station settings; distinct from the internal station ID.", "example": "radio-rivier" } ], "responses": { "200": { "description": "Normalized weather; no-store so revocation applies on the next read", "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 }, "stationId": { "type": "string", "description": "Station identifier associated with this response.", "example": "station-rivier" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IANA timezone used to interpret station calendar dates, for example Europe/Amsterdam.", "example": "Europe/Amsterdam" }, "snapshots": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "open-meteo" ], "description": "Source provider for this normalized observation.", "example": "open-meteo" }, "coverage": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2}:[a-z0-9][a-z0-9_-]{0,62}$", "description": "Identifier of this resource. Use the value returned by the API for subsequent lookups.", "example": "nl:noordwest" }, "name": { "type": "string", "description": "Human-readable display name.", "example": "Noordwest" }, "countryCode": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Lowercase country code of the coverage area, for example nl.", "example": "nl" }, "countryName": { "type": "string", "description": "Country display name.", "example": "Netherlands" }, "latitude": { "type": "number", "description": "Latitude in decimal degrees.", "example": 52.65 }, "longitude": { "type": "number", "description": "Longitude in decimal degrees.", "example": 4.75 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IANA timezone used to interpret station calendar dates, for example Europe/Amsterdam.", "example": "Europe/Amsterdam" } }, "required": [ "id", "name", "countryCode", "countryName", "latitude", "longitude", "timezone" ], "additionalProperties": false, "description": "Geographic location of this weather snapshot.", "example": { "id": "nl:noordwest", "name": "Noordwest", "countryCode": "nl", "countryName": "Netherlands", "latitude": 52.65, "longitude": 4.75, "timezone": "Europe/Amsterdam" } }, "freshness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fresh", "stale", "unavailable", "empty" ], "description": "Freshness classification of the source data. Handle stale, empty, or unavailable data explicitly.", "example": "fresh" }, "thresholdSeconds": { "type": "integer", "exclusiveMinimum": 0, "description": "Age threshold in seconds used to classify an observation as stale.", "example": 900 }, "ageSeconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Observation age in seconds; null when no observation is available.", "example": 30 }, "fetchedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the provider fetch; null when unavailable.", "example": "2026-10-05T08:00:01.000Z" }, "observedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the source observation occurred. Listener responses use ISO 8601 timestamps.", "example": "2026-10-05T08:00:00.000Z" }, "lastError": { "type": [ "string", "null" ], "description": "Latest provider error summary, or null when no error is recorded.", "example": null } }, "required": [ "status", "thresholdSeconds", "ageSeconds", "fetchedAt", "observedAt", "lastError" ], "additionalProperties": false, "description": "Age and freshness of the source observation. A successful HTTP read does not guarantee fresh data.", "example": { "status": "fresh", "thresholdSeconds": 900, "ageSeconds": 30, "fetchedAt": "2026-10-05T08:00:01.000Z", "observedAt": "2026-10-05T08:00:00.000Z", "lastError": null } }, "current": { "type": [ "object", "null" ], "properties": { "asOf": { "type": "string", "format": "date-time", "description": "Timestamp at which this projection or reading applies.", "example": "2026-10-05T08:00:00.000Z" }, "conditionCode": { "type": "string", "enum": [ "Clear", "MostlyClear", "PartlyCloudy", "Cloudy", "Fog", "Drizzle", "FreezingDrizzle", "Rain", "HeavyRain", "FreezingRain", "Snow", "HeavySnow", "Flurries", "Showers", "SnowShowers", "Thunderstorm", "SevereThunderstorm" ], "description": "Normalized weather condition; use the listed enum values for icons and labels.", "example": "PartlyCloudy" }, "daylight": { "type": "boolean", "description": "Whether this reading is during daylight.", "example": true }, "precipitation": { "type": "number", "description": "Precipitation amount for the reading, in millimeters.", "example": 0 }, "temperature": { "type": "number", "description": "Air temperature in degrees Celsius.", "example": 16.5 }, "temperatureApparent": { "type": "number", "description": "Feels-like temperature in degrees Celsius.", "example": 15.8 }, "uvIndex": { "type": "number", "description": "UV index for the reading or forecast period.", "example": 2 }, "windDirection": { "type": "number", "description": "Wind direction in degrees.", "example": 225 }, "windGust": { "type": "number", "description": "Wind gust speed in kilometers per hour.", "example": 24 }, "windSpeed": { "type": "number", "description": "Wind speed in kilometers per hour.", "example": 14 } }, "required": [ "asOf", "conditionCode", "daylight", "precipitation", "temperature", "temperatureApparent", "uvIndex", "windDirection", "windGust", "windSpeed" ], "additionalProperties": false, "description": "Current weather reading, or null when unavailable.", "example": { "asOf": "2026-10-05T08:00:00.000Z", "conditionCode": "PartlyCloudy", "daylight": true, "precipitation": 0, "temperature": 16.5, "temperatureApparent": 15.8, "uvIndex": 2, "windDirection": 225, "windGust": 24, "windSpeed": 14 } }, "hourly": { "type": "array", "items": { "type": "object", "properties": { "forecastStart": { "type": "string", "format": "date-time", "description": "Start timestamp of this forecast period.", "example": "2026-10-05T09:00:00.000Z" }, "conditionCode": { "type": "string", "enum": [ "Clear", "MostlyClear", "PartlyCloudy", "Cloudy", "Fog", "Drizzle", "FreezingDrizzle", "Rain", "HeavyRain", "FreezingRain", "Snow", "HeavySnow", "Flurries", "Showers", "SnowShowers", "Thunderstorm", "SevereThunderstorm" ], "description": "Normalized weather condition; use the listed enum values for icons and labels.", "example": "PartlyCloudy" }, "daylight": { "type": "boolean", "description": "Whether this reading is during daylight.", "example": true }, "precipitation": { "type": "number", "description": "Precipitation amount for the reading, in millimeters.", "example": 0 }, "precipitationChance": { "type": "number", "minimum": 0, "maximum": 1, "description": "Forecast precipitation probability from 0 to 1; multiply by 100 to display a percentage.", "example": 0.1 }, "temperature": { "type": "number", "description": "Air temperature in degrees Celsius.", "example": 17 }, "temperatureApparent": { "type": "number", "description": "Feels-like temperature in degrees Celsius.", "example": 16 }, "windDirection": { "type": "number", "description": "Wind direction in degrees.", "example": 225 }, "windGust": { "type": "number", "description": "Wind gust speed in kilometers per hour.", "example": 24 }, "windSpeed": { "type": "number", "description": "Wind speed in kilometers per hour.", "example": 14 } }, "required": [ "forecastStart", "conditionCode", "daylight", "precipitation", "precipitationChance", "temperature", "temperatureApparent", "windDirection", "windGust", "windSpeed" ], "additionalProperties": false, "example": { "forecastStart": "2026-10-05T09:00:00.000Z", "conditionCode": "PartlyCloudy", "daylight": true, "precipitation": 0, "precipitationChance": 0.1, "temperature": 17, "temperatureApparent": 16, "windDirection": 225, "windGust": 24, "windSpeed": 14 } }, "description": "Hourly forecast readings; may be empty when unavailable.", "example": [ { "forecastStart": "2026-10-05T09:00:00.000Z", "conditionCode": "PartlyCloudy", "daylight": true, "precipitation": 0, "precipitationChance": 0.1, "temperature": 17, "temperatureApparent": 16, "windDirection": 225, "windGust": 24, "windSpeed": 14 } ] }, "daily": { "type": "array", "items": { "type": "object", "properties": { "forecastStart": { "type": "string", "format": "date-time", "description": "Start timestamp of this forecast period.", "example": "2026-10-04T22:00:00.000Z" }, "conditionCode": { "type": "string", "enum": [ "Clear", "MostlyClear", "PartlyCloudy", "Cloudy", "Fog", "Drizzle", "FreezingDrizzle", "Rain", "HeavyRain", "FreezingRain", "Snow", "HeavySnow", "Flurries", "Showers", "SnowShowers", "Thunderstorm", "SevereThunderstorm" ], "description": "Normalized weather condition; use the listed enum values for icons and labels.", "example": "PartlyCloudy" }, "precipitationAmount": { "type": "number", "description": "Total forecast precipitation, in millimeters.", "example": 0.2 }, "precipitationChance": { "type": "number", "minimum": 0, "maximum": 1, "description": "Forecast precipitation probability from 0 to 1; multiply by 100 to display a percentage.", "example": 0.2 }, "sunriseTime": { "type": "string", "format": "date-time", "description": "Sunrise timestamp for this forecast day.", "example": "2026-10-05T05:48:00.000Z" }, "sunsetTime": { "type": "string", "format": "date-time", "description": "Sunset timestamp for this forecast day.", "example": "2026-10-05T17:08:00.000Z" }, "temperatureMax": { "type": "number", "description": "Maximum forecast temperature in degrees Celsius.", "example": 18 }, "temperatureMin": { "type": "number", "description": "Minimum forecast temperature in degrees Celsius.", "example": 11 }, "uvIndex": { "type": "number", "description": "UV index for the reading or forecast period.", "example": 2 }, "windDirection": { "type": "number", "description": "Wind direction in degrees.", "example": 225 }, "windGust": { "type": "number", "description": "Wind gust speed in kilometers per hour.", "example": 24 }, "windSpeed": { "type": "number", "description": "Wind speed in kilometers per hour.", "example": 14 } }, "required": [ "forecastStart", "conditionCode", "precipitationAmount", "precipitationChance", "sunriseTime", "sunsetTime", "temperatureMax", "temperatureMin", "uvIndex", "windDirection", "windGust", "windSpeed" ], "additionalProperties": false, "example": { "forecastStart": "2026-10-04T22:00:00.000Z", "conditionCode": "PartlyCloudy", "precipitationAmount": 0.2, "precipitationChance": 0.2, "sunriseTime": "2026-10-05T05:48:00.000Z", "sunsetTime": "2026-10-05T17:08:00.000Z", "temperatureMax": 18, "temperatureMin": 11, "uvIndex": 2, "windDirection": 225, "windGust": 24, "windSpeed": 14 } }, "description": "Daily forecast readings; may be empty when unavailable.", "example": [ { "forecastStart": "2026-10-04T22:00:00.000Z", "conditionCode": "PartlyCloudy", "precipitationAmount": 0.2, "precipitationChance": 0.2, "sunriseTime": "2026-10-05T05:48:00.000Z", "sunsetTime": "2026-10-05T17:08:00.000Z", "temperatureMax": 18, "temperatureMin": 11, "uvIndex": 2, "windDirection": 225, "windGust": 24, "windSpeed": 14 } ] } }, "required": [ "source", "coverage", "freshness", "current", "hourly", "daily" ], "additionalProperties": false, "example": { "source": "open-meteo", "coverage": { "id": "nl:noordwest", "name": "Noordwest", "countryCode": "nl", "countryName": "Netherlands", "latitude": 52.65, "longitude": 4.75, "timezone": "Europe/Amsterdam" }, "freshness": { "status": "fresh", "thresholdSeconds": 900, "ageSeconds": 30, "fetchedAt": "2026-10-05T08:00:01.000Z", "observedAt": "2026-10-05T08:00:00.000Z", "lastError": null }, "current": { "asOf": "2026-10-05T08:00:00.000Z", "conditionCode": "PartlyCloudy", "daylight": true, "precipitation": 0, "temperature": 16.5, "temperatureApparent": 15.8, "uvIndex": 2, "windDirection": 225, "windGust": 24, "windSpeed": 14 }, "hourly": [ { "forecastStart": "2026-10-05T09:00:00.000Z", "conditionCode": "PartlyCloudy", "daylight": true, "precipitation": 0, "precipitationChance": 0.1, "temperature": 17, "temperatureApparent": 16, "windDirection": 225, "windGust": 24, "windSpeed": 14 } ], "daily": [ { "forecastStart": "2026-10-04T22:00:00.000Z", "conditionCode": "PartlyCloudy", "precipitationAmount": 0.2, "precipitationChance": 0.2, "sunriseTime": "2026-10-05T05:48:00.000Z", "sunsetTime": "2026-10-05T17:08:00.000Z", "temperatureMax": 18, "temperatureMin": 11, "uvIndex": 2, "windDirection": 225, "windGust": 24, "windSpeed": 14 } ] } }, "description": "Weather snapshots for the station's configured coverage areas.", "example": [ { "source": "open-meteo", "coverage": { "id": "nl:noordwest", "name": "Noordwest", "countryCode": "nl", "countryName": "Netherlands", "latitude": 52.65, "longitude": 4.75, "timezone": "Europe/Amsterdam" }, "freshness": { "status": "fresh", "thresholdSeconds": 900, "ageSeconds": 30, "fetchedAt": "2026-10-05T08:00:01.000Z", "observedAt": "2026-10-05T08:00:00.000Z", "lastError": null }, "current": { "asOf": "2026-10-05T08:00:00.000Z", "conditionCode": "PartlyCloudy", "daylight": true, "precipitation": 0, "temperature": 16.5, "temperatureApparent": 15.8, "uvIndex": 2, "windDirection": 225, "windGust": 24, "windSpeed": 14 }, "hourly": [ { "forecastStart": "2026-10-05T09:00:00.000Z", "conditionCode": "PartlyCloudy", "daylight": true, "precipitation": 0, "precipitationChance": 0.1, "temperature": 17, "temperatureApparent": 16, "windDirection": 225, "windGust": 24, "windSpeed": 14 } ], "daily": [ { "forecastStart": "2026-10-04T22:00:00.000Z", "conditionCode": "PartlyCloudy", "precipitationAmount": 0.2, "precipitationChance": 0.2, "sunriseTime": "2026-10-05T05:48:00.000Z", "sunsetTime": "2026-10-05T17:08:00.000Z", "temperatureMax": 18, "temperatureMin": 11, "uvIndex": 2, "windDirection": 225, "windGust": 24, "windSpeed": 14 } ] } ] } }, "required": [ "contractVersion", "stationId", "timezone", "snapshots" ], "additionalProperties": false, "example": { "contractVersion": 1, "stationId": "station-rivier", "timezone": "Europe/Amsterdam", "snapshots": [ { "source": "open-meteo", "coverage": { "id": "nl:noordwest", "name": "Noordwest", "countryCode": "nl", "countryName": "Netherlands", "latitude": 52.65, "longitude": 4.75, "timezone": "Europe/Amsterdam" }, "freshness": { "status": "fresh", "thresholdSeconds": 900, "ageSeconds": 30, "fetchedAt": "2026-10-05T08:00:01.000Z", "observedAt": "2026-10-05T08:00:00.000Z", "lastError": null }, "current": { "asOf": "2026-10-05T08:00:00.000Z", "conditionCode": "PartlyCloudy", "daylight": true, "precipitation": 0, "temperature": 16.5, "temperatureApparent": 15.8, "uvIndex": 2, "windDirection": 225, "windGust": 24, "windSpeed": 14 }, "hourly": [ { "forecastStart": "2026-10-05T09:00:00.000Z", "conditionCode": "PartlyCloudy", "daylight": true, "precipitation": 0, "precipitationChance": 0.1, "temperature": 17, "temperatureApparent": 16, "windDirection": 225, "windGust": 24, "windSpeed": 14 } ], "daily": [ { "forecastStart": "2026-10-04T22:00:00.000Z", "conditionCode": "PartlyCloudy", "precipitationAmount": 0.2, "precipitationChance": 0.2, "sunriseTime": "2026-10-05T05:48:00.000Z", "sunsetTime": "2026-10-05T17:08:00.000Z", "temperatureMax": 18, "temperatureMin": 11, "uvIndex": 2, "windDirection": 225, "windGust": 24, "windSpeed": 14 } ] } ] } }, "examples": { "weather": { "summary": "Current weather and forecasts", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "stationId": "station-rivier", "timezone": "Europe/Amsterdam", "snapshots": [ { "source": "open-meteo", "coverage": { "id": "nl:noordwest", "name": "Noordwest", "countryCode": "nl", "countryName": "Netherlands", "latitude": 52.65, "longitude": 4.75, "timezone": "Europe/Amsterdam" }, "freshness": { "status": "fresh", "thresholdSeconds": 900, "ageSeconds": 30, "fetchedAt": "2026-10-05T08:00:01.000Z", "observedAt": "2026-10-05T08:00:00.000Z", "lastError": null }, "current": { "asOf": "2026-10-05T08:00:00.000Z", "conditionCode": "PartlyCloudy", "daylight": true, "precipitation": 0, "temperature": 16.5, "temperatureApparent": 15.8, "uvIndex": 2, "windDirection": 225, "windGust": 24, "windSpeed": 14 }, "hourly": [ { "forecastStart": "2026-10-05T09:00:00.000Z", "conditionCode": "PartlyCloudy", "daylight": true, "precipitation": 0, "precipitationChance": 0.1, "temperature": 17, "temperatureApparent": 16, "windDirection": 225, "windGust": 24, "windSpeed": 14 } ], "daily": [ { "forecastStart": "2026-10-04T22:00:00.000Z", "conditionCode": "PartlyCloudy", "precipitationAmount": 0.2, "precipitationChance": 0.2, "sunriseTime": "2026-10-05T05:48:00.000Z", "sunsetTime": "2026-10-05T17:08:00.000Z", "temperatureMax": 18, "temperatureMin": 11, "uvIndex": 2, "windDirection": 225, "windGust": 24, "windSpeed": 14 } ] } ] } }, "unavailable": { "summary": "Provider unavailable, no current reading", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "stationId": "station-rivier", "timezone": "Europe/Amsterdam", "snapshots": [ { "source": "open-meteo", "coverage": { "id": "nl:noordwest", "name": "Noordwest", "countryCode": "nl", "countryName": "Netherlands", "latitude": 52.65, "longitude": 4.75, "timezone": "Europe/Amsterdam" }, "freshness": { "status": "unavailable", "thresholdSeconds": 900, "ageSeconds": null, "fetchedAt": null, "observedAt": null, "lastError": "Weather provider temporarily unavailable" }, "current": null, "hourly": [], "daily": [] } ] } } } } } }, "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" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "description": "Read normalized weather for configured station coverage areas. Check each snapshot's freshness before display. current may be null and forecast arrays may be empty. This endpoint requires an available station resource and redistribution entitlement.", "x-mint": { "metadata": { "title": "Get weather" }, "href": "/radiotools/api-reference/public-listener/get-weather" } } }, "/api/v1/stations/{stationSlug}/traffic": { "get": { "summary": "Public traffic when redistribution entitlement is recorded", "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 63 }, "required": true, "name": "stationSlug", "in": "path", "description": "Public station slug from the station settings; distinct from the internal station ID.", "example": "radio-rivier" } ], "responses": { "200": { "description": "Normalized traffic; no-store so revocation applies on the next read", "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 }, "stationId": { "type": "string", "description": "Station identifier associated with this response.", "example": "station-rivier" }, "snapshot": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "anwb" ], "description": "Source provider for this normalized observation.", "example": "anwb" }, "watch": { "type": "object", "properties": { "roads": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^nl:[an](?:[0-9]{1,3}|-all)$", "description": "Identifier of this resource. Use the value returned by the API for subsequent lookups.", "example": "nl:a10" }, "code": { "type": "string", "minLength": 2, "maxLength": 8, "description": "Machine-readable code. Error codes are stable; road codes identify the watched road.", "example": "A10" }, "name": { "type": "string", "description": "Human-readable display name.", "example": "Ring Amsterdam" } }, "required": [ "id", "code", "name" ], "additionalProperties": false, "example": { "id": "nl:a10", "code": "A10", "name": "Ring Amsterdam" } }, "description": "Watched roads included in the station's traffic coverage.", "example": [ { "id": "nl:a10", "code": "A10", "name": "Ring Amsterdam" } ] } }, "required": [ "roads" ], "additionalProperties": false, "description": "Station-configured roads covered by this traffic report.", "example": { "roads": [ { "id": "nl:a10", "code": "A10", "name": "Ring Amsterdam" } ] } }, "freshness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fresh", "stale", "unavailable", "empty" ], "description": "Freshness classification of the source data. Handle stale, empty, or unavailable data explicitly.", "example": "fresh" }, "thresholdSeconds": { "type": "integer", "exclusiveMinimum": 0, "description": "Age threshold in seconds used to classify an observation as stale.", "example": 900 }, "ageSeconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Observation age in seconds; null when no observation is available.", "example": 30 }, "fetchedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the provider fetch; null when unavailable.", "example": "2026-10-05T08:00:01.000Z" }, "observedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the source observation occurred. Listener responses use ISO 8601 timestamps.", "example": "2026-10-05T08:00:00.000Z" }, "lastError": { "type": [ "string", "null" ], "description": "Latest provider error summary, or null when no error is recorded.", "example": null } }, "required": [ "status", "thresholdSeconds", "ageSeconds", "fetchedAt", "observedAt", "lastError" ], "additionalProperties": false, "description": "Age and freshness of the source observation. A successful HTTP read does not guarantee fresh data.", "example": { "status": "fresh", "thresholdSeconds": 900, "ageSeconds": 30, "fetchedAt": "2026-10-05T08:00:01.000Z", "observedAt": "2026-10-05T08:00:00.000Z", "lastError": null } }, "incidents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of this resource. Use the value returned by the API for subsequent lookups.", "example": "anwb-a10-example" }, "road": { "type": "string", "description": "Road code affected by the incident, for example A10.", "example": "A10" }, "type": { "type": "string", "enum": [ "jam", "roadworks", "closure", "speed_check" ], "description": "Discriminator describing this block or incident. Render according to the allowed values.", "example": "jam" }, "direction": { "type": "string", "enum": [ "northbound", "southbound", "eastbound", "westbound", "both", "unknown" ], "description": "Direction affected by the incident.", "example": "northbound" }, "from": { "type": "string", "description": "Start location of the affected road segment.", "example": "Watergraafsmeer" }, "to": { "type": "string", "description": "End location of the affected road segment.", "example": "Zeeburg" }, "lengthMeters": { "type": [ "integer", "null" ], "minimum": 0, "description": "Affected road length in meters; null when unknown.", "example": 2500 }, "delaySeconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Reported delay in seconds; incident delay may be null when unknown.", "example": 300 }, "cause": { "type": [ "string", "null" ], "enum": [ "accident", "vehicle_fire", "broken_down_vehicle", "object_on_road", "clearance_work", "technical_problem", "roadworks", "closure", null ], "description": "Reported cause of the incident; null when unknown.", "example": null }, "closure": { "type": [ "string", "null" ], "enum": [ "road", "entry", "exit", "entry_and_exit", "connector", "lane", "heavy_vehicles", null ], "description": "What is closed, such as the whole road, an entry or exit, or a lane; null when nothing is closed.", "example": null }, "summary": { "type": "string", "description": "Human-readable description of the incident.", "example": "Slow traffic approaching Zeeburg." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp of the latest incident update.", "example": "2026-10-05T08:00:00.000Z" } }, "required": [ "id", "road", "type", "direction", "from", "to", "lengthMeters", "delaySeconds", "cause", "closure", "summary", "updatedAt" ], "additionalProperties": false, "example": { "id": "anwb-a10-example", "road": "A10", "type": "jam", "direction": "northbound", "from": "Watergraafsmeer", "to": "Zeeburg", "lengthMeters": 2500, "delaySeconds": 300, "cause": null, "closure": null, "summary": "Slow traffic approaching Zeeburg.", "updatedAt": "2026-10-05T08:00:00.000Z" } }, "description": "Normalized incidents; an empty array with fresh status means no reported incidents.", "example": [ { "id": "anwb-a10-example", "road": "A10", "type": "jam", "direction": "northbound", "from": "Watergraafsmeer", "to": "Zeeburg", "lengthMeters": 2500, "delaySeconds": 300, "cause": null, "closure": null, "summary": "Slow traffic approaching Zeeburg.", "updatedAt": "2026-10-05T08:00:00.000Z" } ] }, "totals": { "type": "object", "properties": { "incidentCount": { "type": "integer", "minimum": 0, "description": "Number of incidents in this snapshot.", "example": 1 }, "jamDistanceMeters": { "type": "integer", "minimum": 0, "description": "Total reported traffic-jam distance in meters.", "example": 2500 }, "delaySeconds": { "type": "integer", "minimum": 0, "description": "Reported delay in seconds; incident delay may be null when unknown.", "example": 300 } }, "required": [ "incidentCount", "jamDistanceMeters", "delaySeconds" ], "additionalProperties": false, "description": "Aggregate traffic totals for the watched roads.", "example": { "incidentCount": 1, "jamDistanceMeters": 2500, "delaySeconds": 300 } } }, "required": [ "source", "watch", "freshness", "incidents", "totals" ], "additionalProperties": false, "description": "Traffic report for the station's configured watched roads.", "example": { "source": "anwb", "watch": { "roads": [ { "id": "nl:a10", "code": "A10", "name": "Ring Amsterdam" } ] }, "freshness": { "status": "fresh", "thresholdSeconds": 900, "ageSeconds": 30, "fetchedAt": "2026-10-05T08:00:01.000Z", "observedAt": "2026-10-05T08:00:00.000Z", "lastError": null }, "incidents": [ { "id": "anwb-a10-example", "road": "A10", "type": "jam", "direction": "northbound", "from": "Watergraafsmeer", "to": "Zeeburg", "lengthMeters": 2500, "delaySeconds": 300, "cause": null, "closure": null, "summary": "Slow traffic approaching Zeeburg.", "updatedAt": "2026-10-05T08:00:00.000Z" } ], "totals": { "incidentCount": 1, "jamDistanceMeters": 2500, "delaySeconds": 300 } } } }, "required": [ "contractVersion", "stationId", "snapshot" ], "additionalProperties": false, "example": { "contractVersion": 1, "stationId": "station-rivier", "snapshot": { "source": "anwb", "watch": { "roads": [ { "id": "nl:a10", "code": "A10", "name": "Ring Amsterdam" } ] }, "freshness": { "status": "fresh", "thresholdSeconds": 900, "ageSeconds": 30, "fetchedAt": "2026-10-05T08:00:01.000Z", "observedAt": "2026-10-05T08:00:00.000Z", "lastError": null }, "incidents": [ { "id": "anwb-a10-example", "road": "A10", "type": "jam", "direction": "northbound", "from": "Watergraafsmeer", "to": "Zeeburg", "lengthMeters": 2500, "delaySeconds": 300, "cause": null, "closure": null, "summary": "Slow traffic approaching Zeeburg.", "updatedAt": "2026-10-05T08:00:00.000Z" } ], "totals": { "incidentCount": 1, "jamDistanceMeters": 2500, "delaySeconds": 300 } } } }, "examples": { "traffic": { "summary": "Traffic on watched roads", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "stationId": "station-rivier", "snapshot": { "source": "anwb", "watch": { "roads": [ { "id": "nl:a10", "code": "A10", "name": "Ring Amsterdam" } ] }, "freshness": { "status": "fresh", "thresholdSeconds": 900, "ageSeconds": 30, "fetchedAt": "2026-10-05T08:00:01.000Z", "observedAt": "2026-10-05T08:00:00.000Z", "lastError": null }, "incidents": [ { "id": "anwb-a10-example", "road": "A10", "type": "jam", "direction": "northbound", "from": "Watergraafsmeer", "to": "Zeeburg", "lengthMeters": 2500, "delaySeconds": 300, "cause": null, "closure": null, "summary": "Slow traffic approaching Zeeburg.", "updatedAt": "2026-10-05T08:00:00.000Z" } ], "totals": { "incidentCount": 1, "jamDistanceMeters": 2500, "delaySeconds": 300 } } } }, "clear": { "summary": "Fresh report with no incidents", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "stationId": "station-rivier", "snapshot": { "source": "anwb", "watch": { "roads": [ { "id": "nl:a10", "code": "A10", "name": "Ring Amsterdam" } ] }, "freshness": { "status": "fresh", "thresholdSeconds": 900, "ageSeconds": 30, "fetchedAt": "2026-10-05T08:00:01.000Z", "observedAt": "2026-10-05T08:00:00.000Z", "lastError": null }, "incidents": [], "totals": { "incidentCount": 0, "jamDistanceMeters": 0, "delaySeconds": 0 } } } } } } } }, "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" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "description": "Read normalized traffic for the station's watched roads. Check snapshot.freshness before interpreting an empty incidents array as clear traffic. This endpoint requires an available station resource and redistribution entitlement.", "x-mint": { "metadata": { "title": "Get traffic" }, "href": "/radiotools/api-reference/public-listener/get-traffic" } } }, "/api/v1/stations/{stationSlug}/graphql": { "get": { "summary": "Query published station data with GraphQL", "description": "Query the station's published data with GraphQL. Requires a station-scoped Bearer credential with listener:read. GET carries the query in URL parameters, with variables and extensions as JSON-encoded strings; POST accepts a JSON GraphQL request. Send X-Preview-Grant only to read an editorial preview.\n\nAfter the station admits the request, responses use the GraphQL data and errors envelope. Authentication and station errors use the standard error response. Responses are no-store; keep the credential on your server, out of browser bundles and URLs. See the [GraphQL guide](/radiotools/api-reference/graphql) for the schema.", "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" }, "required": true, "name": "query", "in": "query", "description": "GraphQL query document, URL-encoded.", "example": "{ station { name } }" }, { "schema": { "type": "string" }, "required": false, "name": "operationName", "in": "query", "description": "Operation to run when the query document contains more than one." }, { "schema": { "type": "string" }, "required": false, "name": "variables", "in": "query", "description": "GraphQL variables as a JSON-encoded string." }, { "schema": { "type": "string" }, "required": false, "name": "extensions", "in": "query", "description": "GraphQL extensions as a JSON-encoded string." }, { "schema": { "type": "string" }, "required": false, "name": "X-Preview-Grant", "in": "header", "description": "Editorial preview grant from the station's website preview link. Send it to read the unpublished revision it was issued for; omit it for published data." } ], "responses": { "200": { "description": "GraphQL result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphqlResponse" } } } }, "400": { "description": "The request contains invalid parameters or input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphqlFailure" }, "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": { "$ref": "#/components/schemas/GraphqlFailure" }, "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": { "$ref": "#/components/schemas/GraphqlFailure" }, "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": { "$ref": "#/components/schemas/GraphqlFailure" }, "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": { "$ref": "#/components/schemas/GraphqlFailure" }, "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": { "$ref": "#/components/schemas/GraphqlFailure" }, "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" } } } } } } }, "500": { "description": "GraphQL or station admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphqlFailure" } } } }, "503": { "description": "An upstream service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphqlFailure" }, "examples": { "error": { "summary": "503 PROVIDER_UNAVAILABLE", "value": { "error": { "code": "PROVIDER_UNAVAILABLE", "message": "An upstream service is temporarily unavailable.", "requestId": "28e5d867-1f87-4ca7-bca9-4ebc09b36ba3" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "x-mint": { "metadata": { "title": "Query with GraphQL (GET)" }, "href": "/radiotools/api-reference/public-listener/query-graphql-get" } }, "post": { "summary": "Query published station data with GraphQL", "description": "Query the station's published data with GraphQL. Requires a station-scoped Bearer credential with listener:read. GET carries the query in URL parameters, with variables and extensions as JSON-encoded strings; POST accepts a JSON GraphQL request. Send X-Preview-Grant only to read an editorial preview.\n\nAfter the station admits the request, responses use the GraphQL data and errors envelope. Authentication and station errors use the standard error response. Responses are no-store; keep the credential on your server, out of browser bundles and URLs. See the [GraphQL guide](/radiotools/api-reference/graphql) for the schema.", "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" }, "required": false, "name": "X-Preview-Grant", "in": "header", "description": "Editorial preview grant from the station's website preview link. Send it to read the unpublished revision it was issued for; omit it for published data." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "operationName": { "type": [ "string", "null" ] }, "variables": { "type": [ "object", "null" ], "additionalProperties": {} }, "extensions": { "type": "object", "additionalProperties": {} } }, "required": [ "query" ], "example": { "token": "fictional-fcm-device-token", "platform": "android", "provider": "fcm" } }, "examples": { "android": { "summary": "Register an Android device", "description": "Replace the fictional token with the device token from your push provider; the provider must match the station configuration.", "value": { "token": "fictional-fcm-device-token", "platform": "android", "provider": "fcm" } } } } } }, "responses": { "200": { "description": "GraphQL result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphqlResponse" } } } }, "400": { "description": "The request contains invalid parameters or input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphqlFailure" }, "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": { "$ref": "#/components/schemas/GraphqlFailure" }, "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": { "$ref": "#/components/schemas/GraphqlFailure" }, "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": { "$ref": "#/components/schemas/GraphqlFailure" }, "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": { "$ref": "#/components/schemas/GraphqlFailure" }, "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": { "$ref": "#/components/schemas/GraphqlFailure" }, "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" } } } } } } }, "500": { "description": "GraphQL or station admission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphqlFailure" } } } }, "503": { "description": "An upstream service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphqlFailure" }, "examples": { "error": { "summary": "503 PROVIDER_UNAVAILABLE", "value": { "error": { "code": "PROVIDER_UNAVAILABLE", "message": "An upstream service is temporarily unavailable.", "requestId": "28e5d867-1f87-4ca7-bca9-4ebc09b36ba3" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "x-mint": { "metadata": { "title": "Query with GraphQL" }, "href": "/radiotools/api-reference/public-listener/query-graphql" } } }, "/api/v1/stations/{stationSlug}": { "get": { "summary": "Public station identity, timezone, publishing language and resource links", "description": "Fails closed (404) for unknown, inactive or public-offline stations. Per-API switches can null individual resource hrefs; disabled APIs return the same NOT_FOUND body as public-offline. `resources.weather` and `resources.traffic` stay null without redistribution entitlement even when their switches are on. Poll no faster than `delivery.pollIntervalSeconds` and send If-None-Match.", "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 63 }, "required": true, "name": "stationSlug", "in": "path", "description": "Public station slug from the station settings; distinct from the internal station ID.", "example": "radio-rivier" } ], "responses": { "200": { "description": "Delivery-safe station projection", "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 }, "id": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Identifier of this resource. Use the value returned by the API for subsequent lookups.", "example": "station-rivier" }, "slug": { "type": "string", "minLength": 3, "maxLength": 63, "description": "Public URL slug of the station.", "example": "radio-rivier" }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Human-readable display name.", "example": "Radio Rivier" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IANA timezone used to interpret station calendar dates, for example Europe/Amsterdam.", "example": "Europe/Amsterdam" }, "publishingLanguage": { "type": "string", "minLength": 2, "maxLength": 35, "description": "Station publishing language code, for example nl or en.", "example": "nl" }, "profile": { "type": "object", "properties": { "tagline": { "type": [ "string", "null" ], "maxLength": 160, "description": "Short station slogan.", "example": "The sound of the river" }, "description": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Longer public description of the station.", "example": "Local news, music, and events for the riverside towns." }, "frequencyLabel": { "type": [ "string", "null" ], "maxLength": 80, "description": "Frequency or channel as shown to listeners, for example FM 104.3.", "example": "FM 104.3" }, "websiteUrl": { "type": [ "string", "null" ], "maxLength": 500, "format": "uri", "description": "Station website URL.", "example": "https://www.example.com" }, "streamUrl": { "type": [ "string", "null" ], "maxLength": 500, "format": "uri", "description": "Public audio stream URL.", "example": "https://stream.example.com/radio-rivier.mp3" }, "contactEmail": { "type": [ "string", "null" ], "maxLength": 254, "format": "email", "description": "Public contact email address.", "example": "studio@example.com" }, "phone": { "type": [ "string", "null" ], "maxLength": 40, "description": "Public phone number.", "example": "+31 20 123 4567" }, "address": { "type": [ "object", "null" ], "properties": { "street": { "type": [ "string", "null" ], "maxLength": 120, "description": "Street and house number.", "example": "Kade 12" }, "postalCode": { "type": [ "string", "null" ], "maxLength": 20, "description": "Postal code.", "example": "1011 AB" }, "city": { "type": [ "string", "null" ], "maxLength": 120, "description": "City.", "example": "Amsterdam" }, "country": { "type": [ "string", "null" ], "maxLength": 120, "description": "Country.", "example": "Netherlands" } }, "required": [ "street", "postalCode", "city", "country" ], "additionalProperties": false, "description": "Public postal address.", "example": { "street": "Kade 12", "postalCode": "1011 AB", "city": "Amsterdam", "country": "Netherlands" } }, "social": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "facebook", "instagram", "x", "tiktok", "youtube", "linkedin", "mastodon", "bluesky", "whatsapp", "other" ], "description": "Social network of this profile.", "example": "instagram" }, "url": { "type": "string", "maxLength": 500, "format": "uri", "description": "Profile URL on the social network.", "example": "https://instagram.com/example" } }, "required": [ "network", "url" ], "additionalProperties": false, "example": { "network": "instagram", "url": "https://instagram.com/example" } }, "maxItems": 12, "description": "Social media profiles of the station.", "example": [ { "network": "instagram", "url": "https://instagram.com/example" } ] } }, "required": [ "tagline", "description", "frequencyLabel", "websiteUrl", "streamUrl", "contactEmail", "phone", "address", "social" ], "additionalProperties": false, "description": "Public station profile for an about or contact page. Each value is null when the station has not set it.", "example": { "tagline": "The sound of the river", "description": "Local news, music, and events for the riverside towns.", "frequencyLabel": "FM 104.3", "websiteUrl": "https://www.example.com", "streamUrl": "https://stream.example.com/radio-rivier.mp3", "contactEmail": "studio@example.com", "phone": "+31 20 123 4567", "address": { "street": "Kade 12", "postalCode": "1011 AB", "city": "Amsterdam", "country": "Netherlands" }, "social": [ { "network": "instagram", "url": "https://instagram.com/example" } ] } }, "resources": { "type": "object", "properties": { "schemas": { "type": "string", "description": "Discovery link for schemas; follow the returned URL. Nullable links are null when disabled or unavailable.", "example": "/api/v1/stations/radio-rivier/schemas" }, "content": { "type": [ "string", "null" ], "description": "Discovery link for content; follow the returned URL. Nullable links are null when disabled or unavailable.", "example": "/api/v1/stations/radio-rivier/content" }, "schedule": { "type": [ "string", "null" ], "description": "Discovery link for schedule; follow the returned URL. Nullable links are null when disabled or unavailable.", "example": "/api/v1/stations/radio-rivier/schedule" }, "programs": { "type": [ "string", "null" ], "description": "Discovery link for programs; follow the returned URL. Nullable links are null when disabled or unavailable.", "example": "/api/v1/stations/radio-rivier/programs" }, "broadcast": { "type": [ "string", "null" ], "description": "Discovery link for broadcast; follow the returned URL. Nullable links are null when disabled or unavailable.", "example": "/api/v1/stations/radio-rivier/broadcast/current" }, "nowPlaying": { "type": [ "string", "null" ], "description": "Discovery link for nowPlaying; follow the returned URL. Nullable links are null when disabled or unavailable.", "example": "/api/v1/stations/radio-rivier/now-playing" }, "trackHistory": { "type": [ "string", "null" ], "description": "Discovery link for trackHistory; follow the returned URL. Nullable links are null when disabled or unavailable.", "example": "/api/v1/stations/radio-rivier/track-history" }, "realtime": { "type": [ "object", "null" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Secure WebSocket (wss:) URL of the feed. Connect without a token.", "example": "wss://radiotools.rivi.software/api/v1/realtime/stations/station-rivier/feed" }, "channel": { "type": "string", "minLength": 1, "description": "Channel name carried by feed events. Ignore events for other channels.", "example": "databases.public.tables.public_station_feed.rows" } }, "required": [ "url", "channel" ], "description": "The station's public realtime feed: a WebSocket url and the channel its events use. No token is needed. Null when the feed is switched off.", "example": { "url": "wss://radiotools.rivi.software/api/v1/realtime/stations/station-rivier/feed", "channel": "databases.public.tables.public_station_feed.rows" } }, "weather": { "type": [ "string", "null" ], "description": "Discovery link for weather; follow the returned URL. Nullable links are null when disabled or unavailable.", "example": null }, "traffic": { "type": [ "string", "null" ], "description": "Discovery link for traffic; follow the returned URL. Nullable links are null when disabled or unavailable.", "example": null }, "media": { "type": "string", "description": "Discovery link for media; follow the returned URL. Nullable links are null when disabled or unavailable.", "example": "/api/media/public/station-rivier" } }, "required": [ "schemas", "content", "schedule", "programs", "broadcast", "nowPlaying", "trackHistory", "realtime", "weather", "traffic", "media" ], "description": "Discovery links for this station. A null link means the resource is disabled or unavailable.", "example": { "schemas": "/api/v1/stations/radio-rivier/schemas", "content": "/api/v1/stations/radio-rivier/content", "schedule": "/api/v1/stations/radio-rivier/schedule", "programs": "/api/v1/stations/radio-rivier/programs", "broadcast": "/api/v1/stations/radio-rivier/broadcast/current", "nowPlaying": "/api/v1/stations/radio-rivier/now-playing", "trackHistory": "/api/v1/stations/radio-rivier/track-history", "realtime": { "url": "wss://radiotools.rivi.software/api/v1/realtime/stations/station-rivier/feed", "channel": "databases.public.tables.public_station_feed.rows" }, "weather": null, "traffic": null, "media": "/api/media/public/station-rivier" } }, "delivery": { "type": "object", "properties": { "cache": { "type": "string", "enum": [ "no-store" ], "description": "Listener responses must not be stored in shared caches.", "example": "no-store" }, "conditional": { "type": "string", "enum": [ "etag" ], "description": "Use the response ETag in If-None-Match on your next read.", "example": "etag" }, "pollIntervalSeconds": { "type": "integer", "exclusiveMinimum": 0, "description": "Minimum interval between polls, in seconds.", "example": 30 } }, "required": [ "cache", "conditional", "pollIntervalSeconds" ], "description": "Delivery policy for listener reads. Respect the advertised polling interval.", "example": { "cache": "no-store", "conditional": "etag", "pollIntervalSeconds": 30 } } }, "required": [ "contractVersion", "id", "slug", "name", "timezone", "publishingLanguage", "resources", "delivery" ], "example": { "contractVersion": 1, "id": "station-rivier", "slug": "radio-rivier", "name": "Radio Rivier", "timezone": "Europe/Amsterdam", "publishingLanguage": "nl", "resources": { "schemas": "/api/v1/stations/radio-rivier/schemas", "content": "/api/v1/stations/radio-rivier/content", "schedule": "/api/v1/stations/radio-rivier/schedule", "programs": "/api/v1/stations/radio-rivier/programs", "broadcast": "/api/v1/stations/radio-rivier/broadcast/current", "nowPlaying": "/api/v1/stations/radio-rivier/now-playing", "trackHistory": "/api/v1/stations/radio-rivier/track-history", "realtime": { "url": "wss://radiotools.rivi.software/api/v1/realtime/stations/station-rivier/feed", "channel": "databases.public.tables.public_station_feed.rows" }, "weather": null, "traffic": null, "media": "/api/media/public/station-rivier" }, "delivery": { "cache": "no-store", "conditional": "etag", "pollIntervalSeconds": 30 }, "profile": { "tagline": "The sound of the river", "description": "Local news, music, and events for the riverside towns.", "frequencyLabel": "FM 104.3", "websiteUrl": "https://www.example.com", "streamUrl": "https://stream.example.com/radio-rivier.mp3", "contactEmail": "studio@example.com", "phone": "+31 20 123 4567", "address": { "street": "Kade 12", "postalCode": "1011 AB", "city": "Amsterdam", "country": "Netherlands" }, "social": [ { "network": "instagram", "url": "https://instagram.com/example" } ] } } }, "examples": { "station": { "summary": "Station discovery", "description": "Weather and traffic links are null in this example because those resources are unavailable. Follow the links returned by your own station.", "value": { "contractVersion": 1, "id": "station-rivier", "slug": "radio-rivier", "name": "Radio Rivier", "timezone": "Europe/Amsterdam", "publishingLanguage": "nl", "resources": { "schemas": "/api/v1/stations/radio-rivier/schemas", "content": "/api/v1/stations/radio-rivier/content", "schedule": "/api/v1/stations/radio-rivier/schedule", "programs": "/api/v1/stations/radio-rivier/programs", "broadcast": "/api/v1/stations/radio-rivier/broadcast/current", "nowPlaying": "/api/v1/stations/radio-rivier/now-playing", "trackHistory": "/api/v1/stations/radio-rivier/track-history", "realtime": { "url": "wss://radiotools.rivi.software/api/v1/realtime/stations/station-rivier/feed", "channel": "databases.public.tables.public_station_feed.rows" }, "weather": null, "traffic": null, "media": "/api/media/public/station-rivier" }, "delivery": { "cache": "no-store", "conditional": "etag", "pollIntervalSeconds": 30 }, "profile": { "tagline": "The sound of the river", "description": "Local news, music, and events for the riverside towns.", "frequencyLabel": "FM 104.3", "websiteUrl": "https://www.example.com", "streamUrl": "https://stream.example.com/radio-rivier.mp3", "contactEmail": "studio@example.com", "phone": "+31 20 123 4567", "address": { "street": "Kade 12", "postalCode": "1011 AB", "city": "Amsterdam", "country": "Netherlands" }, "social": [ { "network": "instagram", "url": "https://instagram.com/example" } ] } } } } } } }, "304": { "description": "Not modified: your authenticated conditional request matched the current ETag. No response body; reuse your previous representation." }, "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" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "x-mint": { "metadata": { "title": "Get station" }, "href": "/radiotools/api-reference/public-listener/get-station" } } }, "/api/v1/integrations/playback": { "post": { "summary": "Canonical now-playing observation ingest for automation systems", "description": "Requires exactly one of `?stationId=` or `?stationSlug=` (public station slug, same as `/api/v1/stations/{stationSlug}`) plus an integration credential (integration `playback`, scope `ingest:write`) for that same station. Body is at most 8 KiB. Send `artist` and `title`, or a single encoder `streamTitle` (`Artist - Title`; without a separator the whole string is stored as title). Legacy `duration` (seconds) is accepted as an alias of `durationSeconds` but both must match when present. Valid observations are persisted before rundown following; `eventId` deduplicates provider retries and legacy payloads without ids may collapse within a short adjacent window. Rundown following still requires a live broadcast at `observedAt`. When the station has artwork lookup on and the body omits `artworkUrl`, a provider lookup may fill the stored track after this response; the response does not wait for it. Errors on this compatibility-sensitive endpoint are `{ error: string }`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": false, "name": "stationId", "in": "query", "description": "Station ID associated with your credential. Send this or stationSlug, not both.", "example": "station-rivier" }, { "schema": { "type": "string", "minLength": 3, "maxLength": 63 }, "required": false, "name": "stationSlug", "in": "query", "description": "Public station slug from the station settings; distinct from the internal station ID.", "example": "radio-rivier" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Stable source event identifier for deduplicating retries of the same observation.", "example": "automation-rivier-20261005-080000" }, "observedAt": { "type": "integer", "minimum": 0, "maximum": 8640000000000000, "description": "Source observation time as Unix milliseconds (not seconds). Omit when the encoder cannot supply it.", "example": 1791187200000 }, "artist": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Artist reported by external automation.", "example": "The Riverlights" }, "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Human-readable title. Track titles come from external automation.", "example": "Morning Sun" }, "streamTitle": { "type": "string", "minLength": 1, "maxLength": 1001, "description": "Encoder stream title, usually Artist - Title. Without a separator, the whole string is stored as the title." }, "album": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Reported album; null when unknown in listener responses.", "example": "Open Water" }, "sourceTrackId": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Optional track identifier in the automation library. Omitted from listener responses.", "example": "library-track-4821" }, "artworkUrl": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri", "description": "Artwork URL when available. May be omitted; do not assume every track has artwork." }, "durationSeconds": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 86400, "description": "Reported track duration in seconds; null when unknown.", "example": 210 }, "duration": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 86400, "description": "Legacy alias of durationSeconds. If both are provided, their values must match." }, "isPlaying": { "type": "boolean", "default": true, "description": "Whether the automation observation reports the track as playing.", "example": true } }, "additionalProperties": false, "example": { "eventId": "automation-rivier-20261005-080000", "observedAt": 1791187200000, "artist": "The Riverlights", "title": "Morning Sun", "album": "Open Water", "sourceTrackId": "library-track-4821", "durationSeconds": 210, "isPlaying": true } }, "examples": { "fields": { "summary": "Separate artist and title", "description": "observedAt is Unix time in milliseconds. Reuse the same eventId only when retrying the same observation.", "value": { "eventId": "automation-rivier-20261005-080000", "observedAt": 1791187200000, "artist": "The Riverlights", "title": "Morning Sun", "album": "Open Water", "sourceTrackId": "library-track-4821", "durationSeconds": 210, "isPlaying": true } }, "streamTitle": { "summary": "Encoder stream title", "description": "For encoders that send a single stream title. Without a separator, the full string becomes the title.", "value": { "streamTitle": "The Riverlights - Morning Sun", "isPlaying": true } } } } } }, "responses": { "200": { "description": "Observation outcome", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean", "description": "Whether the ingest/follow result was accepted. Inspect outcome for the detailed result.", "example": true }, "outcome": { "type": "string", "enum": [ "no-live-broadcast", "on-air-not-following-rundown", "not-playing", "rejected", "recorded", "matched", "uncertain", "ignored" ], "description": "Ingest or rundown-follow result. Observations do not control audio playback.", "example": "recorded" } }, "required": [ "accepted", "outcome" ], "example": { "accepted": true, "outcome": "recorded" } }, "examples": { "recorded": { "summary": "Observation recorded", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "accepted": true, "outcome": "recorded" } }, "noLiveBroadcast": { "summary": "No live broadcast for rundown following", "description": "A valid observation can be persisted even when there is no live broadcast to follow. The outcome describes the ingest/follow result, not audio control.", "value": { "accepted": false, "outcome": "no-live-broadcast" } } } } } }, "400": { "description": "Invalid observation or content type", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Encoder-compatible error summary.", "example": "The request contains invalid parameters or input." } }, "required": [ "error" ], "example": { "error": "The request contains invalid parameters or input." } }, "examples": { "error": { "summary": "Encoder-compatible error", "value": { "error": "The request contains invalid parameters or input." } } } } } }, "401": { "description": "Missing, unknown, revoked or cross-station credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Encoder-compatible error summary.", "example": "A valid station credential with the required scope is needed." } }, "required": [ "error" ], "example": { "error": "A valid station credential with the required scope is needed." } }, "examples": { "error": { "summary": "Encoder-compatible error", "value": { "error": "A valid station credential with the required scope is needed." } } } } } }, "405": { "description": "Use POST", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Encoder-compatible error summary.", "example": "Use the documented HTTP method for this endpoint." } }, "required": [ "error" ], "example": { "error": "Use the documented HTTP method for this endpoint." } }, "examples": { "error": { "summary": "Encoder-compatible error", "value": { "error": "Use the documented HTTP method for this endpoint." } } } } } } }, "tags": [ "Ingest" ], "security": [ { "integrationToken": [] } ], "x-mint": { "metadata": { "title": "Report now playing" }, "href": "/radiotools/api-reference/ingest/report-now-playing" } } }, "/api/v1/stations/{stationSlug}/now-playing": { "get": { "summary": "Observed now-playing with freshness", "description": "Tenant token with listener:read behind the public station gate. Encoder `sourceTrackId` is omitted. Each `track` may include `artworkUrl` (HTTPS) from ingest or from station artwork lookup (Spotify, Apple Music, or Last.fm) after the observation is stored; the field is omitted when no art is known. `elapsedSeconds` and `endsAt` are derived from `track.observedAt` and `track.durationSeconds` at response time (both null when duration is unknown or the track is not playing). The public realtime feed carries the same projection and may send a follow-up update when lookup fills art.", "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 63 }, "required": true, "name": "stationSlug", "in": "path", "description": "Public station slug from the station settings; distinct from the internal station ID.", "example": "radio-rivier" } ], "responses": { "200": { "description": "Current observed track independent of the planned rundown", "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 }, "stationId": { "type": "string", "description": "Station identifier associated with this response.", "example": "station-rivier" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "IANA timezone used to interpret station calendar dates, for example Europe/Amsterdam.", "example": "Europe/Amsterdam" }, "track": { "type": [ "object", "null" ], "properties": { "artist": { "type": "string", "description": "Artist reported by external automation.", "example": "The Riverlights" }, "title": { "type": "string", "description": "Human-readable title. Track titles come from external automation.", "example": "Morning Sun" }, "album": { "type": [ "string", "null" ], "description": "Reported album; null when unknown in listener responses.", "example": "Open Water" }, "durationSeconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Reported track duration in seconds; null when unknown.", "example": 210 }, "artworkUrl": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri", "description": "Artwork URL when available. May be omitted; do not assume every track has artwork.", "example": "https://images.example.com/riverlights/open-water.jpg" }, "isPlaying": { "type": "boolean", "description": "Whether the automation observation reports the track as playing.", "example": true }, "observedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the source observation occurred. Listener responses use ISO 8601 timestamps.", "example": "2026-10-05T08:00:00.000Z" }, "receivedAt": { "type": "string", "format": "date-time", "description": "Timestamp when RadioTools received the observation.", "example": "2026-10-05T08:00:01.000Z" } }, "required": [ "artist", "title", "album", "durationSeconds", "isPlaying", "observedAt", "receivedAt" ], "additionalProperties": false, "description": "Latest reported track; null when no observation is available.", "example": { "artist": "The Riverlights", "title": "Morning Sun", "album": "Open Water", "durationSeconds": 210, "artworkUrl": "https://images.example.com/riverlights/open-water.jpg", "isPlaying": true, "observedAt": "2026-10-05T08:00:00.000Z", "receivedAt": "2026-10-05T08:00:01.000Z" } }, "elapsedSeconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Elapsed seconds derived at response time; null when duration is unknown or the track is not playing.", "example": 30 }, "endsAt": { "type": [ "string", "null" ], "format": "date-time", "description": "End timestamp. For now-playing this is derived from observedAt and durationSeconds; null when duration is unknown or the track is not playing.", "example": "2026-10-05T08:03:30.000Z" }, "freshness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fresh", "stale", "empty" ], "description": "Freshness classification of the source data. Handle stale, empty, or unavailable data explicitly.", "example": "fresh" }, "thresholdSeconds": { "type": "integer", "exclusiveMinimum": 0, "description": "Age threshold in seconds used to classify an observation as stale.", "example": 300 }, "ageSeconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Observation age in seconds; null when no observation is available.", "example": 30 }, "observedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the source observation occurred. Listener responses use ISO 8601 timestamps.", "example": "2026-10-05T08:00:00.000Z" }, "receivedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when RadioTools received the observation.", "example": "2026-10-05T08:00:01.000Z" } }, "required": [ "status", "thresholdSeconds", "ageSeconds", "observedAt", "receivedAt" ], "additionalProperties": false, "description": "Age and freshness of the source observation. A successful HTTP read does not guarantee fresh data.", "example": { "status": "fresh", "thresholdSeconds": 300, "ageSeconds": 30, "observedAt": "2026-10-05T08:00:00.000Z", "receivedAt": "2026-10-05T08:00:01.000Z" } } }, "required": [ "contractVersion", "stationId", "timezone", "track", "elapsedSeconds", "endsAt", "freshness" ], "additionalProperties": false, "example": { "contractVersion": 1, "stationId": "station-rivier", "timezone": "Europe/Amsterdam", "track": { "artist": "The Riverlights", "title": "Morning Sun", "album": "Open Water", "durationSeconds": 210, "artworkUrl": "https://images.example.com/riverlights/open-water.jpg", "isPlaying": true, "observedAt": "2026-10-05T08:00:00.000Z", "receivedAt": "2026-10-05T08:00:01.000Z" }, "elapsedSeconds": 30, "endsAt": "2026-10-05T08:03:30.000Z", "freshness": { "status": "fresh", "thresholdSeconds": 300, "ageSeconds": 30, "observedAt": "2026-10-05T08:00:00.000Z", "receivedAt": "2026-10-05T08:00:01.000Z" } } }, "examples": { "fresh": { "summary": "Fresh reported track", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "stationId": "station-rivier", "timezone": "Europe/Amsterdam", "track": { "artist": "The Riverlights", "title": "Morning Sun", "album": "Open Water", "durationSeconds": 210, "artworkUrl": "https://images.example.com/riverlights/open-water.jpg", "isPlaying": true, "observedAt": "2026-10-05T08:00:00.000Z", "receivedAt": "2026-10-05T08:00:01.000Z" }, "elapsedSeconds": 30, "endsAt": "2026-10-05T08:03:30.000Z", "freshness": { "status": "fresh", "thresholdSeconds": 300, "ageSeconds": 30, "observedAt": "2026-10-05T08:00:00.000Z", "receivedAt": "2026-10-05T08:00:01.000Z" } } }, "stale": { "summary": "Stale observation with unknown duration", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "stationId": "station-rivier", "timezone": "Europe/Amsterdam", "track": { "artist": "The Riverlights", "title": "Morning Sun", "album": null, "durationSeconds": null, "artworkUrl": "https://images.example.com/riverlights/open-water.jpg", "isPlaying": true, "observedAt": "2026-10-05T08:00:00.000Z", "receivedAt": "2026-10-05T08:00:01.000Z" }, "elapsedSeconds": null, "endsAt": null, "freshness": { "status": "stale", "thresholdSeconds": 300, "ageSeconds": 600, "observedAt": "2026-10-05T08:00:00.000Z", "receivedAt": "2026-10-05T08:00:01.000Z" } } }, "empty": { "summary": "No observations yet", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "stationId": "station-rivier", "timezone": "Europe/Amsterdam", "track": null, "elapsedSeconds": null, "endsAt": null, "freshness": { "status": "empty", "thresholdSeconds": 300, "ageSeconds": null, "observedAt": null, "receivedAt": null } } } } } } }, "304": { "description": "Not modified: your authenticated conditional request matched the current ETag. No response body; reuse your previous representation." }, "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" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "x-mint": { "metadata": { "title": "Get now playing" }, "href": "/radiotools/api-reference/public-listener/get-now-playing" } } }, "/api/v1/stations/{stationSlug}/track-history": { "get": { "summary": "Bounded published playback history", "description": "Tenant token with listener:read behind the public station gate. Omits encoder `sourceTrackId` and provider `eventId`. Each item may include `artworkUrl` when ingest or artwork lookup supplied it. Page with the returned cursor (`id` + observedAt).", "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 63 }, "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": "integer", "minimum": 1, "maximum": 100, "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", "maxLength": 512 }, "required": false, "name": "cursor", "in": "query", "description": "Opaque continuation value from nextCursor. Omit on the first request; pass the returned value unchanged." } ], "responses": { "200": { "description": "Cursor-paginated observations; legitimate repeats stay separate", "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 }, "stationId": { "type": "string", "description": "Station identifier associated with this response.", "example": "station-rivier" }, "items": { "type": "array", "items": { "type": "object", "properties": { "artist": { "type": "string", "description": "Artist reported by external automation.", "example": "The Riverlights" }, "title": { "type": "string", "description": "Human-readable title. Track titles come from external automation.", "example": "Morning Sun" }, "album": { "type": [ "string", "null" ], "description": "Reported album; null when unknown in listener responses.", "example": "Open Water" }, "durationSeconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Reported track duration in seconds; null when unknown.", "example": 210 }, "artworkUrl": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri", "description": "Artwork URL when available. May be omitted; do not assume every track has artwork.", "example": "https://images.example.com/riverlights/open-water.jpg" }, "isPlaying": { "type": "boolean", "description": "Whether the automation observation reports the track as playing.", "example": true }, "observedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the source observation occurred. Listener responses use ISO 8601 timestamps.", "example": "2026-10-05T08:00:00.000Z" }, "receivedAt": { "type": "string", "format": "date-time", "description": "Timestamp when RadioTools received the observation.", "example": "2026-10-05T08:00:01.000Z" }, "id": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Identifier of this resource. Use the value returned by the API for subsequent lookups.", "example": "observation-rivier-001" } }, "required": [ "artist", "title", "album", "durationSeconds", "isPlaying", "observedAt", "receivedAt", "id" ], "additionalProperties": false, "example": { "artist": "The Riverlights", "title": "Morning Sun", "album": "Open Water", "durationSeconds": 210, "artworkUrl": "https://images.example.com/riverlights/open-water.jpg", "isPlaying": true, "observedAt": "2026-10-05T08:00:00.000Z", "receivedAt": "2026-10-05T08:00:01.000Z", "id": "observation-rivier-001" } }, "description": "Reported observations on this page. Repeated titles at different times remain separate entries.", "example": [ { "artist": "The Riverlights", "title": "Morning Sun", "album": "Open Water", "durationSeconds": 210, "artworkUrl": "https://images.example.com/riverlights/open-water.jpg", "isPlaying": true, "observedAt": "2026-10-05T08:00:00.000Z", "receivedAt": "2026-10-05T08:00:01.000Z", "id": "observation-rivier-001" } ] }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 512, "description": "Continuation cursor for the next page; null means there are no more items. Do not construct or decode it.", "example": null } }, "required": [ "contractVersion", "stationId", "items", "nextCursor" ], "additionalProperties": false, "example": { "contractVersion": 1, "stationId": "station-rivier", "items": [ { "artist": "The Riverlights", "title": "Morning Sun", "album": "Open Water", "durationSeconds": 210, "artworkUrl": "https://images.example.com/riverlights/open-water.jpg", "isPlaying": true, "observedAt": "2026-10-05T08:00:00.000Z", "receivedAt": "2026-10-05T08:00:01.000Z", "id": "observation-rivier-001" } ], "nextCursor": null } }, "examples": { "history": { "summary": "Reported track history, final page", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "stationId": "station-rivier", "items": [ { "artist": "The Riverlights", "title": "Morning Sun", "album": "Open Water", "durationSeconds": 210, "artworkUrl": "https://images.example.com/riverlights/open-water.jpg", "isPlaying": true, "observedAt": "2026-10-05T08:00:00.000Z", "receivedAt": "2026-10-05T08:00:01.000Z", "id": "observation-rivier-001" } ], "nextCursor": null } }, "empty": { "summary": "No reported tracks", "description": "Illustrative response using fictional station data. Replace identifiers with values returned by your station.", "value": { "contractVersion": 1, "stationId": "station-rivier", "items": [], "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" } } } } } } } }, "tags": [ "Public listener" ], "security": [ { "machineToken": [] } ], "x-mint": { "metadata": { "title": "List track history" }, "href": "/radiotools/api-reference/public-listener/list-track-history" } } } }, "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." }, "integrationToken": { "type": "http", "scheme": "bearer", "bearerFormat": "rtm_…", "description": "Integration credential (playback) with ingest:write. Send Authorization: Bearer ``. Sending the rtm_ token alone without Bearer returns 401. In an API client's Bearer token field, enter only the raw rtm_ token; the client adds the prefix." } }, "schemas": { "GraphqlResponse": { "type": "object", "properties": { "data": { "type": [ "object", "null" ], "additionalProperties": {} }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer" }, "column": { "type": "integer" } }, "required": [ "line", "column" ] } }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] } }, "extensions": { "type": "object", "additionalProperties": {} } }, "required": [ "message" ] } }, "extensions": { "type": "object", "additionalProperties": {} } } }, "GraphqlFailure": { "anyOf": [ { "$ref": "#/components/schemas/GraphqlResponse" }, { "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" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "maxLength": 64 }, "suggestion": { "type": "string", "maxLength": 200 }, "retryAfter": { "type": "integer", "minimum": 1, "maximum": 86400 } }, "required": [ "path", "message" ] } } }, "required": [ "code", "message", "requestId" ] } }, "required": [ "error" ] } ] } } }, "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." } ], "servers": [ { "url": "https://radiotools.rivi.software", "description": "radiotools API" } ] }