Spotify Ads Agentic Tools
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.
Prerequisites
- 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+ or
uv (required for the secure configuration helpers). On Windows, ensure python or py is in your PATH.
- Git for Windows (Windows only; provides Git Bash, which the token refresh hook requires)
- jq (recommended on Windows for richer hook output; the token refresh hook works without it but produces minimal JSON)
Install
Claude Code
claude plugin i spotify-ads-api
The 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).
To use this repository as a custom marketplace in the Claude UI, choose Add marketplace, enter spotify/ads-agentic-tools or https://github.com/spotify/ads-agentic-tools, and select Sync. Then install Spotify Ads API from that marketplace. The Claude marketplace intentionally uses the repository-relative plugin source "./"; Git-based marketplace installs clone the whole repository and resolve that path from the repository root.
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.
Codex
Add the Spotify Ads API plugin marketplace:
codex plugin marketplace add spotify/ads-agentic-tools
In the Codex app, you can instead choose Add marketplace and enter https://github.com/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.
Antigravity CLI
agy plugin install https://github.com/spotify/ads-agentic-tools
Restart 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.
Install from source
Use a source checkout for local development or testing unreleased changes.
-
Clone the repository (on Windows, disable autocrlf so the bash hooks stay LF-only):
git clone -c core.autocrlf=false 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 codex and enter /plugins in 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-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'
-
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. Their plugin sources intentionally differ: Codex uses the public Git repository URL for this repository-root plugin, while Claude uses the relative string "./" required by its marketplace schema. 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.
Configure
Team administrator: register the application
-
Create or select the team's 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/callback and remember to click Add
- Under Which API/SDKs are you planning to use?, check Ads API
- Save the app and note its Client ID
- 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.
-
Share the client ID with the team's plugin users. A client ID is public
application metadata; do not distribute an application secret. Keeping a
team-owned client ID preserves that team's client-level attribution, quotas,
and rate-limit isolation. The plugin has no global fallback client ID.
Individual user: authorize the plugin
-
Configure OAuth with the team's client ID:
/spotify-ads-api:configure
(On Antigravity 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 PKCE authorization, then saves your tokens locally with automatic refresh. The authorization URL is also printed so it can be copied if the browser does not open automatically.
-
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 two authentication modes:
OAuth 2.0 with PKCE (Recommended)
Run /spotify-ads-api:configure or /spotify-ads-api:configure oauth [client_id]. This launches Authorization Code with PKCE (S256) using Python 3 or uv. The verifier stays in memory, no application secret is requested, and tokens refresh automatically before API calls. The helper writes tokens directly to an atomically replaced mode-0600 settings file instead of printing them. If a managed workspace requires separate write approval, tokens remain in a private mode-0600 temporary file until a token-free finalization command succeeds. If automatic browser opening fails, copy the printed authorization URL while the callback listener remains active.
Direct Token (Legacy)
Run /spotify-ads-api:configure token. The helper securely prompts for a pre-obtained access token without placing it in chat or command arguments. There is no automatic refresh, so the token expires in about one hour.
Available Skills
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:media-plan-to-draft | Convert a spreadsheet, PDF, document, presentation, or third-party media plan into a reviewed and validated Spotify Ads draft |
/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 |
Natural Language Examples
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.
Configuration Reference
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 | — |
auth_flow | authorization_code_pkce or direct_token | — |
ad_account_id | Default ad account UUID | — |
auto_execute | Skip confirmation prompts | false |
Existing OAuth settings created before PKCE can keep using an unexpired access token, but cannot refresh. Run /spotify-ads-api:configure once to reauthorize. On macOS, the old spotify-ads-api-client-secret Keychain item is then unused and may be removed; the plugin does not delete it automatically.
Codex resolves the installed token-refresh hook through its plugin manifest's
${PLUGIN_ROOT} substitution, so the hook does not depend on the workspace
directory or an exported CODEX_PLUGIN_ROOT variable.
Troubleshooting
"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, then enter it at the secure terminal prompt.
"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.
"Python was not found" on Windows
The python3 command on stock Windows 11 is a Microsoft Store redirect stub, not real Python. It exits with code 49 and prints a Store install prompt. Install Python from python.org or via winget install Python.Python.3.13, then use python or py (the plugin detects and skips the Store stub automatically).
Token refresh hook not running on Windows
The hook (hooks/check-token.sh) is a bash script. On Windows it requires Git Bash, which is included with Git for Windows. If the hook silently does nothing, ensure bash.exe is discoverable in your PATH (it should be after installing Git for Windows).
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.
License
Copyright 2026 Spotify, Inc.
Licensed under the Apache License, Version 2.0: https://www.apache.org/licenses/LICENSE-2.0
Security Issues?
Please report sensitive security issues via Spotify's bug-bounty program (https://hackerone.com/spotify) rather than GitHub.
