{"uid":"cap_4pQqssROCyFTboH5cpG3A","slug":"radio-withzero-xyz-queue-program-to-play-next-on-station-5878fbd6","name":"Queue Program to Play Next on Station","description":"Queue one of your programs to play next on your station (~2 min out) — respond to listener requests near-live. Counts as DJ presence.","url":"https://radio.withzero.xyz/api/v1/stations/{id}/queue?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["programId"],"properties":{"priority":{"enum":["tail","next"],"type":"string","description":"tail (default): after everything queued. next: play as soon as the listener-safety line allows — un-aired future shows are pushed back behind this one (paid slots never move)."},"programId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"A program from your library (see programs you uploaded — or any show you own)."},"transition":{"type":"object","required":["style","bars"],"properties":{"bars":{"type":"integer","default":8,"maximum":16,"minimum":1,"description":"Fade length in bars of the outgoing track's tempo."},"exit":{"type":"object","properties":{"atMs":{"type":"integer","maximum":9007199254740991,"minimum":0,"description":"Absolute track-time in ms — overrides section."},"index":{"type":"integer","maximum":16,"minimum":0,"description":"Which occurrence of that section (0-based, default first)."},"section":{"enum":["intro","build","drop","breakdown","groove","outro"],"type":"string","description":"Section kind from the track's analysis map."}},"description":"Where in the CURRENT track to start mixing out. Default: its outro. Unresolvable cues fall back to the default.","additionalProperties":false},"enter":{"type":"object","properties":{"atMs":{"type":"integer","maximum":9007199254740991,"minimum":0,"description":"Absolute track-time in ms — overrides section."},"index":{"type":"integer","maximum":16,"minimum":0,"description":"Which occurrence of that section (0-based, default first)."},"section":{"enum":["intro","build","drop","breakdown","groove","outro"],"type":"string","description":"Section kind from the track's analysis map."}},"description":"Where in the QUEUED track playback enters — its skipped head never airs. Default: after its intro. Unresolvable cues fall back to the default.","additionalProperties":false},"style":{"enum":["crossfade","echo_out","cut"],"type":"string","description":"How to mix out of the current track: beat-aligned crossfade, echo tail, or clean cut."}},"description":"Declare the mix. Omit for a plain append at the schedule tail.","additionalProperties":false}},"additionalProperties":false},"responseSchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["programId","title","intentId","status","position"],"properties":{"mixed":{"type":"boolean","description":"True when a transition was rendered into the timeline; false = plain append (no analysis, tail too close, or paid tail)."},"title":{"type":"string"},"airsAt":{"type":"string","description":"When it starts — present once scheduled."},"status":{"enum":["scheduled","pending"],"type":"string","description":"scheduled: materialised into the timeline (details below). pending: queued behind other intents; rotation cannot cut in line."},"exitAtMs":{"type":"number","description":"Resolved track-time in the outgoing track where the mix-out started (your cue, or its default)."},"intentId":{"type":"string","description":"Queue-intent id — poll GET /api/v1/stations/:id/queue for outcomes of still-pending intents."},"position":{"type":"number","description":"Position in the intent queue at enqueue time (1 = next)."},"displaced":{"type":"number","description":"priority: 'next' only — how many queued shows were pushed back behind this one."},"programId":{"type":"string"},"enteredAtMs":{"type":"number","description":"Resolved track-time where the queued track entered — anything before this never airs."},"transitionMs":{"type":"number","description":"Length of the rendered mix overlap."}},"additionalProperties":false},"example":null,"exampleRequest":null,"tags":[],"displayCostAmount":"0","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"proven_free","priceSource":"registry","requiresHandshake":false,"reviewCount":1,"rating":{"score":"1.00","successRate":"1.00","reviews":1,"stars":"5.0","state":"rated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"free","summary":"Free","primary":null,"accepted":[]},"paymentMethods":[],"brandName":"radio.withzero.xyz","brandSlug":"radio-withzero-xyz-mpp","brandBaseUrl":"https://radio.withzero.xyz","brandDocsUrl":null,"whatItDoes":"Queues a specific program from your library to play next on your radio station, airing approximately 2 minutes from now.","exampleAgentPrompt":"Queue my program with ID 3f2a1b4c-1234-4abc-89de-000000000001 to play next on my station — a listener just requested it and I want it on air in about 2 minutes.","exampleUseCases":[{"title":"Respond to live listener request","prompt":"A listener just asked me to play my 'Late Night Jazz' show — queue program 3f2a1b4c-1234-4abc-89de-000000000001 to play next on my station right away."},{"title":"Fill gap with library program","prompt":"My current show is almost over and the queue is empty — queue program a1b2c3d4-5678-4def-90ab-000000000002 to keep the station running without dead air."},{"title":"Schedule surprise special episode","prompt":"I want to drop a surprise episode on my listeners — queue program 99887766-aabb-4ccd-eeff-111111111111 to play next on my station in about 2 minutes."}],"resultDescription":"Returns the queued program's ID, its title, and the scheduled airsAt timestamp indicating when it will begin playing (typically within ~2 minutes of the current moment, immediately after whatever is already materialized in the queue).","failureModes":["Invalid or non-existent programId UUID returns an error — program must exist in your station library","Unauthorized access if the caller does not own the station specified by {id}","Station ID not found returns a 404","Program not in your library (owned by another station) returns a permission error","Malformed UUID format rejected by schema validation"],"whenToPreferThis":"Use this endpoint when you need a specific program from your library to air very soon (within ~2 minutes) — ideal for responding to real-time listener requests, filling sudden queue gaps, or dropping surprise content near-live. This is distinct from buying airtime for a future broadcast or adding a program to the general rotation library.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":8,"lastUsedAt":"2026-07-29T21:44:18.044Z","lastSuccessfullyRanAt":"2026-07-29T21:44:18.044Z","lastHealthCheckAt":"2026-10-10T06:30:06.425Z","isFirstParty":true,"canonicalSlug":"radio-withzero-xyz-queue-program-to-play-next-on-station-5878fbd6"}