Get a collection
GET/v1/collections/{id}
Returns items and its C34 credit block. Collections use the same rules as the website. A sound board is a collection with kind board. Limits are counted per kind: free accounts can hold 1 collection and 1 sound board; Pro accounts can hold up to 1,000 of each and create up to 60 per hour. A collection holds at most 500 tracks. A lapsed Pro account can view everything but can edit only one collection and one sound board until it resubscribes. Adding a CC BY-NC track to a commercial collection, or marking a collection with CC BY-NC tracks commercial, returns nc_commercial. Collection PATCH requires the current revision. Item edits, reorder, and adds accept an optional revision guard; deletion requires explicit confirmation.
Needs an API key. Send it in the Authorization: Bearer header.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | Path | string |
Responses
200OK.object · Content: application/json
Name Type Description idrequiredstring The collection id. namerequiredstring Shortest: 1. Longest: 80 kindrequiredstring A sound board is a collection with kind board. One of: collection, board commercialrequiredboolean Whether the collection is for commercial use. It only changes the non-commercial warning and the CC BY-NC refusal. revisionrequiredinteger Starts at 1. Send it back on PATCH to change the collection. Minimum: 1 read_onlyrequiredboolean True when the account’s plan no longer lets it edit this collection. It can still be viewed and exported. createdrequiredstring When the collection was created. Format: date-time updatedrequiredstring When the collection was last changed. Format: date-time archived_atrequiredstring or null When the collection was archived, or null while it is active. Format: date-time descriptionrequiredstring or null One line of plain text, or null when unset. Longest: 200 credits_headingrequiredstring or null The heading of the credits block, or null for the default. Longest: 120 itemsrequiredarray of CollectionItem In collection order. Show all 13 fields
Name Type Description creditsrequiredCollectionCredits The ready-to-copy credit block (C34), built from the collection as it stands. 401The API key is missing, not valid, or revoked.Schema Error · Content: application/json
Error fields (8)
Name Type Description errorrequiredstring A short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error. messagerequiredstring What went wrong, in plain words. parameteroptionalstring On invalid_parameter and invalid_filter_for_kind, the invalid parameter or field. invalid_valuesoptionalarray of string Unknown controlled filter ids. discoveryoptionalstring The endpoint listing valid filter ids and labels. limitoptionalstring Only on rate_limited: which limit you hit. One of: minute, day, month retry_afteroptionalnumber Only on rate_limited: seconds to wait before retrying. reset_atoptionalstring Only on rate_limited: when that limit resets, as an ISO 8601 UTC time. 404The collection or item was not found or is not owned by this account.Schema Error · Content: application/json
Error fields (8)
Name Type Description errorrequiredstring A short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error. messagerequiredstring What went wrong, in plain words. parameteroptionalstring On invalid_parameter and invalid_filter_for_kind, the invalid parameter or field. invalid_valuesoptionalarray of string Unknown controlled filter ids. discoveryoptionalstring The endpoint listing valid filter ids and labels. limitoptionalstring Only on rate_limited: which limit you hit. One of: minute, day, month retry_afteroptionalnumber Only on rate_limited: seconds to wait before retrying. reset_atoptionalstring Only on rate_limited: when that limit resets, as an ISO 8601 UTC time. 429Over your plan's limit. Free accounts get 20 calls per minute and 300 calls per day. Pro accounts get 60 calls per minute and 20,000 calls per month (UTC). MCP and the API share one allowance per account. The Retry-After header gives the seconds to wait, up to 86,400, and the limit and reset_at fields in the body name the limit you hit and when it resets.Schema Error · Content: application/json
Error fields (8)
Name Type Description errorrequiredstring A short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error. messagerequiredstring What went wrong, in plain words. parameteroptionalstring On invalid_parameter and invalid_filter_for_kind, the invalid parameter or field. invalid_valuesoptionalarray of string Unknown controlled filter ids. discoveryoptionalstring The endpoint listing valid filter ids and labels. limitoptionalstring Only on rate_limited: which limit you hit. One of: minute, day, month retry_afteroptionalnumber Only on rate_limited: seconds to wait before retrying. reset_atoptionalstring Only on rate_limited: when that limit resets, as an ISO 8601 UTC time.
{
"id": "example",
"name": "example",
"kind": "collection",
"commercial": true,
"revision": 1,
"read_only": true,
"created": "example",
"updated": "example",
"archived_at": "example",
"description": "example",
"credits_heading": "example",
"items": [
{
"track": "example",
"note": "example",
"added_at": "example",
"added_by": "example",
"position": 0,
"unavailable": true,
"modifications": {
"chips": [],
"text": "example"
}
}
],
"credits": {
"heading": "example",
"sections": [
{
"id": "required",
"heading": "example",
"lines": []
}
],
"warnings": [
{
"code": "empty",
"text": "example",
"trackIds": [],
"url": "example",
"licenseId": "cc0"
}
],
"citations": [
"example"
],
"text": "example",
"markdown": "example",
"html": "example"
}
} Copy only. No request is sent from this page, so your key never goes into a web page. The samples read it from the UNCOMMON_EAR_API_KEY environment variable.