- Docs
- Guides for AI
Use MusicAPI with an AI coding agent
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
| File | What it holds |
|---|---|
| /llms.txt | The index of the docs in the llmstxt.org format: every page with its Markdown URL and a one-line summary. |
| /llms-full.txt | Every page in one file. |
| /openapi.json | The OpenAPI 3.1 spec of the partner API. The source of the API reference. |
Any page + .md | The 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.
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.
| Mistake | Correct |
|---|---|
| The Client Secret in a React or mobile bundle | Basic on the backend, a DevToken with sub in the frontend |
Authorization: Token on /api/… | Token works on /public/* only |
A retry loop on 412 | Send the user to sign in again |
| Reading only the first page | Follow nextParam until null |
| 100 track ids in one write | Chunks of at most 20 |
| Removing by track id | Remove by entryId |
Trusting data64 as is | Confirm the sign-in on the backend |
JSON.parse before the signature check | Verify the raw body first |
Polling /public/transfers/{uuid} every few seconds | Webhooks, 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.