# replenish Radio Station Retained recommendation Worker adapter. Automatic retries are disabled. Maximum UTF-8 request body: 24576 bytes. Operation: replenishRadioStation POST /api/recommendation/radio/station/{id} Access: radio-capability. Automatic retries: none. Redirects: manual. Request body limit: 24576 bytes. Default timeout: 30 seconds. Response limit: 16 MiB. Pagination is opt-in and bounded; an exhausted bound reports incomplete execution. [HTML reference](/developers/api/replenishRadioStation) ยท [Authoritative schemas](/api/openapi.json) ## Wire contract ```json { "operationId": "replenishRadioStation", "summary": "replenish Radio Station", "tags": [ "recommendation" ], "description": "Retained recommendation Worker adapter. Automatic retries are disabled. Maximum UTF-8 request body: 24576 bytes.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "RadioCapability": [] } ], "x-public-access": "radio-capability", "x-public-side-effect": "provider-read", "x-public-body-limit": 24576, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "1" }, "stationSeed": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "affinities": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24}$" }, "weight": { "type": "number", "minimum": 0, "maximum": 100 }, "reasonCodes": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "recording-id", "recording-name", "artist-id", "artist-name", "album-id", "album-name", "genre", "semantic", "avoid" ] } } }, "required": [ "canonicalId", "weight", "reasonCodes" ], "additionalProperties": false } }, "votes": { "maxItems": 30, "type": "array", "items": { "type": "object", "properties": { "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24}$" }, "direction": { "type": "string", "enum": [ "more", "less" ] }, "evidence": { "default": "explicit", "type": "string", "enum": [ "explicit", "completion", "early-skip" ] }, "weight": { "default": 1, "type": "number", "minimum": 0.05, "maximum": 1 } }, "required": [ "canonicalId", "direction" ], "additionalProperties": false } }, "hardExclusions": { "maxItems": 30, "type": "array", "items": { "type": "string", "pattern": "^itm_[a-f0-9]{24}$" } }, "recentCanonicalIds": { "maxItems": 60, "type": "array", "items": { "type": "string", "pattern": "^itm_[a-f0-9]{24}$" } }, "intent": { "type": "string", "minLength": 3, "maxLength": 160 }, "genre": { "type": "string", "minLength": 1, "maxLength": 80 }, "context": { "type": "object", "properties": { "timeOfDay": { "type": "string", "enum": [ "dawn", "morning", "afternoon", "evening", "night" ] }, "weatherKind": { "type": "string", "enum": [ "clear", "cloudy", "fog", "drizzle", "rain", "snow", "storm", "unknown" ] }, "calendarKind": { "type": "string", "enum": [ "weekday", "weekend", "holiday" ] }, "daylight": { "type": "string", "enum": [ "day", "night", "unknown" ] }, "season": { "type": "string", "enum": [ "spring", "summer", "autumn", "winter", "unknown" ] } }, "required": [ "timeOfDay", "weatherKind", "calendarKind" ], "additionalProperties": false }, "continuation": { "type": "object", "properties": { "version": { "const": "1" }, "played": { "maxItems": 120, "type": "array", "items": { "type": "object", "properties": { "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24}$" }, "playedAt": { "type": "integer", "minimum": 0, "maximum": 8640000000000000 } }, "required": [ "canonicalId", "playedAt" ], "additionalProperties": false } }, "queuedCanonicalIds": { "maxItems": 12, "type": "array", "items": { "type": "string", "pattern": "^itm_[a-f0-9]{24}$" } }, "position": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, "required": [ "version", "played", "queuedCanonicalIds", "position" ], "additionalProperties": false }, "limit": { "default": 6, "type": "integer", "minimum": 1, "maximum": 6 } }, "required": [ "schemaVersion", "stationSeed", "affinities", "votes", "hardExclusions", "recentCanonicalIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "1" }, "status": { "type": "string", "enum": [ "ready", "empty", "degraded" ] }, "profile": { "type": "object", "properties": { "seedCount": { "type": "integer", "minimum": 0 }, "positiveVoteCount": { "type": "integer", "minimum": 0 }, "negativeVoteCount": { "type": "integer", "minimum": 0 }, "intentApplied": { "type": "boolean" }, "contextApplied": { "type": "boolean" } }, "required": [ "seedCount", "positiveVoteCount", "negativeVoteCount", "intentApplied", "contextApplied" ], "additionalProperties": false }, "tracks": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "canonicalId": { "type": "string", "pattern": "^itm_[a-f0-9]{24}$" }, "title": { "type": "string", "minLength": 1 }, "artist": { "type": "string", "minLength": 1 }, "genres": { "type": "array", "items": { "type": "string" } }, "spotifyUri": { "type": "string", "pattern": "^spotify:track:[A-Za-z0-9]{10,64}$" }, "spotifyUrl": { "type": "string", "format": "uri" }, "itemPath": { "type": "string", "pattern": "^\\/" }, "reasonCodes": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "profile-affinity", "session-more", "intent-adjacent", "context-adjacent", "musical-neighbor", "exploration", "editorial-core", "editorial-recurrent", "underplayed", "contrast", "discovery", "transition-fit" ] } }, "programming": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "core-opener", "adjacent", "deep-cut", "listener-affinity", "contrast", "discovery" ] }, "rotation": { "type": "string", "enum": [ "core", "recurrent", "deep-cut", "discovery" ] } }, "required": [ "role", "rotation" ], "additionalProperties": false } }, "required": [ "canonicalId", "title", "artist", "genres", "spotifyUri", "spotifyUrl", "itemPath", "reasonCodes" ], "additionalProperties": false } }, "diagnostics": { "type": "object", "properties": { "profileVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "candidateCount": { "type": "integer", "minimum": 0 }, "eligibleCount": { "type": "integer", "minimum": 0 }, "fallback": { "type": "boolean" }, "cooldownRelaxed": { "type": "boolean" }, "contextSignals": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "time-of-day", "weather", "daylight", "season" ] } }, "clock": { "type": "string", "minLength": 1, "maxLength": 80 }, "slots": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 1, "maximum": 6 }, "role": { "type": "string", "enum": [ "core-opener", "adjacent", "deep-cut", "listener-affinity", "contrast", "discovery" ] }, "candidateCount": { "type": "integer", "minimum": 0 }, "shortlistSize": { "type": "integer", "minimum": 0, "maximum": 8 }, "selectedRank": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 8 }, { "type": "null" } ] }, "relaxedRules": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "artist-separation", "sound-family-separation", "album-separation" ] } } }, "required": [ "position", "role", "candidateCount", "shortlistSize", "selectedRank", "relaxedRules" ], "additionalProperties": false } } }, "required": [ "profileVersion", "candidateCount", "eligibleCount", "fallback" ], "additionalProperties": false } }, "required": [ "schemaVersion", "status", "profile", "tracks", "diagnostics" ], "additionalProperties": false } } } }, "400": { "description": "Request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "description": "Request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Request failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } ``` ## Synthetic examples ### curl ```bash curl --fail-with-body --max-time 30 --max-filesize 16777216 --request POST 'https://irvinebroque.com/api/recommendation/radio/station/fixture' --header 'Accept: application/json' --header "Authorization: Bearer $RADIO_CAPABILITY" --header 'Content-Type: application/json' --data-binary @request.json ``` ### TypeScript ```typescript import { PublicApi } from '@irvinebroque/public-api'; const api = new PublicApi(); const capability = 'replace-with-scoped-radio-capability'; const result = await api.radio.replenish({ "id": "fixture", "body": { "schemaVersion": "1", "stationSeed": "fixture", "affinities": [], "votes": [], "hardExclusions": [], "recentCanonicalIds": [] } }, { capability }); console.log(result.status, result.headers.get('content-type')); // Keep transient capabilities in memory. ``` ### CLI ```bash irvinebroque radio replenish --id 'fixture' --body-file request.json --capability "$RADIO_CAPABILITY" ``` ### request.json ```json { "schemaVersion": "1", "stationSeed": "fixture", "affinities": [], "votes": [], "hardExclusions": [], "recentCanonicalIds": [] } ```