24/7 supportRequest a demo

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/v1

Authentication

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.

curl
curl "https://api.stationmonster.com/functions/v1/api/v1/stations" \
  -H "X-API-Key: sm_live_your_key"

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.

Reply
{
  "data": [ … ],
  "has_more": true,
  "next_cursor": "eyJvIjoyNX0="
}

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" }.

400Invalid parameters, or the app refused the change: the message says why, just like in the app
401Missing, invalid, expired or revoked key or sign-in, or the person it belongs to no longer works in the company
403The 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
404Not found, or not something this key can reach
405Wrong method for this address (the Allow header lists the right ones)
409Clashes with an existing record, the record is still in use, or the first request with this Idempotency-Key is still running
412The record changed since you read it (If-Match): read it again and retry
413The request body is over 2 MB, or an upload is too big
422This Idempotency-Key was already used for a different request
429Over a limit: 120 a minute per key, 600 a minute for the company, or the key's daily limit (wait for Retry-After seconds)
5xxA 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.

Change a record only if it hasn't changed
curl -X PATCH "https://api.stationmonster.com/functions/v1/api/v1/resources/advertisers/records/ADVERTISER_ID" \
  -H "X-API-Key: sm_live_your_key" -H "Content-Type: application/json" \
  -H 'If-Match: "ETAG_FROM_GET"' -H "Idempotency-Key: 6f1c2a0e-…" \
  -d '{"phone": "555-0199"}'

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.

Try a log change first
curl -X POST "https://api.stationmonster.com/functions/v1/api/v1/stations/STATION_ID/log/entries?dry_run=true" \
  -H "X-API-Key: sm_live_your_key" -H "Content-Type: application/json" \
  -d '{"date": "2026-10-28", "media_id": "MEDIA_ID", "before_id": "LOG_ITEM_ID"}'

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.changed

A new song or item goes on air, or the now-playing text changes.

play.aired

Every item that starts playing (the as-run log).

request.received

A request or message from the listener page, with the name the listener gave.

alert.opened

A monitoring problem starts: dead air, engine down, stream offline….

alert.resolved

That problem has cleared.

log.changed

Entries were added to or removed from a day's log (publishing, imports, edits).

media.added

New 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.

A record event
{
  "id": "90412",
  "event": "ad_orders.updated",
  "station_id": "STATION_ID",
  "created_at": "2026-10-27T14:05:02Z",
  "data": {
    "resource": "ad_orders",
    "action": "updated",
    "key": {
      "id": "ORDER_ID"
    },
    "record": {
      "id": "ORDER_ID",
      "status": "active",
      "…": "…"
    },
    "changed": [
      "status"
    ],
    "previous": {
      "status": "draft"
    },
    "actor": {
      "type": "app",
      "user_id": "USER_ID"
    }
  }
}

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.

What arrives
POST /your/address
X-StationMonster-Event: now_playing.changed
X-StationMonster-Delivery: 81234
X-StationMonster-Signature: t=1793120000,v1=5d41402abc4b2a76b9719d911017c592…

{
  "id": "81234",
  "event": "now_playing.changed",
  "station_id": "STATION_ID",
  "created_at": "2026-10-27T14:03:11Z",
  "data": { "title": "Golden Hour", "artist": "JVKE", "type": "music", "media_id": "…", "text": "JVKE - Golden Hour" }
}

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.

Node.js
import crypto from "node:crypto";

function verified(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const mac = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return !!v1 && v1.length === mac.length && crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}

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).
A website sign-up form becomes a listener
[
  {
    "name": "Add the listener",
    "operation": "create_records",
    "when": [
      {
        "path": "body.email",
        "op": "exists"
      }
    ],
    "args": {
      "resource": "listeners",
      "records": {
        "station_id": "STATION_ID",
        "name": "{{body.name | trim}}",
        "email": "{{body.email | lower}}",
        "opt_in": "{{body.newsletter | bool}}"
      }
    }
  }
]

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.

