Building a Natural Language Interface for the Spotify Ads API with a Claude Code Plugin

Spotify wrapped the Spotify Ads API v3 in a Claude Code plugin, installed on Claude Code in macOS, creating a flow that handles both slash commands and conversational requests. When a user makes a request like Back to School Promo, the agent breaks it down into campaign, ad set, and ad steps, chaining together the necessary API calls. The plugin has been published on GitHub and on Anthropic's Claude Plugins marketplace.

In this process, the agent uses the geo-targeting search endpoint (/targets/geos) to convert requests like Connecticut into IDs, converts dollar budgets into micro-units, and validates whether targeting is broad enough using audience estimates. If a required input is missing, it asks the user again, and depending on the auto_execute setting, it either confirms before executing or executes immediately.

• Skills handle slash commands, and Agents handle natural language interpretation.
• Hooks handle OAuth token refresh and HTTP header injection at PreToolUse.
• Settings store account and environment preferences in a gitignored local file.
• The runtime runs on just curl, jq, and python3, with the actual implementation consisting of Markdown files, a single bash script, and two Python helpers.

The reason CLI-first + OpenAPI was chosen over MCP is that the API is too large. Exposing over 30 resource types and a nested targeting structure as static tools would incur significant context window costs, but showing curl commands as-is lets users copy, modify, and re-run requests. The original OpenAPI v3 spec, external-v3.yaml, is about 8,600 lines and is effectively the single source of truth.

In particular, OpenAPI Links were used to specify the campaign → ad set → ad flow and the path for passing id between responses. The runtime expressions $response.body#/id, $request.path.ad_account_id, and operationId tell the agent what values to include in the next call. The curated api-reference skill organizes the schemas and enums for frequently used endpoints, while the original spec fills in the gaps for less-used endpoints and error responses.

The plugin was released under Apache 2.0, ultimately adopting the philosophy that the OpenAPI spec is the source of truth while business logic lives in prose. Going forward, they plan to observe user flows, support idempotency keys, expand to Codex and Gemini CLI, and even explore generating creative images using GPT5.5 and Images 2.0.