Conventions
Requests and responses
Every operation in version 1 follows the rules on this page.
- The base URL is
https://api.gumball.fm. Every path starts with/v1. - Requests and responses are JSON. Field names are
snake_case. GETreads. When operations that change data arrive,POSTcreates or acts,PATCHedits, andDELETEremoves.- A parameter the operation doesn't have is refused with
invalid_request, so a typo in a filter name can't pass unnoticed.
IDs
An ID is a string with a prefix that names its type:
| Prefix | Record |
|---|---|
user_ |
A user |
show_ |
A show |
slot_ |
An ad slot |
camp_ |
A campaign |
Treat the rest of the ID as opaque. An ID of the wrong type is refused with invalid_request.
Money
An amount of money is whole cents plus a currency. This is $1,250.00:
{ "amount": 125000, "currency": "usd" }
A CPM follows the same rule.
Dates and times
| Field name ends in | Format | Example |
|---|---|---|
_at |
A moment in time: RFC 3339, in UTC | "2026-11-14T18:30:00Z" |
_date |
A calendar day, in US Eastern Time | "2026-12-01" |
An air date is a calendar day. An episode that drops on the evening of December 1 in New York has the air date 2026-12-01, even though the moment falls on December 2 in UTC.
Empty fields
A field with no value is null. It's never left out, so a field in the reference is always present in the response.
Related records
A related record arrives as a small summary with its ID and name. To get the whole record, call its own operation with that ID.
Filters and order
A list takes its filters as plain named parameters, and has one fixed order. The API reference lists both per operation.
Lists of allowed values
A field with a fixed set of values can gain a value in a later release. Write your code to tolerate a value it doesn't know.
Versions
- Adding an operation, a field, an optional parameter, or an allowed value doesn't change the version. Your code must ignore fields it doesn't know.
- A breaking change gets a new version in the path,
/v2. - For what can change in version 1, see the Changelog.
Read this page as plain text.