Create a collection (POST /v1/collections)

POST/v1/collections

Creates a named Collection of one kind, empty or with tracker_ids you already have (all or nothing). The kind is fixed; members may come from any Platform. At most 50 per Customer.

Price

Free.

Request body

application/json

object

namestringrequiredlength 1 to 100Unique among your Collections, regardless of case.
kindstringrequiredone of creator, hashtag, sound, advertiserWhat every member will be. Fixed once created. video is deprecated and refused with 400 kind_deprecated.
tracker_idsarray of stringitems at most 100Trackers you already have to put in it at once, all of kind. Created with them or not at all.

Responses

201 Created

{ collection }.

object

collectionobjectrequiredA named set of Trackers of one kind. Holds no state: pausing, analysis and cycles belong to each Tracker.
- idstringrequired
- namestringrequiredUnique per Customer, regardless of case.
- kindstringrequiredone of creator, hashtag, sound, advertiser, videoWhat every member is. Fixed at creation. video is deprecated: existing Video Collections keep working, new ones are refused with 400 kind_deprecated.
- member_countintegerrequiredLive (active or paused) member Trackers.
- created_atstringrequired
- updated_atstringrequired

201 · `{ collection }`.

{
  "collection": {
    "id": "col_7d20e1b5c4",
    "name": "Competitors",
    "kind": "creator",
    "member_count": 0,
    "created_at": "2026-09-02T09:14:40.221Z",
    "updated_at": "2026-09-02T09:14:40.221Z"
  }
}

400 Bad Request

kind_deprecated — video is deprecated: no new Video Collections. Track the Creator, a Hashtag or a Sound instead. Nothing is created or charged. Or: invalid_request — a malformed body, an empty or over-long name, an unknown kind, or more than 100 tracker_ids.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

400 · kind_deprecated

{
  "type": "https://www.shortsintel.com/docs/reference/errors/kind_deprecated",
  "title": "Kind deprecated",
  "status": 400,
  "code": "kind_deprecated",
  "detail": "Video Trackers and Collections can no longer be created. Track the Creator, a Hashtag or a Sound instead: their cycles re-snapshot the Videos they find every day.",
  "supported_kinds": [
    "creator",
    "hashtag",
    "sound",
    "advertiser"
  ]
}

400 · invalid_request

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "name must not be empty."
}

401 Unauthorized

missing_authorization, invalid_key, key_revoked or invalid_token.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

401 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_key",
  "title": "Invalid key",
  "status": 401,
  "code": "invalid_key",
  "detail": "That API key does not exist. Keys look like `sk_live_...` and are created in the console."
}

404 Not Found

not_found.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

404 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "A `tracker_ids` entry is not one of this Customer's Trackers."
}

409 Conflict

collection_name_taken — you already have a Collection with that name, in any case. Carries collection_id. Or: collection_limit_exceeded at 50 Collections. Or: collection_kind_mismatch — the Tracker is not of the Collection's kind.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
detailstring

409 · collection_name_taken

{
  "type": "https://www.shortsintel.com/docs/reference/errors/collection_name_taken",
  "title": "Collection name taken",
  "status": 409,
  "code": "collection_name_taken",
  "detail": "You already have a Collection named \"Competitors\". Names are unique regardless of case.",
  "collection_id": "col_7d20e1b5c4"
}

409 · collection_limit_exceeded

{
  "type": "https://www.shortsintel.com/docs/reference/errors/collection_limit_exceeded",
  "title": "Collection limit exceeded",
  "status": 409,
  "code": "collection_limit_exceeded",
  "detail": "This Customer already has 50 Collections, the limit is 50. Delete one first.",
  "limit": 50,
  "count": 50
}

409 · collection_kind_mismatch

{
  "type": "https://www.shortsintel.com/docs/reference/errors/collection_kind_mismatch",
  "title": "Collection kind mismatch",
  "status": 409,
  "code": "collection_kind_mismatch",
  "detail": "\"Competitors\" is a Collection of creator Trackers and cannot hold a video.",
  "collection_kind": "creator",
  "kind": "video"
}

Request samples

curl -X POST "https://www.shortsintel.com/v1/collections" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Competitors","kind":"creator"}'

const response = await fetch(
  "https://www.shortsintel.com/v1/collections",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "name": "Competitors",
      "kind": "creator"
    }),
  },
);

if (!response.ok) {
  throw new Error(`ShortsIntel ${response.status}`);
}

const data = await response.json();

import requests

response = requests.post(
    "https://www.shortsintel.com/v1/collections",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
    json={
        "name": "Competitors",
        "kind": "creator",
    },
)
response.raise_for_status()

data = response.json()