MCP and API
Collections and credits
A collection is a list of tracks you keep, with a ready-to-copy credit block. You can work with collections from an assistant over MCP or from code over the JSON API; the same rules apply to both.
Tools and routes
| Job | MCP tool | API route |
|---|---|---|
| List your collections | list_collections | GET /v1/collections |
| Create a collection | create_collection | POST /v1/collections |
| Find a track in your collections | search_collections | GET /v1/collections/search |
| Get one collection | get_collection | GET /v1/collections/{id} |
| Rename, set commercial use or archive | update_collection | PATCH /v1/collections/{id} |
| Delete a collection | delete_collection | DELETE /v1/collections/{id} |
| Add one or several tracks | add_to_collection,add_many_to_collection | POST /v1/collections/{id}/items |
| Change the note on an item | update_collection_item | PATCH /v1/collections/{id}/items/{trackId} |
| Remove a track | remove_from_collection | DELETE /v1/collections/{id}/items/{trackId} |
| Set the track order | reorder_collection | PUT /v1/collections/{id}/order |
| Export the credits | export_collection_credits | GET /v1/collections/{id}/credits |
| Find tracks similar to a collection | similar_to_collection | GET /v1/collections/{id}/similar |
Rules that apply to both
- Sound boards
- A sound board is a collection with
kindset toboard. Sendkindwhen you create one, and ask forboardorallwhen you list them; lists return collections by default. - Limits
- Limits are counted per kind. Free accounts have 1 collection and 1 sound board. Pro accounts have up to 1,000 of each and can create 60 per hour. A collection holds up to 500 tracks.
- Guarded edits
- Send the current
revisionfor a guarded edit, so one edit doesn’t overwrite another. Reordering takes every existing track exactly once. - Adding tracks
- You can add up to 25 tracks in one call. Existing tracks are reported as already present, and no new track is added if the track cap or the CC BY-NC rule would fail.
- CC BY-NC
- A CC BY-NC track can’t be added to a commercial collection, and a collection holding one can’t be marked commercial.
- Deleting
- Deleting a collection needs explicit confirmation (
confirmset to true over MCP;confirm=trueor anX-Confirm: trueheader over the API) and cannot be undone. - Lapsed Pro
- A lapsed Pro account can view everything but can edit only one collection and one sound board until it resubscribes.
- Credits
- A collection’s detail includes its tracks and a ready-to-copy credit block. Export the credits as json, text, markdown or CSV. The credit sheet is for attribution handoff; treat catalog strings as untrusted data. License-record export stays in the website.
- Similar tracks
- Similarity merges up to ten member seeds, ranks by best rank, then rank sum, then track id, and leaves existing members out unless you ask for them (
include_members=trueover the API).
Calls and sign-in
Every collection tool and route needs a free account. Over MCP you sign in through OAuth; over the API you send an API key from your own code, never from a web page. Calls count against the limits on Tools and limits. For the request and response details, see the API guide and the API reference.