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
- Sign in to Gumball and open Account Settings.
- In the API Keys box, click Create API Key.
- Enter a name, choose an access level, and choose when the key expires.
- Accept the API terms if the form asks, then click Create API Key.
- 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
- For every operation and field, see the API reference.
- For how keys work, see Authentication.
- For what an error means, see Errors.
- For lists longer than one page, see Pagination.
Read this page as plain text.