Kits

List kits

Returns the kits of the catalogue, cursor-paginated: named groups of items that go out together, with their components, collection and tags.

GET

/api/v1/kits

curl https://app.filmo.io/api/v1/kits \
  --header "Authorization: Bearer $FILMO_API_KEY"

Node.jsfetch('https://app.filmo.io/api/v1/kits', { headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY' } })Pythonimport requests requests.get("https://app.filmo.io/api/v1/kits", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY" } )

{
  "data": [
    {
      "id": "kit_9f3a2b",
      "name": "Example kit",
      "description": "Example text.",
      "image": "Example image",
      "collectionId": "collection_9f3a2b",
      "collectionName": "Example collection name",
      "tags": [
        {
          "id": "tag_9f3a2b",
          "name": "Example tag"
        }
      ],
      "components": [
        {
          "itemId": "item_9f3a2b",
          "itemName": "Example item name",
          "variantId": "variant_9f3a2b",
          "variantName": "Example variant name",
          "quantity": 1,
          "position": 1
        }
      ],
      "createdAt": "2026-09-01T08:00:00.000Z",
      "updatedAt": "2026-09-01T08:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvIjoyMH0",
    "hasMore": true,
    "total": 1
  }
}

{
  "type": "https://docs.filmo.io/errors/validation_error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "2 validation errors",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "name",
      "code": "too_small",
      "message": "Must be at least 1 characters long"
    },
    {
      "path": "contactType",
      "code": "invalid_value",
      "message": "Value not allowed; expected company, person"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing Authorization header: Bearer <api key>",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredScope": "kits:read"
}

{
  "type": "https://docs.filmo.io/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit exceeded: retry in 30 seconds",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "retryAfter": 30
}

{
  "type": "https://docs.filmo.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

Generated from the schema

Filter by collection and by tag (any of the given tags). Sorted by name; sort accepts a single field. Creation and update date filters are not available on this listing.

Authorizations

Bearer API key with the scope below. kits:read

Query parameters

limitintegerdefault:50

Page size (1-500). Defaults to 50.

Limits: min 1, max 500

cursorstring

Opaque cursor of the page to return. Pass the value of pagination.nextCursor from the previous response; treat it as opaque.

Limits: max length 200

sortstring

Sort order: a single field, with a leading "-" for descending (e.g. "-updatedAt"). Sortable fields: name, createdAt, updatedAt. Defaults to "name". Ties are broken by id, so the order is stable across pages, and a cursor is bound to the sort it was issued with.

Limits: max length 200

collectionIdstring

Filter by identifier of the collection the kit belongs to.

Limits: min length 1, max length 100

collectionIdsstring[]

Filter by collectionId, as a list: repeat the parameter or separate the values with commas. Accepts up to 50 values and returns whatever matches any of them.

Limits: min 1 items, max 50 items, each min length 1, each max length 100

tagIdstring

Filter by tag identifier: kits that carry that tag.

Limits: min length 1, max length 100

tagIdsstring[]

Filter by tagId, as a list: repeat the parameter or separate the values with commas. Accepts up to 50 values and returns whatever matches any of them.

Limits: min 1 items, max 50 items, each min length 1, each max length 100

includeTotalbooleandefault:false

Set it to true to include pagination.total, the number of results that match the filters across all pages. Off by default.

Response

application/json

Successful response.

Response schema: KitDto

Envelope: KitList. meta.warnings is present only when the operation is deprecated.

Headers: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset

dataobject[]

Show child attributes

data.idstring

Unique identifier of the kit.

data.namestring

Kit name.

data.descriptionstring | null

Kit description; null if it has none.

data.imagestring | null

URL of the main image; null if it has none.

data.collectionIdstring | null

Collection it belongs to; null if it is in none.

data.collectionNamestring | null

Full path of the collection; null if it is in none.

data.tagsobject[]

Kit tags, with their identifier and name.

Show child attributes

data.tags.idstring

Unique identifier of the tag.

data.tags.namestring

Tag name.

data.componentsobject[]

Items that make up the kit, in display order.

Show child attributes

data.components.itemIdstring

Identifier of the item; read it in /api/v1/items/{itemId}.

data.components.itemNamestring

Item name, as recorded when it was added to the kit.

data.components.variantIdstring | null

Variant of the item, if one was chosen; null otherwise.

data.components.variantNamestring | null

Name of that variant; null if none.

data.components.quantitynumber

How many units of the item the kit includes.

data.components.positionnumber | null

Display order inside the kit (0-based); null if not set.

data.createdAtstring<date-time>

Creation date in ISO 8601 UTC.

data.updatedAtstring<date-time>

Last modification date in ISO 8601 UTC.

paginationobject

Opaque-cursor pagination metadata.

Show child attributes

pagination.nextCursorstring | null

Opaque cursor of the next page; null when there are no more results. Pass it as cursor in the next request.

pagination.hasMoreboolean

Whether more results exist beyond this page.

pagination.totalinteger

Number of results matching the filters across all pages. Present only when the request sets includeTotal=true.

Limits: min 0

metaobject

Additional information about the response.

Show child attributes

meta.warningsobject[]

Lifecycle warnings; present only when the operation is deprecated.

Show child attributes

meta.warnings.codestring

Stable warning code.

Available options: deprecated

meta.warnings.messagestring

For people: what is deprecated, until when, and what to use.

meta.warnings.sunsetstring

Day (YYYY-MM-DD) the operation stops being served.

meta.warnings.replacementstring | null

operationId of the operation to use instead, or null if there is none.

meta.warnings.linkstring

Where the deprecation is documented (the changelog).

Errors

Status	Codes	Meaning
400	`validation_error`	Malformed query or body. `errors[]` lists every offending field with its stable code.

401, 403, 429, 500 can be returned by any operation. Errors

Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date. Versioning policy

Catalog & inventory
Kit
Named group of items that go out together.

Was this page helpful?

Request examples

Authorizations

Query parameters

Response

Errors

Deprecation

Related

Related pages

Kit