Conversational Ads Management: How Claude Plugins Turn API Specs into Chat Tools

Introduction

Managing digital advertising campaigns often involves navigating complex APIs, parsing documentation, and writing code to automate tasks. But what if you could simply tell an AI what you need—“Show me this week’s ad performance for campaign X”—and have it fetch, interpret, and present the data instantly? Spotify Engineering recently demonstrated exactly this capability by building a natural language interface for the Spotify Ads API using Claude Code Plugins. The result is a conversational tool that requires no compiled code, relying instead on OpenAPI specifications and Markdown files to understand the API’s structure and documentation.

This article explores the concept behind the project, how it works, and why it represents a shift in how developers—and even non-developers—can interact with advertising platforms.

The Core Idea: From Specs to Conversational UI

Traditional integration with a REST API like Spotify Ads requires writing code to handle authentication, requests, responses, and error handling. With Claude Code Plugins, the heavy lifting is replaced by a natural language model that reads the API’s OpenAPI specification (a standard machine-readable description of endpoints, parameters, and data formats) along with human-written Markdown documentation (examples, best practices, contextual notes). The plugin interprets these files at runtime, allowing the user to interact with the API through plain English.

The key innovation is that no compilation or deployment of custom code is needed. The plugin dynamically understands the API’s capabilities and generates appropriate calls on the fly. This dramatically reduces the time from idea to working prototype.

How Claude Code Plugins Enable This

Claude, Anthropic’s AI assistant, supports a plugin system where external tools can be defined declaratively. A Claude Code Plugin typically consists of:

• Plugin Manifest: metadata describing the plugin’s purpose and configuration.
• API Specification: the OpenAPI (Swagger) file describing all endpoints of the target API.
• Documentation Files: Markdown files containing additional context, usage examples, notes on authentication, rate limits, and common pitfalls.
• Action Definitions: optional rules that map natural language intents to specific API calls.

When a user asks a question, Claude’s model examines the plugin’s specification and documentation, determines the appropriate endpoint and parameters, constructs the HTTP request, calls the API, and then interprets the response—all while maintaining a conversational flow.

Example Scenario

Imagine an advertiser asks: “Let me see the impressions and spend for my top 3 campaigns yesterday.” Without writing code, the plugin would:

1. Identify the relevant endpoint from the OpenAPI spec (e.g., GET /campaigns/{id}/stats).
2. Use Markdown docs to understand that “yesterday” means a date range, and “top 3 campaigns” requires sorting by a metric like impressions or spend.
3. Generate the API call with proper authentication headers (handled by the plugin’s configuration).
4. Parse the JSON response and format it back into a human-readable answer, perhaps a table or bulleted list.

This entire process happens in seconds, with the user never touching a code editor.

Benefits Over Traditional Development

Using a natural language interface built on Claude Code Plugins offers several advantages:

• Speed of Prototyping: A functional tool can be created as soon as the OpenAPI spec and documentation are ready—no compilation, no deployment pipeline.
• Accessibility for Non-Programmers: Marketers, product managers, and business analysts can query ad data or configure campaigns without writing a single line of code.
• Reduced Maintenance: When the API evolves, you only need to update the OpenAPI spec and docs; the plugin adapts automatically.
• Consistent Understanding: The AI model uses the same documentation that human developers rely on, reducing misinterpretation.

Architecture Insights

The system is built around two primary input files:

• OpenAPI Specification (YAML/JSON): Defines endpoints, methods, parameters, request bodies, and response schemas. Claude uses this to validate possible queries and construct valid requests.
• Markdown Documentation: Provides the contextual “glue”—for example, “the /adstats endpoint requires at least one metric filter, and date ranges must be in ISO 8601 format.” These files are written in simple Markdown, making them easy for technical writers to maintain.

No backend middleware is required. The plugin communicates directly with the Spotify Ads API (or any other RESTful service). Claude Code Plugins run within the Claude platform, which handles authentication state via stored tokens or OAuth flows defined in the manifest.

Challenges & Considerations

While powerful, this approach has limitations. The quality of the user experience heavily depends on the quality of the documentation. Vague or incomplete Markdown files can lead to incorrect interpretations. Additionally, complex workflows involving multiple sequential API calls may require explicit step-by-step guidance in the documentation. Finally, the model’s ability to handle nuanced business logic (e.g., budget caps, cross-campaign attribution) is still evolving.

Conclusion

Spotify’s demonstration of a natural language interface to the Ads API highlights a future where software tools are defined by specification files rather than compiled code. Claude Code Plugins lower the barrier to building conversational experiences, enabling teams to deliver powerful ad management capabilities in hours instead of weeks. For anyone looking to experiment, grabbing an OpenAPI spec and a few Markdown documents is the only prerequisite—no compiler required.

To explore further, see the original Spotify Engineering post and the core idea section of this article for more context.