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

JobMCP toolAPI route
List your collectionslist_collectionsGET /v1/collections
Create a collectioncreate_collectionPOST /v1/collections
Find a track in your collectionssearch_collectionsGET /v1/collections/search
Get one collectionget_collectionGET /v1/collections/{id}
Rename, set commercial use or archiveupdate_collectionPATCH /v1/collections/{id}
Delete a collectiondelete_collectionDELETE /v1/collections/{id}
Add one or several tracksadd_to_collection,add_many_to_collectionPOST /v1/collections/{id}/items
Change the note on an itemupdate_collection_itemPATCH /v1/collections/{id}/items/{trackId}
Remove a trackremove_from_collectionDELETE /v1/collections/{id}/items/{trackId}
Set the track orderreorder_collectionPUT /v1/collections/{id}/order
Export the creditsexport_collection_creditsGET /v1/collections/{id}/credits
Find tracks similar to a collectionsimilar_to_collectionGET /v1/collections/{id}/similar

Rules that apply to both

Sound boards
A sound board is a collection with kind set to board. Send kind when you create one, and ask for board or all when 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 revision for 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 (confirm set to true over MCP; confirm=true or an X-Confirm: true header 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=true over 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.