Getting started

What the API does

The Gumball API lets your code do what you do on gumball.fm. An advertiser searches shows, reads prices, open ad slots, bookings, and invoices, builds a campaign, and reserves ad slots. A creator reads their shows, schedule, bookings, and payouts, adds episodes, blacks out ad slots, and submits airchecks. Nothing in the API purchases anything.

To use Gumball from an AI agent instead of your own code, see Connect an AI agent.

Create an API key

  1. Sign in to Gumball and open Account Settings.
  2. In the API Keys box, click Create API Key.
  3. Enter a name, choose an access level, and choose when the key expires.
  4. Accept the API terms if the form asks, then click Create API Key.
  5. Copy the key. Gumball shows it once.

A key acts as you. It reaches everything your account reaches, so store it like a password.

Make a first call

Send the key in the Authorization header:

curl https://api.gumball.fm/v1/me \
  -H "Authorization: Bearer gum_YOUR_KEY"

The response names the account the key acts as:

{
  "user": {
    "id": "user_5f8d0d55b54764421b7156c3",
    "name": "Sam Rivera",
    "email": "sam@example.com"
  },
  "role": "advertiser",
  "access_level": "read",
  "shows": [],
  "campaigns": [
    { "id": "camp_64f1c2a9b54764421b7156d0", "name": "Spring launch" }
  ]
}

role tells you which operations the account can use. An advertiser account uses the show search operations. A creator account uses the operations under /v1/me/shows.

Search shows as an advertiser

curl "https://api.gumball.fm/v1/shows?q=true+crime" \
  -H "Authorization: Bearer gum_YOUR_KEY"

To read a show's open ad slots for a range of air dates, pass the show's ID and the range:

curl "https://api.gumball.fm/v1/shows/show_5f8d0d55b54764421b7156c3/slots?start_date=2027-01-04&end_date=2027-01-31" \
  -H "Authorization: Bearer gum_YOUR_KEY"

List your shows as a creator

curl https://api.gumball.fm/v1/me/shows \
  -H "Authorization: Bearer gum_YOUR_KEY"

Next steps

Read this page as plain text.