Turning API Docs into Conversational Ads Management with Claude Code Plugins

Managing ad campaigns through APIs often requires developers to read through lengthy documentation and write custom code. Spotify Engineering turned this on its head by building a natural language interface that lets advertisers interact with the Spotify Ads API through plain English. By leveraging Claude Code Plugins, they transformed OpenAPI specs and Markdown files into a conversational tool — all without writing a single line of compiled code. Below, we dive into how this works and what it means for ad managers.

What is the natural language interface for the Spotify Ads API?

The natural language interface is a conversational tool that allows users to manage Spotify ad campaigns by speaking or typing in everyday language, rather than writing API calls. It sits on top of the existing Spotify Ads API, interpreting user requests like “Show me the performance of my last campaign” or “Increase the budget for my top ad set by 20%.” Behind the scenes, it translates these requests into structured API commands using knowledge of the API’s specification. This system was built entirely using Claude Code Plugins, which read the API’s OpenAPI Spec and accompanying Markdown documentation to understand the available endpoints, parameters, and expected responses. The result is an interface that feels like talking to a human expert.

Turning API Docs into Conversational Ads Management with Claude Code Plugins — Source: engineering.atspotify.com

How did the team build it without writing compiled code?

The key innovation was using Claude Code Plugins as the runtime environment. Instead of writing a traditional application in a compiled language like Java or Go, the team configured Claude — an AI assistant — to act as the interpreter between user intent and API actions. They fed it the OpenAPI specification (a machine-readable file describing all endpoints) and related Markdown guides. Claude uses its built-in code generation and reasoning capabilities to map natural language queries to API calls on the fly. No compiled executable was created; the entire interface runs as a dynamic, prompt-driven system within Claude’s plugin framework. This approach drastically reduced development time and made updates trivial — just update the spec and documentation files.

What role do Claude Code Plugins play in this solution?

Claude Code Plugins are the backbone of the entire system. They provide the environment where the AI can read external files (like OpenAPI YAML and Markdown), execute code snippets, and make HTTP requests to the Spotify Ads API. The plugin is configured with a set of tools that allow Claude to: (1) parse the API specification, (2) generate sample requests based on user intent, (3) call the live API with proper authentication, and (4) format the response back in natural language. Crucially, the plugin uses contextual understanding to handle multi-turn conversations — for example, remembering that a user previously asked about “last month” and then referencing that in a follow-up query. All of this happens without any pre-compiled logic; the plugin’s behavior is entirely driven by the documents it loads.

How does the system interpret OpenAPI specs and Markdown files?

When the natural language interface starts, Claude reads the OpenAPI specification file for the Spotify Ads API. This file contains structured definitions of every endpoint, including URL paths, HTTP methods, request parameters, authentication requirements, and response schemas. Simultaneously, it processes Markdown documentation that explains business logic, campaign rules, and best practices. Claude indexes all of this information into its working memory. When a user asks a question, Claude first identifies the relevant endpoint(s) by comparing keywords and intent against the spec. Then it uses the Markdown documentation to refine the request — for example, understanding that “boost a campaign” maps to the /campaigns/{id}/boost endpoint with specific budget limits. The interpretation is essentially a semantic match enhanced by the AI’s language understanding.

What are the main benefits for ad campaign managers?

Ad campaign managers benefit from a dramatic reduction in complexity. Instead of learning the API’s technical details or relying on a developer for every change, they can interact in plain language. Real-time adjustments become possible: pausing underperforming ads, reallocating budgets, or pulling performance reports take just seconds. The system also reduces human error — the AI validates requests against the spec before sending them. Additionally, because the interface uses the same underlying API, it inherits all the security and compliance measures of the Spotify Ads ecosystem. Managers can focus on strategy rather than syntax, and the conversational format makes training new team members faster. Finally, updates to the API are automatically reflected if the spec and docs are updated, keeping the interface current.

Can you give an example of a typical user interaction?

Certainly. A user might say: “Show me the top 5 ad sets by impressions this week.” The system first confirms the user’s authentication, then queries the API endpoint /ad-sets/report?metric=impressions&sort=desc&limit=5. It formats the response: “Here are your top 5 ad sets by impressions this week: 1. ‘Summer Sale’ – 12,450 impressions; 2. ‘New Album Drop’ – 9,230 impressions; …” The user can then say, “Increase the budget for ‘Summer Sale’ by 50%.” The system retrieves the ad set’s current budget from its memory, calculates the new amount, calls /ad-sets/{id}/update with the new budget, and replies, “Done! ‘Summer Sale’ budget increased from $100 to $150 per day.” All of this happens conversationally, with the AI maintaining context across exchanges.

What technical challenges were overcome?

One major challenge was handling ambiguity in natural language. For example, a user might say “last campaign” when they mean the most recently created campaign, but the API might interpret it as the campaign with the latest activity date. The system uses heuristics built into the Markdown docs to resolve such ambiguities. Another challenge was authentication — the API requires OAuth tokens that expire. The plugin was extended to support token refresh flows securely. Additionally, rate limiting needed careful management; the system queues requests and batches them when possible. Finally, ensuring that the AI’s generated API calls were syntactically correct required thorough testing of the OpenAPI spec parsing. The team solved this by adding validation steps within the plugin that mock-run the call against a sandbox environment first.

How does this approach compare to traditional API interfaces?

Traditional API interfaces require developers to write code, understand HTTP methods, and interpret error codes. This natural language interface replaces all of that with a conversational wrapper. The difference is similar to using a command-line shell versus a GUI — one is powerful but requires expertise, the other is intuitive but may have limitations. Here, you gain speed and accessibility: non-technical staff can make changes immediately. However, traditional interfaces provide more fine-grained control and can be scripted for automation. The natural language interface is ideal for quick decisions and ad-hoc queries, while programmatic access remains better for bulk operations. Spotify’s solution actually complements the existing API rather than replacing it — it’s an alternative access point that lowers the barrier to entry.

Tags: