A Codex, Claude Code, and Antigravity 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.
- Codex, Claude Code CLI, or Antigravity 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)
claude plugin i spotify-ads-apiThe plugin is installed from the Official Anthropic marketplace, which has auto-update enabled by default. Claude Code checks for plugin updates in the background after each session starts and applies them automatically. New versions take effect on your next launch (or run /reload-plugins to pick them up in the current session).
If you have auto-update disabled for the Official Anthropic marketplace, you will need to update the plugin manually. See the Anthropic instructions on Discover and install plugins for instructions on managing marketplace updates.
Add the Spotify Ads API plugin marketplace:
codex plugin marketplace add spotify/ads-agentic-toolsRestart 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.
agy plugin install https://github.com/spotify/ads-agentic-toolsRestart Antigravity CLI, then verify with /plugins. On Antigravity, 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.
Use a source checkout for local development or testing unreleased changes.
-
Clone the repository:
git clone https://github.com/spotify/ads-agentic-tools.git cd ads-agentic-tools -
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
codexand enter/pluginsin the CLI. Select the local marketplace and install/enable Spotify Ads API. -
For Claude Code, launch with the plugin directory:
claude --plugin-dir "$(pwd)"The Claude
--plugin-dirflag 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'
-
For Antigravity CLI, link the checkout as a local plugin:
agy plugin link "$(pwd)"The link is a symlink, so source changes are picked up on the next Antigravity CLI restart.
The repository includes platform-specific marketplace metadata: .agents/plugins/marketplace.json for Codex and .claude-plugin/marketplace.json for Claude Code. Antigravity CLI has no marketplace file — it installs directly from the repository using the root plugin.json manifest. Keep all three manifests in sync when changing plugin metadata.
-
Create a Spotify Developer app:
- Go to developer.spotify.com and log in
- Click Create App
- Enter a name (e.g. "Ads Agentic Tools") and a simple description
- Under Redirect URIs, enter
http://127.0.0.1:8080/callbackand remember to click Add - Under Which API/SDKs are you planning to use?, check Ads API
- Save the app and note your Client ID and Client Secret
- 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.
-
Configure OAuth credentials:
/spotify-ads-api:configure(On Antigravity CLI, run
/configureinstead — 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. -
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
The plugin supports three authentication modes:
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.
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.
Run /spotify-ads-api:configure token <your-token>. Accepts a pre-obtained access token. No automatic refresh — token expires in ~1 hour.
Skill names below use Claude Code/Codex slash-command syntax. On Antigravity CLI, the same skills activate automatically from natural language (browse them with /skills list), and setup is /configure.
| Skill | Description |
|---|---|
/spotify-ads-api:configure |
Set up OAuth credentials, ad account, and preferences |
/spotify-ads-api:campaigns |
List or get campaigns; stage creates and updates through drafts by default |
/spotify-ads-api:ads |
List or get ad sets and ads; stage creates and updates through drafts by default |
/spotify-ads-api:campaign-strategy |
Plan API-ready campaign structure and targeting from a landing page, business brief, or creative assets |
/spotify-ads-api:build-campaign |
Create a full campaign hierarchy from a plain-text description |
/spotify-ads-api:report |
Pull aggregate metrics, audience insights, or async CSV reports |
/spotify-ads-api:assets |
Upload, list, and manage creative assets |
/spotify-ads-api:audiences |
Upload customer lists and manage custom, engagement, event, and lookalike audiences |
/spotify-ads-api:measurement-setup |
Design and configure Pixel, CAPI, datasets, event mapping, advanced matching, mobile apps, and sharing |
/spotify-ads-api:measurement-debug |
Diagnose missing, stale, duplicated, mismatched, or unattributed Pixel/CAPI events |
/spotify-ads-api:account-admin |
Discover businesses/ad accounts and manage members, roles, invitations, and account details |
/spotify-ads-api:dashboard |
Quick performance overview of active campaigns |
/spotify-ads-api:monitor |
Diagnose pacing, delivery, stalled campaigns, and underdelivery issues |
/spotify-ads-api:export |
Export campaign hierarchy, targeting, budget, and optional metrics to CSV |
/spotify-ads-api:bulk |
Stage batch pause, resume, budget, delivery, archive, creative, and tracking workflows through drafts |
/spotify-ads-api:clone |
Clone campaigns or ad sets as validated drafts with optional changes |
/spotify-ads-api:change-history |
View a timeline of changes — who changed what, when, and how |
Ask for an outcome in ordinary language; you do not need to know endpoint names or request schemas. For example:
- Plan and build: “Recommend a Spotify campaign plan for this product page and a $5,000 budget.” or “Build an audio campaign for US listeners ages 25–44 and keep it as a validated draft.”
- Operate at scale: “Pause every active ad set in my summer campaign.” or “Clone last quarter’s campaign for next month.”
- Measure performance: “How are my active campaigns doing?” or “Export my campaign hierarchy and last-30-day metrics to CSV.”
- Manage creative and audiences: “Upload this MP3 as an audio creative.” or “Upload this customer list and create a custom audience.”
- Set up and debug conversion tracking: “Design Pixel and CAPI purchase tracking with deduplication.” or “Why did CAPI purchases stop arriving yesterday?”
- Administer access: “Audit who can access my ad account and which roles they have.”
- Audit changes: “What changed in my ad account this week?” or “Who changed the Summer Sale campaign?”
Contributors and internal testers can use the fuller prompt catalog, which pairs a natural user example with a behavioral probe for every skill. The test scenarios cover exact routing, schema, safety, and recovery expectations.
Campaign, ad set, and ad creation or modification is staged through the draft workflow by default, including requests that do not use the word “draft.” The plugin validates staged changes and publishes only after a separate request and explicit confirmation. Ask for an immediate or direct live change only when you intentionally want to bypass draft staging and your account permits published-entity writes.
Settings are stored in .codex/spotify-ads-api.local.md on Codex, .claude/spotify-ads-api.local.md on Claude, and .agents/spotify-ads-api.local.md on Antigravity. Each platform falls back to the other settings files if its preferred file does not exist. All three paths are gitignored.
| Field | Description | Default |
|---|---|---|
access_token |
OAuth2 bearer token | — |
refresh_token |
Token for automatic renewal | — |
token_expires_at |
ISO 8601 expiry timestamp | — |
client_id |
Spotify app client ID | — |
ad_account_id |
Default ad account UUID | — |
auto_execute |
Skip confirmation prompts | false |
The client secret is stored in the macOS Keychain (not in the settings file) for security. It is saved during /spotify-ads-api:configure and retrieved automatically by the token refresh hook.
"Token may be invalid or expired"
If using OAuth, the plugin auto-refreshes tokens. If the refresh token is also expired, re-run /spotify-ads-api:configure. If using direct token mode, obtain a new token and run /spotify-ads-api:configure token <new-token>.
"Ad account ID may be incorrect" Verify your ad account UUID. You can find it in the Spotify Ads Manager or by asking the plugin to list accounts after configuring a valid token.
"Settings file not found"
Run /spotify-ads-api:configure to create the settings file.
"Min audience threshold was not met" Your targeting is too narrow for the selected ad format. Try broadening the age range, adding more platforms, or switching from VIDEO to AUDIO format.
"Asset stuck in PROCESSING"
Large files may take longer to transcode. Check status with /spotify-ads-api:assets get <id>. If status is REJECTED, the file may not meet format requirements.
Skill not activating on Antigravity CLI
Run /skills list to confirm the plugin's skills loaded, and /plugins to confirm the plugin is enabled. Restart Antigravity CLI after installing or linking.
Copyright 2026 Spotify, Inc.
Licensed under the Apache License, Version 2.0: https://www.apache.org/licenses/LICENSE-2.0
Please report sensitive security issues via Spotify's bug-bounty program (https://hackerone.com/spotify) rather than GitHub.