---
title: "List component catalog (defaults + installed)"
method: GET
path: "/v1/components"
tags: ["components"]
---

# List component catalog (defaults + installed)

`GET /v1/components`

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/components`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.cueframe.ai/api/auth/mcp/authorize`, token URL `https://api.cueframe.ai/api/auth/mcp/token`, scopes: `projects:read`)
  - API key in header `PAYMENT-SIGNATURE`

Discover the built-in primitive catalog (87 primitives + 7 scenes) plus your installed components. Narrow with facet filters (category, kind, tier, useCase, mood) or free-text (q / intent); when ANY filter is set, results are ordered recommended-tier-first. With NO `limit` the WHOLE (filtered) catalog returns in one page — pass `limit` only to page. Each entry carries a `placement` hint telling you exactly how to author it on the timeline.

## Query parameters

- `projection` 'component-library'
- `origin` 'builtin' | 'library'
- `libraryKind` 'definition' | 'preset' | 'recipe'
- `category` 'text' | 'effects' | 'transitions' | 'layouts' | 'backgrounds' | 'ui-blocks' | 'scenes'
- `kind` 'component' | 'transition' | 'scene'
- `tier` 'recommended' | 'standard' | 'niche'
- `useCase` 'intro' | 'outro' | 'full-scene' | 'title-over-footage' | 'transition' | 'background' | 'grade' | 'emphasis' | 'explainer' | 'social-cut'
- `mood` string
- `q` string
- `intent` string
- `limit` integer
- `after` string

## Response `200`

Component catalog (filtered + recommend-ordered).