Skip to the next song
curl -X POST "https://api.stationmonster.com/functions/v1/api/v1/stations/STATION_ID/playout/commands" \
  -H "X-API-Key: sm_live_your_key" -H "Content-Type: application/json" \
  -d '{"command": "play_next"}'

# { "id": "…", "command": "play_next", "engine": "cloud", "as_studio": null, "status": "sent" }

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:data

Read everything: Every record the key's person can see in the app, including all the permissions below.

write:data

Create and change: Add and edit records, run app actions and upload audio (includes Read everything).

delete:data

Delete: Delete records (needs Create and change).

control:playout

Run 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:stations

Stations: Station names, markets and time zones.

read:now_playing

Now playing: What's on air right now.

read:plays

What aired: Everything that played (as-run log).

read:log

Logs: Each day's playout log.

read:library

Library: Song, imaging and commercial details, and downloading their audio.

read:shows

Show schedule: Weekly shows and hosts.

read:requests

Listener requests: Requests and messages, including the names listeners give.

read:audience

Listener 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.

Tomorrow's pending songs
curl "https://api.stationmonster.com/functions/v1/api/v1/resources/log_items/records?station_id=eq.STATION_ID&air_date=eq.2026-10-28&item_type=eq.music&status=eq.pending&order=position.asc" \
  -H "X-API-Key: sm_live_your_key"
Add a listener, then change them
curl -X POST "https://api.stationmonster.com/functions/v1/api/v1/resources/listeners/records" \
  -H "X-API-Key: sm_live_your_key" -H "Content-Type: application/json" \
  -d '{"station_id": "STATION_ID", "first_name": "Dana", "last_name": "Ruiz", "email": "dana@example.com", "opt_in": true}'

curl -X PATCH "https://api.stationmonster.com/functions/v1/api/v1/resources/listeners/records/LISTENER_ID" \
  -H "X-API-Key: sm_live_your_key" -H "Content-Type: application/json" \
  -d '{"phone": "555-0142"}'

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.

Commercial avails for a week
curl -X POST "https://api.stationmonster.com/functions/v1/api/v1/actions/station_avails" \
  -H "X-API-Key: sm_live_your_key" -H "Content-Type: application/json" \
  -d '{"p_station": "STATION_ID", "p_from": "2026-11-02", "p_to": "2026-11-08"}'

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).

Add a commercial
# 1. Get an upload address
curl -X POST "https://api.stationmonster.com/functions/v1/api/v1/stations/STATION_ID/library/uploads" \
  -H "X-API-Key: sm_live_your_key" -H "Content-Type: application/json" -d '{"ext": "mp3", "size": 482113}'

# 2. Send the file to upload_url (with any headers the reply lists)
curl -X PUT "UPLOAD_URL" -H "Content-Type: audio/mpeg" --data-binary @spot.mp3

# 3. Create the library item
curl -X POST "https://api.stationmonster.com/functions/v1/api/v1/resources/media_items/records" \
  -H "X-API-Key: sm_live_your_key" -H "Content-Type: application/json" \
  -d '{"station_id": "STATION_ID", "title": "Main Street Motors 30", "category": "advert",
       "storage_path": "STORAGE_PATH", "storage_provider": "STORAGE_PROVIDER", "duration_ms": 30000}'

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

GET/meread:stations

Who the key acts as, its company, stations, permissions and limits.

GET/stationsread:stations

Every station the key can use, with market and time zone.

GET/stations/{station_id}read:stations

One station's details.

GET/stations/{station_id}/now-playingread:now_playing

What's on air, when it started and the now-playing text.

GET/stations/{station_id}/playsread:plays

Everything that aired, newest first.

Parameters: from, to, type, limit, cursor

GET/stations/{station_id}/logread:log

One station day's log, in order, with each entry's status.

Parameters: date

GET/stations/{station_id}/libraryread:library

Search songs, imaging and commercials.

Parameters: q, type, limit, cursor

GET/stations/{station_id}/showsread:shows

The weekly show schedule.

GET/stations/{station_id}/requestsread:requests

Listener requests and messages.

Parameters: status, limit, cursor

GET/stations/{station_id}/listenersread:audience

Listener counts once a minute, plus the peak.

