Introduction
Managing advertising campaigns through APIs often requires deep technical knowledge of query parameters, authentication flows, and rate limits. Spotify Engineering recently tackled this challenge by creating a natural language interface for the Spotify Ads API. The result is a tool that lets marketers and campaign managers interact with the API conversationally, without writing a single line of compiled code. By combining OpenAPI specifications, Markdown documentation, and Claude Code Plugins, the team transformed a traditional REST API into an intuitive chat-like experience.
The Challenge of API Management
APIs are powerful but can be intimidating for non-technical users. The Spotify Ads API, which handles everything from ad campaign creation to performance analytics, is no exception. To manage ad placements, budgets, and targeting, users typically need to understand HTTP methods, endpoints, and JSON payloads. For busy marketing teams, this learning curve can slow down campaign optimizations and reduce agility.
The goal was to abstract away the technical complexity while preserving the full functionality of the API. Instead of building a custom web app with a graphical user interface (GUI), the engineering team explored a more flexible approach: a conversational interface powered by a large language model (LLM).
Leveraging OpenAPI and Markdown Specifications
The foundation of the solution lies in two widely used specification formats: OpenAPI and Markdown. OpenAPI provides a machine-readable definition of the API’s endpoints, request schemas, and response structures. Spotify’s OpenAPI spec covers hundreds of operations, from retrieving account details to scheduling ad flights.
Markdown files were used to document higher-level workflows, best practices, and example use cases. For instance, a Markdown guide might show how to create a targeted ad campaign step by step, including the necessary API calls and parameter values. Together, these two sources form a comprehensive knowledge base that the LLM can reference.
How Claude Code Plugins Enable Conversational Interaction
Claude Code Plugins allow developers to define custom tools and commands that the LLM can invoke. In this project, the team created a plugin that connects Claude to the Spotify Ads API via the OpenAPI spec. When a user asks a question like “Show me the performance of last week’s campaign,” Claude interprets the intent, maps it to the appropriate API endpoint, fills in required parameters, executes the call, and returns the results in natural language.
The Markdown guides serve as context for complex workflows. For example, if the user says “Set up a new campaign targeting podcast listeners in the EU,” Claude can follow the Markdown checklist to ensure all necessary steps are taken: define the campaign, set targeting, allocate budget, and launch. The plugin handles authentication tokens seamlessly, so the user doesn’t need to worry about OAuth flows.
Benefits of a No-Compiled-Code Approach
One of the most striking aspects of this project is that it requires no compiled code. Traditional API integrations often involve writing and building software in Java, Python, or Go. Here, the entire interface runs on configuration files (OpenAPI JSON and Markdown) and a plugin definition. This lowers the barrier for iteration: changes to the API spec or documentation can be reflected in the conversational interface instantly, without a deployment cycle.
Other benefits include:
- Reduced development time – What might take weeks to build as a GUI can be prototyped in days.
- Accessibility – Non-technical team members can query campaign data and make adjustments using everyday language.
- Transparency – The LLM can show the underlying API calls it plans to make, building trust and enabling manual override if needed.
- Scalability – As the Ads API evolves, the plugin can be updated by simply refreshing the OpenAPI spec.
Future Possibilities
This proof of concept opens up exciting possibilities for Spotify and other teams. In the future, similar interfaces could be built for internal tools, customer support systems, or partner integrations. The combination of OpenAPI spec and Claude Code Plugins demonstrates a general pattern for creating natural language interfaces to any REST API.
Spotify Engineering is already exploring additional use cases, such as integrating multiple APIs into a single dialogue, adding multi-turn context (remembering previous requests), and incorporating real-time data alerts. The ultimate vision is an AI assistant that manages advertising campaigns autonomously, with human oversight only when needed.
Conclusion
The project shows that building a conversational interface for a complex API doesn’t require months of software development. By combining OpenAPI specifications, Markdown documentation, and Claude Code Plugins, Spotify Engineering created a natural language tool that makes ad management faster and more inclusive. As AI continues to evolve, such no-compiled-code approaches may become the standard way to interact with APIs.