# 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: ```json { "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](https://gumball.fm/developers/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](https://gumball.fm/developers/changelog).