# 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](https://gumball.fm/developers/connect-an-agent). ## Create an API key 1. Sign in to Gumball and open [Account Settings](https://gumball.fm/user/settings#api-keys). 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](https://gumball.fm/developers/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: ```bash curl https://api.gumball.fm/v1/me \ -H "Authorization: Bearer gum_YOUR_KEY" ``` The response names the account the key acts as: ```json { "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 ```bash 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: ```bash 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 ```bash 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](https://gumball.fm/developers/reference). - For how keys work, see [Authentication](https://gumball.fm/developers/authentication). - For what an error means, see [Errors](https://gumball.fm/developers/errors). - For lists longer than one page, see [Pagination](https://gumball.fm/developers/pagination).