Godcaster · API Overview · For Station Teams
Your Godcaster dashboard already holds your players, your programs, your episodes, and your listening numbers. The Godcaster API lets your website, mobile app, lobby screen, or newsletter tool pull that same information automatically — no copying and pasting, no manual updates. And it now works in both directions: the same key that reads your data can also manage your lineup, colors, artwork, and settings. This guide explains what a standard station API key can do, and what a radio station might do with it.
A quick word on how it works: every request is a simple web address. Your station's API key — found in your Godcaster dashboard — goes along with the request to prove it's you. The answer comes back as structured data (JSON) that any web developer, app builder, or no-code tool can read. Hand this guide to whoever runs your website and they'll know exactly what to do with it.
Your key works for the players your station owns. You can't pull another station's private information, and nobody can pull yours. The same rule holds for changes: only your own key can modify your players.
Part One · Pulling data out What your website, app, or reports can read from Godcaster.
The complete picture of one player, in a single request.
A "player" in Godcaster is the curated lineup you present to listeners — the shows you carry, in the look and order you chose. This request returns everything about one player: its name, description, and artwork; your brand colors and styling; your location and timezone; your website and support links; and every program on the player, each with its 50 most recent episodes — titles, artwork, descriptions, publish dates, durations, and the audio itself.
Your player's ID number is shown in the dashboard.
ON AIRLive streams and live episodes carried on your player are included and flagged as live, so your website can show a "live now" indicator the moment you go on air.
The same figures as your dashboard's stats page, ready for reports.
This request returns the current month's listening activity for one of your players: how many plays, downloads, shares, page visits, follows, and support clicks you've received — plus breakdowns by episode, by program, by listener location, by device, by traffic source, and by podcast app.
Details and recent episodes for a single program.
Where player data gives you the whole lineup, this request zooms in on one program: its title, host, description, artwork, website, and donation link, along with its 50 most recent episodes. It's the right choice when a single show deserves its own spotlight.
For stations that organize players into themed groups.
If your station groups players into collections — by genre, by language, by ministry, by sister station — these requests return those groupings so your website can mirror them. There are three flavors, from full detail to a fast, lightweight listing:
All three begin with https://api.godcaster.fm — shortened here to fit.
Part Two · Making changes The same key can now manage your players — every change takes effect right away, just like editing in the dashboard.
Curate a player's program lineup without opening the dashboard.
These requests let your own tools manage what's on a player. You can list the current lineup in display order, add a program, remove one, or submit a complete new running order. When you add a program Godcaster doesn't know yet, it looks up the show's title, artwork, and details automatically — you only supply the program's ID number. There's a catalog search to find that number by name, and you can even create a brand-new player from scratch.
All addresses begin with https://api.godcaster.fm — shortened here to fit.
ON AIRLive-stream tiles on a player are protected: they can be reordered along with everything else, but adding or removing them stays in the dashboard's player settings screen.
Everything on the dashboard's player settings page, readable and writable.
Three groups of requests cover a player's appearance and behavior. Colors reads or updates the player's full color scheme — change one color or all seventeen, or reset the whole scheme back to the defaults. Image uploads new player artwork (JPEG or PNG, up to 4 MB). Settings reads or updates the rest: the player's title, layout style, how many programs and episodes to display, description, website, donation link, location, and toggles like the public directory listing and Open Mic. Change your player's location and Godcaster re-maps it and updates the timezone for you.
Authorization header. That's the only
setup there is.