Developers · API
The StationMonster API.
A REST API that can read, create, change and delete almost everything in your stations: logs, the library and its audio, music scheduling, traffic and sales, listeners, contests, news, websites and settings. JSON over HTTPS.
OpenAPI document (JSON)Base URL
https://api.stationmonster.com/functions/v1/api/v1Authentication
Keys are made in the app under Organization › API keys. Send one on every request in the X-API-Key header (Authorization: Bearer works too).
Every key works as one person. Company admins can make keys for anyone in the company, market managers for people in their markets, and employees for themselves when their company allows it. Everything a key does goes through the same checks as its person in the app, so it can never do more than they can, and changes show in the Activity log under their name. If the person leaves or loses access, the key stops working.
Keys can be narrowed further: read, change or delete; some stations; only certain job permissions (this also turns off manager and admin powers); only certain kinds of records or actions; the REST API, AI assistants (MCP) or both; and fixed IP addresses. GET /me shows a key's person and limits.
Apps can sign in instead. The API also accepts OAuth access tokens (Authorization: Bearer sm_oat_…) from the same sign-in AI assistants use: authorization code with PKCE, issuer https://stationmonster.com, metadata at https://stationmonster.com/.well-known/oauth-authorization-server. The person approving chooses what the app may do.
Keys start with sm_live_. They're shown once when created and stored only as a fingerprint, so we can't show them again. Keep them on your server, never in browser code or an app people download. To show now playing on a public web page, use the listener page feed instead, which needs no key.
Pagination
Lists return up to limit records (1–100, default 25). When there are more, the reply says so and gives a cursor. Send it back as cursor with the same filters until has_more is false.
Times are ISO 8601 in UTC. Log dates are station days in the station's own time zone, which every station record includes.
Errors
Errors come back with the HTTP status and a JSON body like { "error": "…", "required_scope": "read:plays" }.
| 400 | Invalid parameters, or the app refused the change: the message says why, just like in the app |
| 401 | Missing, invalid, expired or revoked key or sign-in, or the person it belongs to no longer works in the company |
| 403 | The key doesn't have the permission this needs (named in required_scope), its limits rule it out (stations, records (needs_resources), actions, IP address, API or MCP only), or its person isn't allowed to do it |
| 404 | Not found, or not something this key can reach |
| 405 | Wrong method for this address (the Allow header lists the right ones) |
| 409 | Clashes with an existing record, the record is still in use, or the first request with this Idempotency-Key is still running |
| 412 | The record changed since you read it (If-Match): read it again and retry |
| 413 | The request body is over 2 MB, or an upload is too big |
| 422 | This Idempotency-Key was already used for a different request |
| 429 | Over a limit: 120 a minute per key, 600 a minute for the company, or the key's daily limit (wait for Retry-After seconds) |
| 5xx | A temporary problem on our side: try the same request again |
Rate limits
Each key may make 120 requests per minute, shared between the API and the MCP server, and all of a company's keys together 600 per minute. A key can also get a daily limit (midnight to midnight UTC). Over a limit you get 429 with a Retry-After header and a message saying which limit it was.
History next to each key in Organization › API keys lists its requests from the last 30 days: what it did, the answer it got, how long it took and any error.
Safe retries & edits
Retries. Send an Idempotency-Key header (a new UUID per request) on any POST, PATCH or DELETE. If the connection drops and you send the same request again with the same key, you get the first answer back (with Idempotent-Replayed: true) instead of the change happening twice. Answers are kept for 24 hours.
Edits. GET …/records/{id} answers with an ETag header. Send it back as If-Match when you change or delete that record: if someone changed it in the meantime, nothing happens and you get 412.
Test mode
Add dry_run=true to a create, change, delete, log edit or action. Everything runs with every rule and check, then it's all undone: the answer (marked "dry_run": true) shows what would have happened, and nothing is saved, aired or sent. Use it while building, or to let an AI assistant show a change before making it.
Outgoing webhooks
Instead of asking over and over, let us tell you. Add a webhook in Organization › API keys › Outgoing webhooks with your https address and the events you want. Like keys, a webhook belongs to the person who made it and only covers stations they work at.
Built-in events cover what's happening on air:
now_playing.changedA new song or item goes on air, or the now-playing text changes.
play.airedEvery item that starts playing (the as-run log).
request.receivedA request or message from the listener page, with the name the listener gave.
alert.openedA monitoring problem starts: dead air, engine down, stream offline….
alert.resolvedThat problem has cleared.
log.changedEntries were added to or removed from a day's log (publishing, imports, edits).
media.addedNew songs, imaging or commercials in the library.
Record events cover everything else. Every resource (the same ones as Records) sends <resource>.created, <resource>.updated and <resource>.deleted: library items, log entries, clocks and rules, carts, orders, spots and invoices, payments, deals and proposals, listeners, contest entries and winners, phone calls, news stories, shifts and timesheets, engineering tickets, website pages and form answers, settings and more. Subscribe to <resource>.* for all three, *.created for one kind of change everywhere, or * for every record change. You only get records the webhook's person can see in the app: each record is read back as them, so money, listener details and sales accounts stay walled exactly as in the app. Optional filters per resource, written like the API's ({"media_items": {"category": "eq.song"}}), narrow it further.
record is the record as it is when the event is sent (for deletes: as it was). changed and previous come with updates; bookkeeping-only changes (like a last-seen time) aren't sent. actor.type is app (someone in the app), api (an API key or connected app) or system (automatic work, like the engine or a schedule).
Each event is a POST with a JSON body, usually within a few seconds. Answer with any 2xx within 10 seconds. Anything else is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. Redirects aren't followed. After 100 failures in a row the webhook turns itself off. Send test sends a ping event.
Check the signature before trusting a delivery: compute HMAC-SHA256 of <t>.<raw body> with your webhook's signing secret and compare it with v1. Refuse deliveries whose t is more than 5 minutes old. The same event can arrive twice: use id to skip repeats.
Incoming webhooks
The other way round: give another service an address to send its webhooks to, and StationMonster acts on them. Add one in Organization › API keys › Incoming webhooks. Its address looks like https://api.stationmonster.com/functions/v1/hooks/sm_hook_… and is shown once. Website forms, Zapier or Make, ticketing and payment services, your phone system or your own code can then add listeners and contest entries, book orders, put songs in the log, fire carts, skip songs, post news or do anything else the API can.
Each incoming webhook runs as one of your own API keys, with exactly that key's permissions, stations, limits and rate limit. A delivery runs up to 10 steps, each one of the API's operations (the tool names under Endpoints), with arguments filled in from the delivery:
{{body.contact.email}},{{body.items[0].title}},{{headers.x-event}},{{query.station}},{{now}},{{today}}. A value that's only a placeholder keeps its type (a number, a list, an object); inside other text it's written in.- Filters after a bar:
{{body.name | trim | default:"Listener"}}. Available: default, lower, upper, trim, string, number, int, bool, json, parse, date, datetime, first, last, join, split, truncate. - Only when conditions (is, isn't, contains, is one of, matches pattern, more/less than, filled in, empty) let one address handle several kinds of events, and For each item in runs a step once per item of a list (
{{item.…}}, up to 100).
Check the sender with one of these:
Secret address only
Anyone with the address can send. Fine for tools that can't sign their deliveries.
Shared secret header
The sender puts your secret in a header, e.g. X-Gitlab-Token, or Authorization with "Bearer " in front.
HMAC signature
A header carries an HMAC of the body (GitHub: X-Hub-Signature-256 with sha256= in front; Shopify: base64).
Stripe-style t=…,v1=…
Stripe-Signature, or X-StationMonster-Signature from another StationMonster webhook. Checked within 5 minutes.
Standard Webhooks
webhook-id / webhook-timestamp / webhook-signature (Svix, Clerk, Resend and more). Repeats are skipped by webhook-id.
Deliveries can be JSON, form posts or plain text, up to 1 MB. The answer is 200 with each step's result when everything worked, or the first failing step's status (so the sender tries again). Skip repeats by (e.g. {{headers.x-github-delivery}}) answers a repeat within 24 hours without running it again. Slack-style url_verification and Meta-style hub.challenge checks are answered for you (Meta's verify token = the signing secret).
Test mode runs every step as a dry run, so nothing is saved, and Try it in the app runs a pasted sample the same way. Received shows the last deliveries with each step's answer (kept 30 days), and every step shows in the key's History.
Running the Studio
Skip, play and stop over the API like pressing the Studio's buttons: play_next (skip: the next item starts and what's on air fades out as at a segue), play_player, stop_player, pause_player and recue_player (players 1–3), stop_all, set_mode (auto or assist), jump_to a log entry, fire_cart and set_level (move the player1–player3 or carts fader: 0 = off, 0.75 = the U mark, 1 = top; cloud engine only, and the Studio's faders follow). It needs the control:playout permission (Run the air), which no other permission includes.
The rest of the Studio works the same way: GET …/studios lists the station's studio PCs, POST …/studio/control takes on-air control for a studio PC the key's person has open (take), gives it to another open studio (hand) or releases it (release), POST …/studio/cohosts lets a studio's mic on air as a co-host or takes it off, POST …/studio/mute turns Mute audio on or off in everyone's talkback headphones (never air), and POST …/now-playing/text shows your own text on streams and radio displays until you clear it. The log is edited with add_log_entry, move_log_entry, swap_log_entries and remove_log_entry; segues, notes, carts and requests are records (log_items, studio_notes, carts, song_requests). Mic switches stay on the studio PC: no app can put a mic on air.
The Studio's rules apply. The key's person must be able to run the air now: from 30 minutes before their scheduled shift, or any time with On-air control any time. While a studio holds on-air control, only commands from that studio's own person count. Others get 409 naming the studio, unless they send take_over: true with On-air control any time, which releases control first. Works with the cloud engine, and with the browser engine while a studio is playing the log. GET …/playout shows the players, fader levels, the now-playing text, who holds control, co-hosts and studios asking to join, Mute audio, and whether the key may act (can_operate, can_take_over).
Commands run within a few seconds. GET …/playout/commands/{id} says waiting, done or expired (not picked up within 30 seconds, so it was dropped and never runs late). Each command shows in the Activity log under the person's name, with the key.
Permissions
Every endpoint needs one permission. read:data covers all the narrower read permissions, write:data includes read:data, and delete:data needs write:data. control:playout is only ever given on its own. A key never gains new permissions by itself: to add one, edit the key.
read:dataRead everything: Every record the key's person can see in the app, including all the permissions below.
write:dataCreate and change: Add and edit records, run app actions and upload audio (includes Read everything).
delete:dataDelete: Delete records (needs Create and change).
control:playoutRun the air: Run the whole Studio: players, carts, faders, auto/assist, on-air control, co-hosts, Mute audio and the now-playing text (not included in anything else).
read:stationsStations: Station names, markets and time zones.
read:now_playingNow playing: What's on air right now.
read:playsWhat aired: Everything that played (as-run log).
read:logLogs: Each day's playout log.
read:libraryLibrary: Song, imaging and commercial details, and downloading their audio.
read:showsShow schedule: Weekly shows and hosts.
read:requestsListener requests: Requests and messages, including the names listeners give.
read:audienceListener counts: Stream listeners, once a minute.
Records
Almost everything in the app is a resource you can list, read, create, change and delete: media_items (the library), log_items, carts, ms_clocks, advertisers, ad_orders, crm_opportunities, listeners, contests, news_stories, station_shows, site_articles, station settings and many more. GET /resources lists every one your key can use; GET /resources/{resource} shows its columns and which are required.
Filter with any column as a query parameter, written column=operator.value: eq, neq, gt, gte, lt, lte, like/ilike (* is a wildcard), in.(a,b), nin.(a,b), is.null, is.not_null, and cs/cd/ov for lists. Repeat a column for a range. Sort with order=air_date.asc,position.asc, pick columns with select, and add count=true for the total. Lists page up to 500 records at a time.
POST takes one record or a list of up to 500 (all saved or none); add upsert=true to update records whose key already exists. PATCH and DELETE work on one record by its key, or on every record matching your filters (at least one filter, up to 1,000 records). Records keyed by more than one column, like a station's settings per hour, are changed with filters.
Actions
Some jobs change many records together and follow the app's rules, like publishing a music log, moving a log entry, placing voice tracks, merging duplicate songs, booking a sponsorship, creating an invoice or drawing contest winners. Those are actions: GET /actions lists them with their arguments, and POST /actions/{name} runs one. Actions that change data need write:data, and ones that remove data (delete, merge, reset, void, revoke, unpublish…) need delete:data, just like deleting records. With only read:data a key can run the ones that just read, like avails and reports. GET /actions shows what each one needs.
Audio files
GET /stations/{station_id}/library/{media_id}/audio returns a download address for an item's audio, valid for 6 hours. To add audio, ask for an upload address with the file's exact size in bytes, send the file to it, then create the library item pointing at it. Files are stored exactly as you send them (up to 100 MB, or 1 GB when your audio is kept in cloud storage).
Endpoints
The OpenAPI document above lists each parameter in full, and imports straight into Postman, Insomnia or an OpenAPI code generator. For JavaScript, TypeScript and Python, use the official SDKs.
Stations & on air
/meread:stationsWho the key acts as, its company, stations, permissions and limits.
/stationsread:stationsEvery station the key can use, with market and time zone.
/stations/{station_id}read:stationsOne station's details.
/stations/{station_id}/now-playingread:now_playingWhat's on air, when it started and the now-playing text.
/stations/{station_id}/playsread:playsEverything that aired, newest first.
Parameters: from, to, type, limit, cursor
/stations/{station_id}/logread:logOne station day's log, in order, with each entry's status.
Parameters: date
/stations/{station_id}/libraryread:librarySearch songs, imaging and commercials.
Parameters: q, type, limit, cursor
/stations/{station_id}/showsread:showsThe weekly show schedule.
/stations/{station_id}/requestsread:requestsListener requests and messages.
Parameters: status, limit, cursor
/stations/{station_id}/listenersread:audienceListener counts once a minute, plus the peak.
Parameters: from, to
On-air controls
/stations/{station_id}/playoutread:now_playingThe players, fader levels, auto or assist, now-playing text, who holds on-air control, co-hosts and requests to join, Mute audio, and whether the key's person may run the air now.
/stations/{station_id}/studiosread:now_playingThe station's studio PCs: open, ready, in control, co-host, asking to join, yours.
/stations/{station_id}/playout/commandscontrol:playoutSkip to the next item, play, stop, pause or recue a player, stop everything, switch auto/assist, jump to a log entry, fire a cart or move a fader.
Parameters: command, player, fade, mode, log_item_id, cart_id, fader, level, take_over, dry_run
/stations/{station_id}/studio/controlcontrol:playoutTake on-air control for your studio PC, hand it to another studio, or release it.
Parameters: action, studio_id, take_over, dry_run
/stations/{station_id}/studio/cohostscontrol:playoutLet a studio's mic on air as a co-host, or take it off (Let in / Not now).
Parameters: studio_id, on, dry_run
/stations/{station_id}/studio/mutecontrol:playoutMute audio in everyone's talkback headphones (never air), or turn it back on.
Parameters: on, studio_id, dry_run
/stations/{station_id}/now-playing/textcontrol:playoutShow your own now-playing text on streams and radio displays, or clear it.
Parameters: text, dry_run
/stations/{station_id}/playout/commands/{command_id}read:now_playingWhether the engine has carried out a command yet.
Log
/stations/{station_id}/log/entrieswrite:dataPut a library item into a day's log, before another entry or at the end.
Parameters: date, media_id, before_id, hour, dry_run
/stations/{station_id}/log/entries/{item_id}/movewrite:dataMove an entry that hasn't started, like dragging it in the Studio log.
Parameters: before_id, hour, date, dry_run
/stations/{station_id}/log/entries/{item_id}/swapwrite:dataTwo entries that haven't started trade places, like dropping one player onto another.
Parameters: with_id, dry_run
/stations/{station_id}/log/entries/{item_id}delete:dataTake an entry that hasn't started out of the log.
Parameters: dry_run
Records
/resourcesread:dataEvery kind of record the key can work with, and what each allows.
Parameters: q
/resources/{resource}read:dataA resource's columns, required fields and checks.
/resources/{resource}/recordsread:dataFilter, sort and page through records.
Parameters: <column>=op.value, select, order, count, limit, cursor
/resources/{resource}/records/{id}read:dataOne record by its key, with its ETag.
Parameters: select
/resources/{resource}/recordswrite:dataCreate one record or up to 500 at once; upsert to update existing ones.
Parameters: upsert, select, dry_run
/resources/{resource}/records/{id}write:dataChange some fields of one record (If-Match for safe edits).
Parameters: if_match, select, dry_run
/resources/{resource}/recordswrite:dataChange every record matching the filters (up to 1,000).
Parameters: <column>=op.value, dry_run
/resources/{resource}/records/{id}delete:dataDelete one record.
Parameters: if_match, dry_run
/resources/{resource}/recordsdelete:dataDelete every record matching the filters (up to 1,000).
Parameters: <column>=op.value, dry_run
Actions
/actionsread:dataThe app's own operations (publishing, moving log entries, merges, invoices, draws, reports…).
Parameters: q
/actions/{name}read:dataRun an action with named arguments. Ones that change data need write:data; ones that remove data need delete:data.
Parameters: dry_run
Audio
/stations/{station_id}/library/{media_id}/audioread:libraryA download address for a library item's audio file.
/stations/{station_id}/library/uploadswrite:dataAn upload address for a new audio file of an exact size, to add or replace a library item.
Parameters: ext, size
Missing an endpoint?
Tell us what you'd like to build. We add to the API based on what customers ask for.


