Conversational Ad Management: Building a Natural Language Interface for Spotify Ads with Claude Code Plugins

Managing digital ad campaigns often involves navigating complex APIs and documentation. But what if you could talk to your ad platform like a colleague? This guide explores how Spotify Engineering leveraged Claude Code Plugins to transform OpenAPI specifications and Markdown documentation into a fully conversational ads management interface — all without writing a single line of compiled code. Below, we answer key questions about this innovative approach to API interaction.

1. What is the Spotify Ads API and why would you want a natural language interface?

The Spotify Ads API enables advertisers to programmatically manage campaigns, audiences, creatives, and reporting. However, traditional API usage requires developers to parse lengthy documentation, handle authentication, and write code to structure requests. A natural language interface (NLI) abstracts these complexities, allowing users to issue commands like "Show me last week’s ad performance by campaign" or "Pause all active ads for region US" in plain English. This lowers the barrier for non-technical marketers and accelerates workflows for developers by removing the need to reference endpoints manually. The NLI acts as a conversational gateway, translating human language into the correct API calls and returning human-readable results.

Conversational Ad Management: Building a Natural Language Interface for Spotify Ads with Claude Code Plugins — Source: engineering.atspotify.com

2. How do Claude Code Plugins enable a conversational interface without compiled code?

Claude Code Plugins allow developers to define tools using familiar formats like OpenAPI specs and Markdown files. Instead of writing compiled code (e.g., C++, Java), you provide a plugin configuration that describes the API endpoints, parameters, and expected responses. The plugin reads the OpenAPI spec to understand the API structure, while Markdown files offer supplementary instructions or examples. When a user asks a question, Claude’s language model interprets the intent, selects the appropriate plugin tool, and constructs the API call on the fly. No traditional software compilation is needed — just descriptive documentation that Claude can parse. This approach drastically reduces development time and makes the interface adaptable to API changes by simply updating the spec.

3. What role do OpenAPI specifications and Markdown files play in this process?

OpenAPI specifications (formerly Swagger) provide a machine-readable definition of the API: endpoints, HTTP methods, request schemas, and response formats. Claude uses this as the primary blueprint to understand what actions are possible and what data each call requires. Markdown files complement the spec by offering human-readable context — use cases, best practices, or complex query patterns. For example, a Markdown file might explain how to retrieve audience demographics across multiple campaigns. Together, they form a complete knowledge base that Claude can reference to generate accurate API calls. This dual approach ensures both technical precision (via OpenAPI) and contextual richness (via Markdown) without writing backend code.

4. What are the key benefits of using a natural language interface for ad management?

The primary benefits include improved accessibility — marketers with no programming experience can run complex reports and adjust campaigns using everyday language. Increased efficiency — developers save time by not manually constructing API requests or referencing docs mid-workflow. The NLI also reduces error rates since Claude validates requests against the API spec before sending them. Additionally, because the interface is built from standard documentation (OpenAPI + Markdown), it scales quickly when new API features are added — simply update the spec and the NLI learns the new endpoints. Finally, conversational interaction allows for iterative refinement: users can ask follow-up questions like "now exclude weekends" without restarting a query.

5. How does the conversational tool handle API authentication and complex queries?

Authentication is typically handled through environment variables or secrets configured in the plugin setup. When a user initiates a session, Claude requests necessary credentials (e.g., API tokens) once and stores them securely. For complex queries — say, "compare CTR across campaigns that ran during the holiday season, filtered by budget over $10k" — Claude breaks the request into multiple steps. It first fetches campaign lists, then filters by budget and dates, finally calculates CTR from metric endpoints. Each step uses the OpenAPI spec to ensure correct parameters. The plugin can also combine data from different endpoints, such as joining campaign performance with audience data, by chaining API calls intelligently. This multi-step reasoning is handled conversationally, with Claude providing intermediate results or clarifications if needed.

6. Can this approach be applied to other APIs beyond Spotify Ads?

Absolutely. The methodology is API-agnostic — any RESTful API that provides an OpenAPI specification can be turned into a natural language interface using Claude Code Plugins. The same plugin configuration and Markdown documentation pattern works for cloud services (AWS, Google Cloud), SaaS platforms (Salesforce, Stripe), or internal company APIs. The key requirement is a well-structured OpenAPI spec and optionally some Markdown guidance for domain-specific nuances. Because no compiled code is required, integrating a new API can take hours instead of weeks. This makes the approach ideal for organizations that manage multiple APIs and want to offer a unified conversational interface to both technical and non-technical users.

7. What are the limitations or challenges of building such an interface?

While powerful, the approach has limitations. Ambiguity in user queries can lead to incorrect API calls, especially for nuanced business logic not fully captured in the spec. Rate limiting and latency may become issues if Claude makes many sequential API calls for complex requests. The interface depends on the quality of the OpenAPI spec — poorly documented endpoints will confuse the model. Additionally, security considerations like token scoping and data privacy must be carefully implemented in the plugin layer. Finally, while the NLI handles many tasks, it may struggle with multi-step workflows that require conditional logic or external data sources not covered in the spec. Continuous testing and updating of the Markdown guidance can mitigate some challenges.

8. How does this compare to traditional API wrappers or SDK approaches?

Traditional approaches involve writing code (e.g., Python SDK) that wraps API calls into functions. This requires developers to maintain the wrapper as the API evolves, and end-users must learn the SDK’s syntax. In contrast, the Claude Code Plugin method eliminates the need for a custom SDK — the API spec itself becomes the interface. Maintenance is simpler: update the OpenAPI spec and the conversational interface adapts automatically. However, for programmatic use in scripts or applications, an SDK still offers faster execution and deterministic behavior. The NLI excels in ad-hoc queries, onboarding new users, and rapid prototyping, while traditional SDKs remain better for production automation. Ideally, the two complement each other — the NLI for exploration and troubleshooting, the SDK for scheduled tasks.

Tags: