spotify-ads-api

Spotify Ads Agentic Tools

A Codex, Claude Code, and Gemini CLI plugin package that lets you manage Spotify advertising campaigns through natural language. Create campaigns, target audiences, launch ads, and pull performance reports — all by describing what you want in plain English.

Check out our post on the Spotify Engineering Blog.

Prerequisites

• Codex, Claude Code CLI, or Gemini CLI
• A Spotify Developer account with an ads-enabled app
• A Spotify Ads ad account ID
• Python 3.8+ (for automated OAuth flow; optional — manual flow available as fallback)

Install

Claude Code

claude plugin i spotify-ads-api

Codex

Add the Spotify Ads API plugin marketplace:

codex plugin marketplace add spotify/ads-agentic-tools

Restart Codex after adding the marketplace. Then open the plugin directory in the Codex app, or run codex and enter /plugins in the CLI. Select the added marketplace and install/enable Spotify Ads API.

Use codex plugin marketplace upgrade later to refresh installed marketplace sources.

Gemini CLI

gemini extensions install https://github.com/spotify/ads-agentic-tools

Restart Gemini CLI, then verify with /extensions. On Gemini, skills activate automatically from natural language (or browse them with /skills list); run /configure for first-time setup instead of /spotify-ads-api:configure. Note: automatic OAuth token refresh uses the macOS Keychain, so auto-refresh is macOS-only.

Install from source

Use a source checkout for local development or testing unreleased changes.

1. Clone the repository:

   git clone https://github.com/spotify/ads-agentic-tools.git
   cd ads-agentic-tools
   

2. For Codex, register the checkout as a local marketplace:

   codex plugin marketplace add "$(pwd)"
   

   Restart Codex after adding the marketplace. Then open the plugin directory in the Codex app, or run codex and enter /plugins in the CLI. Select the local marketplace and install/enable Spotify Ads API.

3. For Claude Code, launch with the plugin directory:

   claude --plugin-dir "$(pwd)"
   

   The Claude --plugin-dir flag loads the plugin for that session only. You can also add it to a shell alias if you use it frequently:

   alias claude-ads='claude --plugin-dir /path/to/ads-agentic-tools'
   

4. For Gemini CLI, link the checkout as a local extension:

   gemini extensions link "$(pwd)"
   

   The link is a symlink, so source changes are picked up on the next Gemini CLI restart.

The repository includes platform-specific marketplace metadata: .agents/plugins/marketplace.json for Codex and .claude-plugin/marketplace.json for Claude Code. Gemini CLI has no marketplace file — it installs directly from the repository using the root gemini-extension.json manifest. Keep all three manifests in sync when changing plugin metadata.

Configure

1. Set up the redirect URI in Spotify Developer Dashboard:

   • Go to developer.spotify.com and open your app settings
   • Under Redirect URIs, add: http://127.0.0.1:8080/callback
   • Save the changes
   • Open https://adsmanager.spotify.com/api-terms and make sure the ad account you want to use is selected. Accept the terms to authorize your client id to access your ad account through Ads API.

2. Configure OAuth credentials:

   /spotify-ads-api:configure
   

   (On Gemini CLI, run /configure instead — the skill names below all apply, but the slash-command prefix is Claude Code/Codex syntax.) This opens your browser for Spotify authorization, then saves your tokens locally with automatic refresh.

3. Create your first campaign:

   /spotify-ads-api:build-campaign Create an audio campaign called Summer Promo targeting US listeners aged 25-44 with $100/day budget
   

Authentication

The plugin supports three authentication modes:

OAuth 2.0 (Recommended)

Run /spotify-ads-api:configure or /spotify-ads-api:configure oauth. This launches an automated OAuth flow using a local Python script. Your tokens are stored locally and refresh automatically before API calls.

Manual OAuth

Run /spotify-ads-api:configure manual if Python is not available. You'll manually open the authorization URL, copy the redirect, and the plugin exchanges the code for tokens via curl.

Direct Token (Legacy)

Run /spotify-ads-api:configure token <your-token>. Accepts a pre-obtained access token. No automatic refresh — token expires in ~1 hour.

Available Skills