Conversational Ads Management: How Spotify Built a Natural Language Interface for the Ads API Using AI

Introduction

Managing digital advertising campaigns often involves navigating complex APIs, reading extensive documentation, and writing code to interact with platforms. Spotify Engineering recently tackled this challenge by creating a natural language interface for their Ads API, enabling users to manage ads through simple conversation. The project leveraged Claude Code Plugins and required no compiled code, relying instead on existing OpenAPI specifications and Markdown documentation.

The Challenge: Simplifying API Interactions

Spotify Ads API is a powerful tool for advertisers to manage campaigns, audiences, and creative assets. However, learning the API endpoints, parameters, and authentication can be time-consuming. The team wanted to lower the barrier to entry by allowing users to perform actions like “Create a new ad campaign targeting users in New York” or “Show me the performance of my last week’s campaign” without writing a single line of code.

Traditional approaches would require building a full-fledged UI or writing custom middleware. Instead, Spotify Engineering turned to large language models and the concept of AI plugins that can directly consume API specifications.

How Claude Code Plugins Enable the Solution

Claude Code Plugins allow developers to define tools that a language model can call autonomously. In this case, the plugin was fed two key files:

• OpenAPI specification – a standard machine-readable format describing all API endpoints, request/response formats, and authentication methods.
• Markdown documentation – human-readable guides explaining concepts like campaign structures, billing, and best practices.

By providing these files as context, the AI could understand the full capability of the Ads API and generate accurate API calls based on natural language prompts. No compiled code was needed; the plugin acted as an interpreter between the user and the API.

The Magic of No Compiled Code

One of the standout aspects of this project is that it required zero compilation. Typically, integrating an API involves writing client libraries, handling serialization, and managing dependencies. Here, the plugin reads the OpenAPI spec at runtime and dynamically constructs requests based on the AI's understanding.

This approach offers several advantages:

• Rapid iteration – changes to the API spec can be reflected instantly without redeploying code.
• Reduced development overhead – no need to maintain a separate codebase for the interface.
• Flexibility – the same plugin could theoretically work with any API, as long as an OpenAPI spec is provided.

The team emphasized that the entire solution is built on top of existing artifacts that Spotify already maintains, meaning no extra documentation effort was required.

A Day in the Life: Conversational Ad Management

Imagine a marketing manager who wants to pause all campaigns that are not performing well over the weekend. With this natural language interface, they can simply type: “Pause all active campaigns where CTR is below 1% and set them to resume on Monday.” The AI, guided by the plugin, translates this into a series of API calls: first to list campaigns, then to filter by performance, then to update their status and schedule.

The interface can also answer questions like “What targeting options are available for a US-based audio ad?” by referencing the documentation files. The result is a powerful, flexible tool that makes the Ads API accessible to non-developers while still giving developers a faster way to prototype.

Technical Details Behind the Plugin

The plugin was built using Claude Code Plugins, which follow a specific structure for defining tools. Each tool has a name, description, and an input schema. In this case, one tool was defined for interacting with the Ads API:

1. Tool name: spotify_ads_api
2. Description: A natural language interface to the Spotify Ads API. Provide the action you want to perform in plain English.
3. Input schema: A JSON object containing the user's request and any optional parameters.

The plugin leverages the OpenAPI spec and Markdown files as context that the model can reference. No additional code compiles the spec; instead, the model reads it as part of its system prompt and uses its reasoning ability to match user requests to API calls.

Spotify Engineering also emphasized authentication handled transparently through OAuth tokens, so the user doesn't need to manage credentials manually.

Results and Future Possibilities

The initial prototype demonstrated that natural language interfaces could effectively replace point-and-click dashboards for many routine tasks. The team noted that complex multi-step operations were handled gracefully, though some edge cases required explicit disambiguation.

Looking ahead, Spotify is exploring ways to extend this concept to other internal tools. They also see potential for third-party developers to create their own plugins that combine multiple APIs, making the entire ad ecosystem more interoperable.

Conclusion

By combining the power of Claude Code Plugins with existing API specifications, Spotify Engineering has created a conversational ads management tool that requires no compiled code. This approach not only speeds up development but also makes advanced advertising features accessible through plain language. It’s a compelling example of how AI can bridge the gap between technical APIs and everyday users.

Originally published on Spotify Engineering Blog. Republished with permission.