# Use MusicAPI with an AI coding agent
URL: https://musicapi.com/docs/ai/ai-coding-agents.md

> Give Claude Code, Cursor, Codex or Copilot the MusicAPI docs as Markdown and a ready prompt with the rules agents get wrong.

Product: MusicAPI Core and MusicAPI Managed Transfers. Section: Guides for AI.

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](https://musicapi.com/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](https://musicapi.com/llms-full.txt) | Every page in one file.                                                                                                                 |
| [/openapi.json](https://musicapi.com/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](https://musicapi.com/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.

```markdown
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](https://musicapi.com/docs/ai/mcp-server.md) 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.