10 Steps to Create a Conversational Ads Manager Using Claude Code and Spotify’s API

Managing Spotify ads can be complex, but a new approach lets you turn technical API specs into a smooth, chat-based experience—no compiled code needed. By combining OpenAPI specifications, Markdown documentation, and Claude Code plugins, you can build a natural language interface that simplifies campaign management. This guide covers the key steps and insights from Spotify Engineering’s innovative method, helping you understand how to create a conversational tool that speaks your language.

1. Understand the Core Concept

At its heart, this project transforms the Spotify Ads API—normally accessed through raw endpoints and JSON payloads—into a conversational interface. Instead of writing code to make API calls, you talk to a Claude-powered agent that interprets your requests. The agent uses OpenAPI specs to know what actions are possible and Markdown files for contextual help. The result: you can say “Show me last week’s ad performance” and get an instant answer without touching a line of code.

2. Start with the OpenAPI Specification

The foundation is the OpenAPI spec for the Spotify Ads API. This machine-readable file lists every available endpoint, request/response structure, and authentication method. Claude Code parses this spec to understand the API’s capabilities. As described above, this eliminates the need to hand‑code API calls—the plugin dynamically generates them based on your intent. Make sure your spec is accurate and includes examples for better interpretations.

3. Enrich with Markdown Documentation

OpenAPI specs are great for machines but lack human context. That’s where Markdown files come in. Spotify’s engineers bundled explanatory docs—like best practices, common pitfalls, and use cases—into the tool’s knowledge base. Claude Code reads these markdown documents to provide natural‑language guidance. For instance, if you ask about budget optimization, the plugin can reference a Markdown guide on bid strategies.

4. Leverage Claude Code Plugins

The secret sauce is Claude Code Plugins, which let you extend Claude’s capabilities. Instead of uploading specs every time, you package the OpenAPI spec and Markdown files into a plugin. Claude then loads this plugin when you start a conversation. The plugin acts as a bridge: it maps your spoken requests to API calls and formats responses into plain English. No compiled code is required—just configuration.

5. Embrace a Zero‑Code Workflow

A standout feature is that the entire interface is built without writing any compiled code. Traditional API integrations require programming languages, SDKs, and deployment pipelines. Here, you simply provide structured data (OpenAPI + Markdown) and let Claude do the heavy lifting. This dramatically lowers the barrier for marketers and analysts who aren’t developers, enabling them to quickly prototype custom ads management tools.

6. Focus on Conversational Commands

The user experience centers on natural language. Commands like “Create a new campaign for my podcast ad with a $500 daily budget” are parsed by Claude, which uses the plugin to call the POST /campaigns endpoint. The response is converted back to everyday language. To make this work well, design your Markdown docs with example phrases and edge cases. Markdown helps Claude understand context, like whether “performance” means impressions or clicks.

7. Handle Authentication Securely

Spotify Ads API requires OAuth tokens. In this setup, you pre‑configure authentication within the Claude plugin so that the user never sees raw tokens. The plugin stores credentials securely (e.g., as environment variables) and attaches them automatically to each API call. This keeps the conversational interface safe while still allowing full access to your ad accounts.

8. Test with Real‑World Scenarios

Once built, test the interface with typical tasks: viewing campaign stats, adjusting budgets, pausing ads, or generating reports. Use the OpenAPI spec to verify that each action matches the expected endpoint. Also test edge cases—like asking for a non‑existent report—to ensure Claude responds gracefully with help from Markdown docs. Iterate on your configuration to improve accuracy.

9. Iterate Based on User Feedback

Because the system relies on config files (OpenAPI and Markdown), updating it is simple. Add new endpoints by editing the OpenAPI spec. Improve conversational responses by refining your Markdown notes. This agility lets you adapt the tool as Spotify evolves its API or as your team discovers new needs. No recompilation means changes go live instantly.

10. Deploy and Scale the Interface

Finally, package your Claude plugin for deployment. You can share it with your organization via a private plugin repository. Multiple team members can use the same conversational interface simultaneously, each with their own authentication. Since the tool is stateless (Claude handles state), scaling is straightforward. Monitor usage and update the spec as needed—keeping the entire ad management workflow conversational and code‑free.

Conclusion

Building a natural language interface to the Spotify Ads API using Claude Code Plugins is a game‑changer for teams that want to manage ads without writing code. By leveraging OpenAPI specs for structure and Markdown for context, you create a robust, conversational tool that is easy to update. This approach, pioneered by Spotify Engineering, proves that complex API interactions can be simplified into everyday language. Try it yourself—you might never go back to raw API calls again.