API reference / Collections

Add one or several tracks to a collection

POST/v1/collections/{id}/items

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.

Get a key

Parameters

NameInTypeDescription
id requiredPathstring

Request body required

Content type: application/json

Responses

  • 200 Already present; no new rows added.

    object · Content: application/json

    NameTypeDescription
    id requiredstringThe collection id.
    name requiredstring Shortest: 1. Longest: 80
    kind requiredstringA sound board is a collection with kind board. One of: collection, board
    commercial requiredbooleanWhether the collection is for commercial use. It only changes the non-commercial warning and the CC BY-NC refusal.
    revision requiredintegerStarts at 1. Send it back on PATCH to change the collection. Minimum: 1
    read_only requiredbooleanTrue when the account’s plan no longer lets it edit this collection. It can still be viewed and exported.
    created requiredstringWhen the collection was created. Format: date-time
    updated requiredstringWhen the collection was last changed. Format: date-time
    archived_at requiredstring or nullWhen the collection was archived, or null while it is active. Format: date-time
    description requiredstring or nullOne line of plain text, or null when unset. Longest: 200
    credits_heading requiredstring or nullThe heading of the credits block, or null for the default. Longest: 120
    items requiredarray of CollectionItemIn collection order.
    Show all 15 fields
    NameTypeDescription
    results optionalarray of objectPresent on a bulk add (the tracks array) only: one entry per requested id, in request order. A single-track add omits it.
    track requiredstring Shortest: 1. Longest: 200
    already_present requiredboolean
  • 201 Added. Bulk results report each requested track.

    object · Content: application/json

    NameTypeDescription
    id requiredstringThe collection id.
    name requiredstring Shortest: 1. Longest: 80
    kind requiredstringA sound board is a collection with kind board. One of: collection, board
    commercial requiredbooleanWhether the collection is for commercial use. It only changes the non-commercial warning and the CC BY-NC refusal.
    revision requiredintegerStarts at 1. Send it back on PATCH to change the collection. Minimum: 1
    read_only requiredbooleanTrue when the account’s plan no longer lets it edit this collection. It can still be viewed and exported.
    created requiredstringWhen the collection was created. Format: date-time
    updated requiredstringWhen the collection was last changed. Format: date-time
    archived_at requiredstring or nullWhen the collection was archived, or null while it is active. Format: date-time
    description requiredstring or nullOne line of plain text, or null when unset. Longest: 200
    credits_heading requiredstring or nullThe heading of the credits block, or null for the default. Longest: 120
    items requiredarray of CollectionItemIn collection order.
    Show all 15 fields
    NameTypeDescription
    results optionalarray of objectPresent on a bulk add (the tracks array) only: one entry per requested id, in request order. A single-track add omits it.
    track requiredstring Shortest: 1. Longest: 200
    already_present requiredboolean
  • 400 The collection request is not valid.

    Schema Error · Content: application/json

    Error fields (8)
    NameTypeDescription
    error requiredstringA short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error.
    message requiredstringWhat went wrong, in plain words.
    parameter optionalstringOn invalid_parameter and invalid_filter_for_kind, the invalid parameter or field.
    invalid_values optionalarray of stringUnknown controlled filter ids.
    discovery optionalstringThe endpoint listing valid filter ids and labels.
    limit optionalstringOnly on rate_limited: which limit you hit. One of: minute, day, month
    retry_after optionalnumberOnly on rate_limited: seconds to wait before retrying.
    reset_at optionalstringOnly on rate_limited: when that limit resets, as an ISO 8601 UTC time.
  • 401 The API key is missing, not valid, or revoked.

    Schema Error · Content: application/json

    Error fields (8)
    NameTypeDescription
    error requiredstringA short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error.
    message requiredstringWhat went wrong, in plain words.
    parameter optionalstringOn invalid_parameter and invalid_filter_for_kind, the invalid parameter or field.
    invalid_values optionalarray of stringUnknown controlled filter ids.
    discovery optionalstringThe endpoint listing valid filter ids and labels.
    limit optionalstringOnly on rate_limited: which limit you hit. One of: minute, day, month
    retry_after optionalnumberOnly on rate_limited: seconds to wait before retrying.
    reset_at optionalstringOnly on rate_limited: when that limit resets, as an ISO 8601 UTC time.
  • 403 The collection is currently read-only.

    Schema Error · Content: application/json

    Error fields (8)
    NameTypeDescription
    error requiredstringA short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error.
    message requiredstringWhat went wrong, in plain words.
    parameter optionalstringOn invalid_parameter and invalid_filter_for_kind, the invalid parameter or field.
    invalid_values optionalarray of stringUnknown controlled filter ids.
    discovery optionalstringThe endpoint listing valid filter ids and labels.
    limit optionalstringOnly on rate_limited: which limit you hit. One of: minute, day, month
    retry_after optionalnumberOnly on rate_limited: seconds to wait before retrying.
    reset_at optionalstringOnly on rate_limited: when that limit resets, as an ISO 8601 UTC time.
  • 404 The collection or item was not found or is not owned by this account.

    Schema Error · Content: application/json

    Error fields (8)
    NameTypeDescription
    error requiredstringA short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error.
    message requiredstringWhat went wrong, in plain words.
    parameter optionalstringOn invalid_parameter and invalid_filter_for_kind, the invalid parameter or field.
    invalid_values optionalarray of stringUnknown controlled filter ids.
    discovery optionalstringThe endpoint listing valid filter ids and labels.
    limit optionalstringOnly on rate_limited: which limit you hit. One of: minute, day, month
    retry_after optionalnumberOnly on rate_limited: seconds to wait before retrying.
    reset_at optionalstringOnly on rate_limited: when that limit resets, as an ISO 8601 UTC time.
  • 409 A collection limit or revision conflict prevented the write.

    Schema Error · Content: application/json

    Error fields (8)
    NameTypeDescription
    error requiredstringA short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error.
    message requiredstringWhat went wrong, in plain words.
    parameter optionalstringOn invalid_parameter and invalid_filter_for_kind, the invalid parameter or field.
    invalid_values optionalarray of stringUnknown controlled filter ids.
    discovery optionalstringThe endpoint listing valid filter ids and labels.
    limit optionalstringOnly on rate_limited: which limit you hit. One of: minute, day, month
    retry_after optionalnumberOnly on rate_limited: seconds to wait before retrying.
    reset_at optionalstringOnly on rate_limited: when that limit resets, as an ISO 8601 UTC time.
  • 413 The JSON body exceeds 64 KB.

    Schema Error · Content: application/json

    Error fields (8)
    NameTypeDescription
    error requiredstringA short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error.
    message requiredstringWhat went wrong, in plain words.
    parameter optionalstringOn invalid_parameter and invalid_filter_for_kind, the invalid parameter or field.
    invalid_values optionalarray of stringUnknown controlled filter ids.
    discovery optionalstringThe endpoint listing valid filter ids and labels.
    limit optionalstringOnly on rate_limited: which limit you hit. One of: minute, day, month
    retry_after optionalnumberOnly on rate_limited: seconds to wait before retrying.
    reset_at optionalstringOnly on rate_limited: when that limit resets, as an ISO 8601 UTC time.
  • 422 The commercial setting conflicts with a non-commercial license.

    Schema Error · Content: application/json

    Error fields (8)
    NameTypeDescription
    error requiredstringA short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error.
    message requiredstringWhat went wrong, in plain words.
    parameter optionalstringOn invalid_parameter and invalid_filter_for_kind, the invalid parameter or field.
    invalid_values optionalarray of stringUnknown controlled filter ids.
    discovery optionalstringThe endpoint listing valid filter ids and labels.
    limit optionalstringOnly on rate_limited: which limit you hit. One of: minute, day, month
    retry_after optionalnumberOnly on rate_limited: seconds to wait before retrying.
    reset_at optionalstringOnly on rate_limited: when that limit resets, as an ISO 8601 UTC time.
  • 429 Over 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)
    NameTypeDescription
    error requiredstringA short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error.
    message requiredstringWhat went wrong, in plain words.
    parameter optionalstringOn invalid_parameter and invalid_filter_for_kind, the invalid parameter or field.
    invalid_values optionalarray of stringUnknown controlled filter ids.
    discovery optionalstringThe endpoint listing valid filter ids and labels.
    limit optionalstringOnly on rate_limited: which limit you hit. One of: minute, day, month
    retry_after optionalnumberOnly on rate_limited: seconds to wait before retrying.
    reset_at optionalstringOnly on rate_limited: when that limit resets, as an ISO 8601 UTC time.
Request: POST /v1/collections/{id}/items
curl · Request, POST /v1/collections/{id}/items
curl -X POST "https://api.uncommonear.com/v1/collections/example/items" \
  -H "Authorization: Bearer $UNCOMMON_EAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '"example"'
JavaScript · Request, POST /v1/collections/{id}/items
const url = "https://api.uncommonear.com/v1/collections/example/items";
const response = await fetch(url, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.UNCOMMON_EAR_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify("example"),
});
const data = await response.json();
console.log(response.status, data);
Python · Request, POST /v1/collections/{id}/items
import os
import requests

response = requests.post(
    "https://api.uncommonear.com/v1/collections/example/items",
    headers={"Authorization": "Bearer " + os.environ["UNCOMMON_EAR_API_KEY"]},
    json="example",
)
print(response.status_code, response.json())
JSON · 200 response
{
  "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"
      }
    }
  ],
  "results": [
    {
      "track": "example",
      "already_present": true
    }
  ]
}

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.