---
title: "Get a component entry"
method: GET
path: "/v1/components/{id}"
tags: ["components"]
---

# Get a component entry

`GET /v1/components/{id}`

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/components/{id}`
- 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`

Required permission: projects:read

## Path parameters

- `id` string, required

## Response `200`

Component entry.

- ComponentResponse: Component catalog entry per §Components.
  - `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.

## 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)