How to Build a Natural Language Ads Manager with Claude Code and Spotify's API
By
<h2>Introduction</h2>
<p>Imagine managing your Spotify ad campaigns by simply typing or speaking natural language commands like <em>"Show me last month's ad spend by campaign"</em> or <em>"Pause the Holiday Promo campaign"</em>. With Claude Code plugins and the Spotify Ads API, you can build a conversational interface that turns API specs and documentation into a live, interactive tool — no compiled code required. This guide walks you through the entire process, from gathering materials to testing your first natural language query.</p><figure style="margin:20px 0"><img src="https://images.ctfassets.net/p762jor363g1/7GnlGifTt2p6DEfhG0GerL/0439f4b0965d712e5f747af50826031b/spotify-ads-api-claude-plugin__2.1_.png" alt="How to Build a Natural Language Ads Manager with Claude Code and Spotify's API" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px">Source: engineering.atspotify.com</figcaption></figure>
<h2>What You Need</h2>
<ul>
<li><strong>Claude Code</strong> – installed and configured (see <a href="#step1">Step 1</a>)</li>
<li><strong>Spotify Ads API OpenAPI specification</strong> (typically a <code>.yaml</code> or <code>.json</code> file)</li>
<li><strong>Spotify Ads API documentation</strong> in Markdown format (at least the core endpoints, rate limits, and authentication guide)</li>
<li><strong>Spotify Ads Manager account</strong> with API credentials (client ID, client secret, token)</li>
<li><strong>Node.js 18+</strong> (optional, if you plan to test locally)</li>
<li><strong>A text editor or IDE</strong> (VS Code recommended)</li>
</ul>
<h2>Step-by-Step Guide</h2>
<h3 id="step1">Step 1: Install and Configure Claude Code</h3>
<p>If you haven't already, install Claude Code on your system. Follow the official installation instructions for your platform (macOS, Windows, or Linux). Once installed, run <code>claude login</code> to authenticate with your Anthropic account. Ensure you have a project directory ready where you'll store your API spec, Markdown docs, and plugin configuration files.</p>
<h3>Step 2: Gather Your Spotify Ads API Resources</h3>
<p>Obtain the latest OpenAPI specification for the Spotify Ads API. This is usually provided as a single <code>.yaml</code> file. Also collect any Markdown files that describe authentication flows, campaign management endpoints, reporting endpoints, and error handling. Place all files in a folder named <code>spotify-ads-docs/</code> inside your project directory.</p>
<h3>Step 3: Prepare the Documentation for Plugin Consumption</h3>
<p>Claude Code plugins work best when documentation is well-structured. If your Markdown files contain large blocks of text, consider splitting them into smaller, focused files (e.g., <code>auth.md</code>, <code>campaigns.md</code>, <code>reports.md</code>). For the OpenAPI spec, ensure it's valid and up-to-date. You can validate it using an online tool or a local CLI like <code>speccy</code>. Any missing endpoints or incorrect paths will break the conversational interface later.</p>
<h3>Step 4: Create the Plugin Configuration</h3>
<p>Inside your project directory, create a directory named <code>.claude/</code> and inside it create a file <code>plugins.yaml</code> (or <code>.json</code>). This file tells Claude Code which documents to use. A minimal configuration looks like:</p>
<pre><code>plugins:
- name: "Spotify Ads Manager"
description: "Manage ad campaigns, view reports, and control budgets via natural language."
sources:
- path: "spotify-ads-docs/openapi.yaml"
type: openapi
- path: "spotify-ads-docs/auth.md"
type: markdown
- path: "spotify-ads-docs/campaigns.md"
type: markdown
- path: "spotify-ads-docs/reports.md"
type: markdown
</code></pre>
<h3>Step 5: Define Intent Handlers and Examples</h3>
<p>To make the interface conversational, you need to map natural language intents to API calls. Within the same plugin configuration (or a separate file), add an <code>intents</code> section. For each intent (e.g., <code>get_campaign_spend</code>), provide a description, example user phrases, and the corresponding API endpoint and method. For instance:</p>
<pre><code>intents:
- name: "get_campaign_spend"
description: "Get total spend for a specific campaign over a date range."
examples:
- "How much did the Spotify Wrapped campaign spend last month?"
- "Show me spend for all campaigns in Q1 2025"
api_operation:
path: "/v1/campaigns/{campaignId}/statistics"
method: GET
parameters:
campaignId:
source: "campaign name mapping"
startDate:
source: "date range from query"
endDate:
source: "date range from query"
</code></pre>
<h3>Step 6: Add Authentication Flows</h3>
<p>Because the Spotify Ads API requires OAuth 2.0, your plugin must handle token acquisition. Add an <code>authentication</code> block to your plugin config. Specify the OAuth endpoint, scopes, and a link to your stored credentials. You can also define a helper function that refreshes tokens automatically. Claude Code plugins can execute local scripts, so you can use a small Node.js or Python script to manage the token lifecycle.</p><figure style="margin:20px 0"><img src="https://engineering.atspotify.com/_next/image?url=https%3A%2F%2Fimages.ctfassets.net%2Fp762jor363g1%2F6VpxcfIxMRS8Ft1PMlxUro%2F9b7b39abfccec844ebb8586ab5a5122f%2Fspotify-ads-api-claude-plugin__2.2__1.5x.png&amp;w=1920&amp;q=75" alt="How to Build a Natural Language Ads Manager with Claude Code and Spotify's API" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px">Source: engineering.atspotify.com</figcaption></figure>
<h3>Step 7: Load and Test the Plugin</h3>
<p>Run <code>claude plugin add .claude/plugins.yaml</code> (or the equivalent command for your setup) to register your plugin. Then start a chat session with Claude Code and try a few commands:</p>
<ul>
<li>"List my ad campaigns"</li>
<li>"Show me impressions for the last 7 days"</li>
<li>"Create a new campaign with a daily budget of $100"</li>
</ul>
<p>If the plugin doesn't understand a command, review your intent definitions and add more example phrases. Adjust the documentation sources if the context is missing.</p>
<h3>Step 8: Iterate and Extend</h3>
<p>After basic functionality works, extend the plugin with advanced capabilities:</p>
<ul>
<li>Add <strong>aggregated reporting</strong> intents (e.g., "Top 5 campaigns by ROI")</li>
<li>Include <strong>budget alerts</strong> via webhooks or scheduled queries</li>
<li>Support <strong>multi-language</strong> commands by adding intents in other languages</li>
<li>Incorporate <strong>error handling</strong> guides so the plugin can explain API errors in plain English</li>
</ul>
<h3>Step 9: Document Your Plugin</h3>
<p>Create a simple README or Markdown file that explains how to use the plugin. Include example conversations, prerequisite steps, and troubleshooting. This will be helpful for team members or if you share the plugin publicly.</p>
<h2>Tips for a Smooth Experience</h2>
<ul>
<li><strong>Keep your OpenAPI spec up-to-date</strong> – The Spotify Ads API evolves. Regularly fetch the latest spec to avoid broken endpoints.</li>
<li><strong>Use consistent naming</strong> – In your intents, match parameter names exactly as they appear in the spec. Mismatches cause failures.</li>
<li><strong>Test with real credentials</strong> – Use a test ad account first to avoid accidentally spending money.</li>
<li><strong>Leverage the 'dry run' feature</strong> – Claude Code often supports a dry-run mode; use it to preview API calls before executing them.</li>
<li><strong>Write clear example phrases</strong> – The more varied examples you provide, the better Claude will understand user intent.</li>
<li><strong>Separate sensitive data</strong> – Never hardcode API keys or tokens in the plugin configuration. Use environment variables or a secrets manager.</li>
</ul>
<p>With these steps, you can transform static API documentation into a natural language interface that feels like a conversation. The best part is that no compiled code is necessary — just a well-organized set of documents and a flexible plugin system. Happy building!</p>
Tags: