From spotify-ads-api
Provides the Spotify Ads API v3 reference: endpoints for campaigns, ad sets, ads, assets, audiences, and reports. Useful for managing Spotify ad accounts, creating campaigns, uploading assets, targeting audiences, and pulling reports.
How this skill is triggered — by the user, by Claude, or both
Slash command
/spotify-ads-api:api-referenceThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
The Spotify Ads API v3 enables programmatic management of advertising campaigns on Spotify. It follows a strict resource hierarchy and uses OAuth 2.0 bearer token authentication.
The Spotify Ads API v3 enables programmatic management of advertising campaigns on Spotify. It follows a strict resource hierarchy and uses OAuth 2.0 bearer token authentication.
https://api-partner.spotify.com/ads/v3
All requests require a Bearer token and the SDK tracking header:
Authorization: Bearer <access_token>
X-Spotify-Ads-Sdk: <sdk-product>/<version>
Use the active platform SDK product and plugin version:
.codex-plugin/plugin.json, set SDK_PRODUCT="codex-plugin"..claude-plugin/plugin.json, set SDK_PRODUCT="claude-code-plugin".gemini-extension.json (extension root), set SDK_PRODUCT="gemini-cli-extension".Set SDK_HEADER="X-Spotify-Ads-Sdk: $SDK_PRODUCT/$PLUGIN_VERSION" and include -H "$SDK_HEADER" on all API requests.
To set up authentication, run the configure skill (/spotify-ads-api:configure on Claude/Codex, /configure on Gemini), which supports OAuth 2.0 with automatic token refresh, manual OAuth, or direct token input.
Business
└── Ad Account
├── Campaign
│ └── Ad Set
│ └── Ad (references Assets)
├── Audience
├── Asset
└── Reports
Every CRUD operation on campaigns, ad sets, ads, assets, and audiences is scoped under an ad account ID.
50000000 micro-amount.2025-09-23T04:56:07Z).ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a).limit (1-50, default 50) and offset (default 0).sort_direction (ASC/DESC) and entity-specific sort fields.POST /ad_accounts/{id}/campaigns — Create campaign (required: name, objective)GET /ad_accounts/{id}/campaigns — List campaigns (filterable by status, name, IDs)GET /ad_accounts/{id}/campaigns/{campaign_id} — Get campaign by IDPATCH /ad_accounts/{id}/campaigns/{campaign_id} — Update campaign (name, status)POST /ad_accounts/{id}/ad_sets — Create ad set (required: name, start_time, budget, asset_format, targets, bid_strategy)GET /ad_accounts/{id}/ad_sets/{ad_set_id} — Get ad set by IDPATCH /ad_accounts/{id}/ad_sets/{ad_set_id} — Update ad setPOST /ad_accounts/{id}/ads — Create ad (required: name, assets; also needs tagline, advertiser_name, ad_set_id, call_to_action)GET /ad_accounts/{id}/ads — List ads (filterable by ad_set_ids, campaign_ids, statuses)GET /ad_accounts/{id}/ads/{ad_id} — Get ad by IDPATCH /ad_accounts/{id}/ads/{ad_id} — Update adPOST /ad_accounts/{id}/assets — Create asset (image, audio, or video)GET /ad_accounts/{id}/assets — List assetsGET /ad_accounts/{id}/assets/{asset_id} — Get asset by IDPATCH /ad_accounts/{id}/assets/{asset_id} — Update assetPATCH /ad_accounts/{id}/assets — Bulk archive/unarchivePOST /ad_accounts/{id}/audiences — Create audience (CUSTOM or LOOKALIKE)GET /ad_accounts/{id}/audiences — List audiencesDELETE /ad_accounts/{id}/audiences/{audience_id} — Delete audienceGET /ad_accounts/{id}/aggregate_reports — Aggregated metrics by entityGET /ad_accounts/{id}/insight_reports — Audience insight breakdownsPOST /ad_accounts/{id}/async_reports — Create async CSV reportGET /ad_accounts/{id}/async_reports/{report_id} — Check async report statusGET/PATCH /ad_accounts/{id} — Get/update ad accountPOST/GET /businesses — Create/list businessesGET /businesses/{id} — Get business by IDGET /targets/artists — Search artist targetsGET /ad_categories — List ad categoriesPOST /estimates/audience — Estimate audience size for targeting parameters (recommended before creating ad sets to validate reach)POST /estimates/bid — Get bid recommendationsRead the user's plugin settings from the active platform settings file created by the configure skill:
.codex/spotify-ads-api.local.md, then fall back to .claude/spotify-ads-api.local.md, then .gemini/spotify-ads-api.local.md..claude/spotify-ads-api.local.md, then fall back to .codex/spotify-ads-api.local.md, then .gemini/spotify-ads-api.local.md..gemini/spotify-ads-api.local.md, then fall back to .claude/spotify-ads-api.local.md, then .codex/spotify-ads-api.local.md.Use the settings file to get:
access_token — Bearer token for authenticationad_account_id — Default ad account IDauto_execute — Whether to execute API calls automatically or present them first (default: false)If the settings file does not exist, instruct the user to run the configure skill first (/spotify-ads-api:configure on Claude/Codex, /configure on Gemini).
Construct curl commands using the appropriate base URL. Example:
curl -s -w "\nHTTP_STATUS:%{http_code}" -X GET \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "$SDK_HEADER" \
"https://api-partner.spotify.com/ads/v3/ad_accounts/$AD_ACCOUNT_ID/campaigns?limit=50"
For error response format and common HTTP status codes, see references/endpoints.md (Error Responses section).
For detailed request/response schemas and field definitions, consult:
references/endpoints.md — Complete endpoint details with all parameters and response schemasreferences/schemas.md — Request/response body schemas with field types, constraints, and required fieldsreferences/enums.md — All enum values for status fields, asset formats, targeting options, report dimensions/metricsWorking examples with complete curl commands and expected responses:
examples/full-campaign-flow.md — End-to-end: create campaign, ad set, and ad with targetingexamples/aggregate-report.md — Pull aggregate metrics and create async CSV reportsnpx claudepluginhub spotify/ads-agentic-tools --plugin spotify-ads-apiManages Spotify Ads API ad sets and ads — list, create, get, or update. Useful for programmatic ad campaign management via curl.
Manages Google Ads, Meta Ads (Facebook/Instagram), LinkedIn Ads, TikTok Ads campaigns via natural language. Automates keyword research, budget optimization, ROAS tracking, wasted spend analysis, ad creatives, targeting, and reporting.
Audits and optimizes paid ad campaigns across Meta, Google, and TikTok with guided onboarding, scoring, and AI creative generation.