Parameters: from, to

On-air controls

GET/stations/{station_id}/playoutread:now_playing

The 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.

GET/stations/{station_id}/studiosread:now_playing

The station's studio PCs: open, ready, in control, co-host, asking to join, yours.

POST/stations/{station_id}/playout/commandscontrol:playout

Skip 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

POST/stations/{station_id}/studio/controlcontrol:playout

Take on-air control for your studio PC, hand it to another studio, or release it.

Parameters: action, studio_id, take_over, dry_run

POST/stations/{station_id}/studio/cohostscontrol:playout

Let a studio's mic on air as a co-host, or take it off (Let in / Not now).

Parameters: studio_id, on, dry_run

POST/stations/{station_id}/studio/mutecontrol:playout

Mute audio in everyone's talkback headphones (never air), or turn it back on.

Parameters: on, studio_id, dry_run

POST/stations/{station_id}/now-playing/textcontrol:playout

Show your own now-playing text on streams and radio displays, or clear it.

Parameters: text, dry_run

GET/stations/{station_id}/playout/commands/{command_id}read:now_playing

Whether the engine has carried out a command yet.

Log

POST/stations/{station_id}/log/entrieswrite:data

Put a library item into a day's log, before another entry or at the end.

Parameters: date, media_id, before_id, hour, dry_run

POST/stations/{station_id}/log/entries/{item_id}/movewrite:data

Move an entry that hasn't started, like dragging it in the Studio log.

Parameters: before_id, hour, date, dry_run

POST/stations/{station_id}/log/entries/{item_id}/swapwrite:data

Two entries that haven't started trade places, like dropping one player onto another.

Parameters: with_id, dry_run

DELETE/stations/{station_id}/log/entries/{item_id}delete:data

Take an entry that hasn't started out of the log.

Parameters: dry_run

Records

GET/resourcesread:data

Every kind of record the key can work with, and what each allows.

Parameters: q

GET/resources/{resource}read:data

A resource's columns, required fields and checks.

GET/resources/{resource}/recordsread:data

Filter, sort and page through records.

Parameters: <column>=op.value, select, order, count, limit, cursor

GET/resources/{resource}/records/{id}read:data

One record by its key, with its ETag.

Parameters: select

POST/resources/{resource}/recordswrite:data

Create one record or up to 500 at once; upsert to update existing ones.

Parameters: upsert, select, dry_run

PATCH/resources/{resource}/records/{id}write:data

Change some fields of one record (If-Match for safe edits).

Parameters: if_match, select, dry_run

PATCH/resources/{resource}/recordswrite:data

Change every record matching the filters (up to 1,000).

Parameters: <column>=op.value, dry_run

DELETE/resources/{resource}/records/{id}delete:data

Delete one record.

Parameters: if_match, dry_run

DELETE/resources/{resource}/recordsdelete:data

Delete every record matching the filters (up to 1,000).

Parameters: <column>=op.value, dry_run

Actions

GET/actionsread:data

The app's own operations (publishing, moving log entries, merges, invoices, draws, reports…).

Parameters: q

POST/actions/{name}read:data

Run an action with named arguments. Ones that change data need write:data; ones that remove data need delete:data.

Parameters: dry_run

Audio

GET/stations/{station_id}/library/{media_id}/audioread:library

A download address for a library item's audio file.

POST/stations/{station_id}/library/uploadswrite:data

An upload address for a new audio file of an exact size, to add or replace a library item.

Parameters: ext, size

What aired in the last hour
curl "https://api.stationmonster.com/functions/v1/api/v1/stations/STATION_ID/plays?type=music&from=2026-10-27T13:00:00Z" \
  -H "X-API-Key: sm_live_your_key"
JavaScript (server side)
const res = await fetch(`https://api.stationmonster.com/functions/v1/api/v1/stations/${stationId}/now-playing`, {
  headers: { "X-API-Key": process.env.STATIONMONSTER_KEY },
});
const { title, artist, started_at } = await res.json();

Missing an endpoint?

Tell us what you'd like to build. We add to the API based on what customers ask for.