- union
  - LegacyComponentListResponse
    - `data` ComponentResponse[], required
      - `name` string, required
      - `description` string, required
      - `category` 'text' | 'effects' | 'transitions' | 'layouts' | 'backgrounds' | 'ui-blocks' | 'scenes', required
      - `propSchema` object, required
      - `origin` 'customer-owned' | 'server-native'
      - `ejectedFrom` string
      - `tokens` object
      - `examples` object[]: Usage examples, as authored. A built-in primitive projects {name, mood?, params?, description?}; an authored component's examples are whatever it wrote, which is why the item is open. One shape for both directions: what you write here is what you read back.
      - `durationInFrames` number
      - `manifest` union
        - ComponentManifestV4
          - `version` 4, required
          - `runtime` 'hyperframes', required
          - `hfContract` 1, required
          - `kind` 'scene', required
          - `sceneShot` object
            - `version` 2, required
          - `assets` object, required
          - `graphics` object, required
            - `api` 'canvas2d' | 'webgl' | 'webgl2' | 'webgpu', required
            - `required` true, required
            - `accelerationPreference` 'hardware-preferred' | 'software-allowed', required
          - `alphaPolicy` 'requires-transparency' | 'allows-opaque', required
        - ComponentManifestV2
          - `version` 2, required
          - `assets` object, required
          - `graphics` object, required
            - `api` 'canvas2d' | 'webgl' | 'webgl2' | 'webgpu', required
            - `required` true, required
            - `accelerationPreference` 'hardware-preferred' | 'software-allowed', required
          - `alphaPolicy` 'requires-transparency' | 'allows-opaque', required
          - `sceneShot` object
            - `version` 2, required
          - `visualMedia` object
            - `version` 1, required
      - `id` string, required: The entry's id: a `primitiveId` for a built-in, a `componentId` for an installed component.
      - `source` 'default' | 'installed', required: 'default' = built-in primitive (place by primitiveId); 'installed' = org-authored component (place by componentId).
      - `kind` 'component' | 'transition' | 'scene', required: RENDER kind (component | transition | scene). NOT the ClipSource variant — see `placement` for how to author it on the timeline.
      - `version` string, required: The ENTRY's version: a semver string ('0.0.0' until an authored component is versioned). Distinct from `manifest.version`, which is the runtime contract version (4 native, 2 retired TSX).
      - `propDefaults` object
      - `textParam` string, nullable: The param field that carries this primitive's primary text; null = no single text slot.
      - `subtextParam` string, nullable: The param field for secondary text (subtitle/byline); null = none.
      - `format` Format
        - `aspectRatio` '16:9' | '9:16' | '1:1' | '4:5', required
        - `fps` union
          - 24
          - 25
          - 30
          - 60
        - `resolution` 'hd' | 'fhd' | '4k'
        - `platform` string
      - `intent` string: Selection signal: a verb naming what this primitive accomplishes (e.g. 'product-trailer'). Match it to the beat you are authoring.
      - `useWhen` string: When to use this — AND when not to. The negative guidance is load-bearing; read it before picking.
      - `pairsWith` string[]: Authoring guidance: ids of primitives that COMPOSE well with this one in the same edit.
      - `avoidWith` string[]: Authoring guidance: ids of primitives that CONFLICT with this one — do not place together.
      - `tags` string[]: Free-text search keywords.
      - `mood` string[]: Vibe/tone tags (e.g. 'cinematic', 'minimal'). Filter to match the edit's mood.
      - `tier` 'recommended' | 'standard' | 'niche': Quality/applicability RANKING (a preference, not a flag). Prefer 'recommended'; reach for 'niche' only when its specific use-case is exactly the beat.
      - `useCase` string[]: The edit ROLE(s) this primitive fills — the dimension to filter by for a beat (e.g. 'intro', 'title-over-footage', 'grade').
      - `fixedCopy` string[]: On-screen strings this primitive BAKES — the read-side counterpart to propSchema. These literals render REGARDLESS of params (no param can change them); fork the source via get_component_source to edit them. Use this to see at author time what fixed copy (someone-else's marketing text, faux-code, faux-data) will appear before you render.
      - `brandBindings` object[]: Params that can follow the project brand kit. Each {param, brandToken} says: set `param` to `brandToken` (a `$brand:` ref, e.g. '$brand:colors.accent') to track the brand instead of a literal. See the list response's `brandTokens` for the full ref vocabulary. Omitted when nothing is brand-bound.
        - `param` string, required
        - `brandToken` string, required
      - `placement` ComponentPlacement, required
        - `clipSourceKind` 'overlay' | 'effect' | 'component', required: The ClipSource `kind` to author this entry as: 'overlay' (built-in text/ui/scene/background/layout), 'effect' (built-in effect/transition), or 'component' (an org-INSTALLED custom component).
        - `refField` 'primitiveId' | 'componentId', required: Which id field keys the ClipSource: 'primitiveId' for built-ins (source:'default'), 'componentId' for installed components (source:'installed'). Using the wrong field will NOT resolve at render.
      - `warnings` string[]: Non-blocking save-time advisories — the create/update SUCCEEDED. Currently: a `fontFamily` string literal referencing a NON-vendored font (a bare CSS generic like 'serif', or an unknown named family like 'Arial') whose LIVE-lane pixels vary by render host — re-author with a vendored family or 'Georgia'. Omitted when there is nothing to flag; only present on the create/update responses.
    - `pagination` PaginationMeta, required: Cursor pagination metadata.
      - `hasMore` boolean, required
      - `nextCursor` string, nullable, required
      - `prevCursor` string, nullable, required
    - `brandTokens` string[]: Catalog-level reference: the valid `$brand:` token refs a param value may carry (e.g. accentColor: "$brand:colors.accent"). Colors + fonts are the common bindings; the full design-token vocabulary is listed. Derived from the brand kit resolver so it can't drift. See each entry's `brandBindings` for which params are brand-bound by default.
    - `sfx` SfxCatalogEntry[]: Catalog-level reference: the curated CC0 SFX pack (closed, versioned). The compose sfx pass places these deterministically; this is the pack-only structural inventory to pick a `soundId` by family. Present on the first page only.
      - `soundId` string, required: Stable sound-pack item id.
      - `family` 'tick' | 'pop' | 'impact' | 'confirm' | 'error' | 'whoosh' | 'riser', required: Editorial family the compose sfx pass binds by.
      - `envelopeClass` 'transient' | 'sweep' | 'ambient', required: Coarse envelope shape — the browse grouping.
      - `intensity` 'subtle' | 'standard' | 'strong', required
      - `durationSec` number, required: Duration of the mastered asset (seconds).
      - `description` string, required: One-line human-legible caption.
      - `attribution` string, required: CC0 provenance string.
    - `audio` AudioPaletteEntry[]: The UNIFIED org sound palette (audio-substrate Phase 2): the curated packs (SFX + music beds) unioned with THIS org's own uploads/imports (source:"org") and generated audio (source:"generated"), one uniform entry shape carrying role + envelopeClass + provenance + license; music entries carry bpm. Prefer an org sound when it fits — an org that uploads its product's real UI sounds hears ITS product. Present on the first page only.
      - `ref` string, required: Placement handle: a pack soundId/bedId, or an org media id.
      - `role` 'vo' | 'music' | 'sfx' | 'ambience', required: Declared role for mix policy.
      - `envelopeClass` 'transient' | 'sweep' | 'ambient', required: Coarse envelope shape — the browse grouping.
      - `description` string, required
      - `durationSec` number, required
      - `evidence` object, required: Envelope probe evidence (always carries envelopeClass).
        - `envelopeClass` 'transient' | 'sweep' | 'ambient', required
        - `attackMs` number
        - `spectralCentroidHz` number
        - `meanVolumeDb` number
        - `maxVolumeDb` number
      - `source` 'pack' | 'org' | 'generated', required: Provenance discriminant.
      - `license` string, required: "CC0" (pack), "org-owned"/a CC token (org), or "generated".
      - `provenance` string, required: Human-legible provenance (pack attribution / org-owned / generator + prompt).
      - `bpm` number: Tempo — present for music-role entries.
      - `mood` string[]: Editorial mood tags — present for pack music beds.
  - object
    - `protocolVersion` 1, required
    - `scope` union
      - object
        - `kind` 'builtin', required
        - `collection` string, required
      - object
        - `kind` 'org-local', required
        - `orgId` string, required
        - `workspaceId` string, required
      - object
        - `kind` 'org-hosted', required
        - `orgId` string, required
        - `deploymentId` string, required
    - `data` union[], required
      - union
        - object
          - `identity` object, required
            - `scope` union, required
              - …
            - `id` string, required
            - `revision` string, required
          - `name` string, required
          - `description` string, required
          - `category` string, required
          - `presentation` object
            - `version` 1, required
            - `representativeTimeSeconds` number, required
          - `showcase` object
            - `version` 1, required
            - `presentationKey` string, required
            - `fixtureIdentity` string, required
            - `rendererIdentity` string, required
            - `video` object, required
              - …
            - `poster` object, required
              - …
          - `preview` object
            - `identity` string, required
            - `status` 'unproven' | 'verified', required
          - `kind` 'definition', required
          - `source` object, required
            - `scope` union, required
              - …
            - `componentId` string, required
            - `sourceVersionId` string, required
            - `sourceVersion` union, required
              - …
          - `declaration` object, required
            - `state` 'v3', required
            - `capabilities` union[], required
              - …
            - `timing` object, required
              - …
          - `origin` 'server-native' | 'customer-owned', required
        - object
          - `identity` object, required
            - `scope` union, required
              - …
            - `id` string, required
            - `revision` string, required
          - `name` string, required
          - `description` string, required
          - `category` string, required
          - `presentation` object
            - `version` 1, required
            - `representativeTimeSeconds` number, required
          - `showcase` object
            - `version` 1, required
            - `presentationKey` string, required
            - `fixtureIdentity` string, required
            - `rendererIdentity` string, required
            - `video` object, required
              - …
            - `poster` object, required
              - …
          - `preview` object
            - `identity` string, required
            - `status` 'unproven' | 'verified', required
          - `kind` 'preset', required
          - `definition` object, required
            - `scope` union, required
              - …
            - `componentId` string, required
            - `sourceVersionId` string, required
            - `sourceVersion` union, required
              - …
          - `presetVersionId` string, required
          - `historicalDocument` object, required
            - `scope` union, required
              - …
            - `documentId` string, required
            - `documentSha256` string, required
          - `equivalence` 'unproven' | 'verified', required
        - object
          - `identity` object, required
            - `scope` union, required
              - …
            - `id` string, required
            - `revision` string, required
          - `name` string, required
          - `description` string, required
          - `category` string, required
          - `presentation` object
            - `version` 1, required
            - `representativeTimeSeconds` number, required
          - `showcase` object
            - `version` 1, required
            - `presentationKey` string, required
            - `fixtureIdentity` string, required
            - `rendererIdentity` string, required
            - `video` object, required
              - …
            - `poster` object, required
              - …
          - `preview` object
            - `identity` string, required
            - `status` 'unproven' | 'verified', required
          - `kind` 'recipe', required
          - `document` object, required
            - `scope` union, required
              - …
            - `documentId` string, required
            - `documentSha256` string, required
          - `placementCount` integer, required
          - `memberSources` object[], required
            - `scope` union, required
              - …
            - `componentId` string, required
            - `sourceVersionId` string, required
            - `sourceVersion` union, required
              - …
          - `equivalence` 'unproven' | 'verified', required
    - `pagination` PaginationMeta, required: Cursor pagination metadata.
      - `hasMore` boolean, required
      - `nextCursor` string, nullable, required
      - `prevCursor` string, nullable, required

## Other responses

- `400`: Bad request — validation_error / invalid_cursor / invalid_query.
- `401`: Missing or invalid Authorization header.
- `402`: Payment required. Returned when the caller presents no API key on a priced operation: the body AND the `Payment-Required` header carry the x402 v2 challenge (accepted scheme, network, USDC asset, amount, payTo). Sign the EIP-3009 authorization and retry with a `PAYMENT-SIGNATURE` header. A KEYED caller sees this status instead when their plan lacks or has exhausted the feature (`billing_required`).
- `403`: Forbidden — permission insufficient.
- `404`: Resource not found.
- `422`: Unprocessable — invalid_composition / media_in_use / session_in_use / render_not_cancellable.
- `429`: Rate limited. Retry-After header present.
- `500`: Internal error.

---

[API](https://skmtc.dev/cueframe/apis/cueframe-api.md) · [All operations](https://skmtc.dev/cueframe/apis/cueframe-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cueframe/apis/cueframe-api/revisions/8f9bfe362b4a?raw)