How We Created a Conversational Ads Manager Using Spotify's API and Claude Code Plugins

Introduction

Managing digital advertising campaigns often involves navigating complex APIs, writing code, and interpreting technical documentation. At Spotify, our engineering team set out to simplify this process by building a natural language interface to the Spotify Ads API. The result? A conversational tool that allows advertisers to manage campaigns through simple dialogue, all powered by Claude Code plugins and without a single line of compiled code.

How We Created a Conversational Ads Manager Using Spotify's API and Claude Code Plugins — Source: engineering.atspotify.com

The Vision: Conversational Ads Management

We envisioned an interface where users could ask questions like "How is my Q4 campaign performing?" or "Pause my ad set targeting millennials" and receive instant, accurate responses. This required bridging the gap between human language and the structured endpoints of the Spotify Ads API.

Why a Natural Language Interface?

Traditional API clients require developers to write code, authenticate, and parse JSON responses. For marketing teams without deep technical expertise, this creates friction. A natural language interface removes that barrier, enabling faster campaign adjustments and more intuitive data access.

Building the Interface with Claude Code Plugins

Claude Code plugins offered the perfect foundation. These plugins allow custom capabilities to be added to Claude, the AI assistant from Anthropic, by defining actions and knowledge sources. We focused on two key inputs: the API specification and supporting documentation.

Leveraging OpenAPI Spec

The Spotify Ads API is described by an OpenAPI specification (formerly Swagger). This machine-readable file defines every endpoint, parameter, and response format. By feeding this spec directly into a Claude Code plugin, we enabled the AI to understand available operations—such as retrieving campaign metrics or updating budgets—without writing any wrapper code.

Incorporating Markdown Documentation

Beyond the raw API spec, our team also authored Markdown files that explained common use cases, rate limits, authentication flows, and best practices. Claude indexed these files as part of its knowledge base. When a user asks a question, the plugin retrieves the most relevant documentation snippets, ensuring responses are contextually accurate and compliant with API guidelines.

No Compiled Code Required

A standout aspect of this project is that we never wrote or compiled traditional code (e.g., Python or JavaScript) to create the API bindings. Instead, the plugin dynamically interprets the OpenAPI spec at runtime, mapping user intents to API calls. This approach dramatically reduces development and maintenance overhead.

Plugin Architecture

The core plugin has three components:

Intent Parser: Using Claude's natural language understanding, it extracts the user's goal (e.g., "show me last week's ad impressions") and identifies required parameters.
Action Executor: This component constructs the appropriate API request based on the parsed intent and the OpenAPI schema.
Response Formatter: The raw API response is transformed into a conversational reply, complete with summaries or tables when helpful.

How It Works in Practice

Consider a marketing manager who types: "Increase the daily budget of my 'Summer Sale' campaign by 15%."

The plugin identifies the campaign by name (using fuzzy matching against known campaigns).
It determines the action: a budget update via the PUT /campaigns/{id} endpoint.
It fetches the current budget, calculates the 15% increase, and sends the update.
Finally, it confirms: "Your 'Summer Sale' campaign budget has been raised from $500 to $575."

All of this happens in seconds, without the user ever seeing a curl command or JSON blob.

Benefits and Future Directions

This conversational interface has several advantages:

Accessibility: Teams without programming skills can manage ads effectively.
Speed: Routine tasks are completed faster than manually navigating the API.
Maintainability: Updating the plugin only requires refreshing the OpenAPI spec or documentation files—no recompilation.

Looking ahead, we plan to add multi-turn conversations (e.g., refining a search after initial results) and proactive notifications. We also hope to open-source the plugin framework as a reusable pattern for other APIs.

Conclusion

By combining OpenAPI specs, Markdown documentation, and Claude Code plugins, Spotify Engineering has demonstrated that a natural language interface to a powerful ads API is not only possible but also practical—and it requires zero compiled code. This approach paves the way for more intuitive interactions with complex systems, making data-driven advertising accessible to everyone.

Tags: