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.
  • GET reads. When operations that change data arrive, POST creates or acts, PATCH edits, and DELETE removes.
  • 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.