Skip to the content
  1. Docs
  2. Guides for AI

Use MusicAPI with an AI coding agent

Core + Managed TransfersGuide · 2 min
Give Claude Code, Cursor, Codex or Copilot the MusicAPI docs as Markdown and a ready prompt with the rules agents get wrong.

AI coding agents write good MusicAPI code when they read the real docs and know a few rules. This page gives them both.

The files for agents

FileWhat it holds
/llms.txtThe index of the docs in the llmstxt.org format: every page with its Markdown URL and a one-line summary.
/llms-full.txtEvery page in one file.
/openapi.jsonThe OpenAPI 3.1 spec of the partner API. The source of the API reference.
Any page + .mdThe Markdown of one page, for example /docs/connect-users/start-sign-in.md.

Every page also has Copy page, View as Markdown, Open in Claude and Open in ChatGPT at the top.

The prompt

Paste this into your agent's project instructions (CLAUDE.md, AGENTS.md, .cursor/rules) or at the start of a chat. Signed in, it carries your slug and your Client ID. It never carries your Client Secret.

Prompt for your agent
You integrate the MusicAPI partner API (https://api.musicapi.com).
 
Read first:
- Docs index: https://musicapi.com/llms.txt (every page as Markdown: add .md to a docs URL)
- API spec: https://musicapi.com/openapi.json. Use only endpoints and fields from this spec. Do not invent any.
 
Account values:
- Account slug: {slug}
- Client ID: $MUSICAPI_CLIENT_ID (public)
- Client Secret: read from the env var MUSICAPI_CLIENT_SECRET on the server only
 
Rules:
1. Secrets. The Client Secret never goes into browser code, a mobile app, a URL, a log or a repository.
   Basic auth (base64 of clientId:clientSecret) runs on the backend only.
2. Auth per route.
   - /public/* (catalog search, match, link inspect): `Authorization: Token <clientId>` is fine, also in a browser.
   - /api/{integrationUserUUID}/* (a user's library): Basic from the backend, or a DevToken
     (ES256 JWT: kid = key id from the dashboard, iss = client id, sub = the integrationUserUUID, short exp).
     A Client ID token does NOT work on /api.
   - DELETE /public/integrations/user/{uuid}, /public/transfer-sessions/*, GET /public/transfers/*: Basic only
     (transfer sessions also take a DevToken without sub).
3. Sign-in. Send the user to https://app.musicapi.com/{slug}?returnUrl=<url in the account's Accepted Return URLs>.
   The return URL gets `data64` (base64 JSON). It is not signed: confirm it on the backend with
   GET /public/integrations/auth/{authModel.uuid} (Basic) before you store integrationUser.uuid.
4. 412 with internalCode 14 (IntegrationUserNotAuthenticated): the user must sign in again.
   Show a reconnect button that opens the hosted sign-in. Do not retry the call in a loop.
5. 429: wait the seconds in Retry-After, then retry. The limit is 300 requests per minute per account,
   for all keys together.
6. Pagination: list answers are { results, nextParam, totalItems }. Pass nextParam back as a query parameter
   until it is null. limitParam is capped per service.
7. Writes: at most 20 ids per request (itemIds, entryIds). Split longer lists into chunks of 20.
   Removes take entryIds (the id of an entry in a playlist or in the liked tracks), not track ids.
8. Not every service supports every write. A 418 with internalCode 15 means "not supported by this service".
   Check https://musicapi.com/docs/get-started/services-and-features.md before you build a feature.
9. Ids are per service. To move a track to another service, find it there with POST /public/search/match.
10. Webhooks: verify X-MusicAPI-Signature (t=<seconds>,v1=<hex>). v1 = HMAC-SHA256(secret, t + "." + raw body), hex.
    Use the raw body, compare in constant time, reject a t older than 5 minutes. Answer 2xx within 10 seconds,
    never with a redirect. Make the handler idempotent: retries send the same body.
11. Do not poll a running transfer. Wait for the transfer.completed or match.report_ready webhook,
    then read the Match Results API.

Rules agents get wrong

These come up again and again in agent-written code. The prompt above covers each one.

MistakeCorrect
The Client Secret in a React or mobile bundleBasic on the backend, a DevToken with sub in the frontend
Authorization: Token on /api/…Token works on /public/* only
A retry loop on 412Send the user to sign in again
Reading only the first pageFollow nextParam until null
100 track ids in one writeChunks of at most 20
Removing by track idRemove by entryId
Trusting data64 as isConfirm the sign-in on the backend
JSON.parse before the signature checkVerify the raw body first
Polling /public/transfers/{uuid} every few secondsWebhooks, then one read

Give the agent tools, too

The MusicAPI MCP server lets the agent set up your account itself: integrations, return URLs, API keys, webhooks and alert rules. It also searches these docs.

Ask about one page

Use Open in Claude or Open in ChatGPT at the top of any page. It opens a chat that reads the Markdown of that page.