Managing advertising campaigns often requires navigating complex APIs and documentation. At Spotify, we wanted to simplify this process by creating a natural language interface that lets advertisers interact with the Spotify Ads API conversationally. Using Claude Code Plugins, we transformed OpenAPI specifications and Markdown files into a fully functional ads management tool—without writing any compiled code. This approach not only accelerated development but also made the system accessible to non-technical stakeholders. Below, we answer common questions about how this solution works and why it matters.

What exactly is a natural language interface for an API?

A natural language interface allows you to interact with an API using everyday language instead of writing code or manually constructing HTTP requests. In this project, we built a system where users can type commands like “Show me my ad performance for last week” or “Create a new campaign with a budget of $500.” Behind the scenes, Claude Code Plugins interpret the intent, validate the query against the API spec, and execute the appropriate API call. This lowers the barrier to entry for marketers and product managers who may not be familiar with API syntax.

Why did Spotify choose Claude Code Plugins for this project?

Claude Code Plugins excel at understanding structured data like OpenAPI specs and Markdown documentation. They can parse these files into actionable knowledge without requiring manual configuration. This made it possible to feed the Spotify Ads API’s OpenAPI spec and our internal Markdown guides directly into the plugin, which then learned how to map natural language requests to API endpoints. No additional model training or compiled code was needed—just clear documentation. This saved weeks of development time and ensured the plugin stayed up-to-date with any API changes simply by updating the input files.

What role did the OpenAPI spec play in building the interface?

The OpenAPI specification served as the backbone of the natural language interface. It describes every endpoint, parameter, and response in a machine-readable format. Claude Code Plugins use this spec to understand the full capabilities of the Spotify Ads API—what actions are possible, what data fields exist, and how they relate to each other. When a user asks a question, the plugin cross-references the natural language with the spec to generate the correct API call. This eliminates the need for manual mapping and ensures that the conversational interface always aligns with the actual API contract.

How were Markdown files integrated into the conversational flow?

In addition to the OpenAPI spec, we had extensive internal documentation in Markdown files—FAQs, best practices, and step-by-step guides for common tasks. Claude Code Plugins ingested these files and used them to provide context-aware responses. For example, if a user asks “How do I target a specific country?” the plugin reads the relevant Markdown section and returns concise instructions along with the API call. This hybrid approach means the interface isn’t just executing commands; it can also offer guidance, troubleshooting tips, and explanations, making it a true conversational companion for advertisers.

Can this interface handle complex multi-step workflows?

Yes. One of the key advantages of using Claude Code Plugins is their ability to maintain context across a conversation. Users can build a campaign step by step, ask for changes, and get feedback—all without restarting. For instance, you might say “Set my daily budget to $200 for the brand awareness campaign targeting New York” and then follow up with “Show me the projected reach.” The plugin remembers the campaign context, fetches the right data, and displays results naturally. Complex workflows, like scheduling across multiple time zones or adjusting bids by device type, are also supported through chained API calls.

What benefits does this approach offer over traditional API tools?

Traditional API tools require users to learn endpoints, authentication, and request formatting. Our conversational interface eliminates that learning curve. Non-technical team members can manage ads directly, reducing dependency on developers. Speed also improves—queries that might take several minutes to construct and debug can be answered in seconds. Additionally, because the system is built entirely from documentation files, updates are straightforward: change the OpenAPI spec or Markdown, and the interface adapts immediately. This agility is especially valuable in a fast-paced advertising environment where campaign requirements evolve daily.

What challenges did the team face during development?

One challenge was ensuring the plugin correctly interpreted ambiguous natural language. For example, “show performance” could mean different metrics depending on context. We addressed this by enriching the Markdown files with example queries and clarifying ambiguous terms. Another challenge was handling authentication securely within the conversational flow. We implemented token-based authentication that the plugin manages transparently, so users never need to handle credentials manually. Finally, we had to tune the plugin to respect API rate limits and error handling—translating API error codes into friendly, actionable messages for the user.

How can other teams apply this technique to their own APIs?

Any team with an OpenAPI specification and clear documentation can replicate this approach. Start by gathering your API spec and any Markdown guides you have. Feed them into a Claude Code Plugin (or similar tool) and define the scope of interactions. Test with a small set of common tasks, then expand. The key is to write documentation that covers edge cases and typical workflows—the plugin will handle the rest. No compiled code rewriting is needed, which means updates stay in sync with your API docs automatically. This method is especially useful for teams who want to democratize API access without building a custom frontend.