---
title: "Get a project's composition"
method: GET
path: "/v1/projects/{id}/composition"
tags: ["compositions"]
---

# Get a project's composition

`GET /v1/projects/{id}/composition`

## Request

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

## Query parameters

- `componentExecutionVersions` '3'
- `includeDependencies` 'true' | 'false'
- `compositionId` string

## Response `200`

The composition wire shape, or its observed dependency envelope when requested.

- union
  - object
    - `composition` Composition, required
      - `v` 1, required
      - `format` Format, required
        - `aspectRatio` '16:9' | '9:16' | '1:1' | '4:5', required
        - `fps` union
          - 24
          - 25
          - 30
          - 60
        - `resolution` 'hd' | 'fhd' | '4k'
        - `platform` string
      - `tracks` object[], required
        - `id` string, required
        - `kind` 'video' | 'audio' | 'image' | 'overlay' | 'effect', required
        - `name` string
        - `enabled` boolean
        - `volume` number
        - `contents` union[], required
          - union
            - TimelineClip
              - …
            - object
              - …
      - `markers` object[]
        - `id` string, required
        - `startTime` number, required
        - `endTime` number
        - `kind` string, required
        - `name` string
        - `metadata` object
      - `captions` union
        - object
          - `source` 'derived', required
          - `from` object, required
            - `clipId` string, required
          - `segments` object[], required
            - `words` object[], required
              - …
          - `style` object
            - `fontFamily` string
            - `fontSize` number: Font size as % of composition height (1-15, default 5). NOT px.
            - `fontWeight` integer
            - `color` string
            - `highlightColor` string
            - `backgroundColor` string
            - `plate` 'glass' | 'solid' | 'none'
            - `position` 'top' | 'center' | 'bottom'
            - `region` object: Optional caption layout box {x,y,w,h} in normalized output-frame coordinates. Overrides position; text starts at its top edge and wraps/pages within its width and height.
              - …
            - `textTransform` 'none' | 'uppercase' | 'capitalize'
            - `letterSpacing` number: Base caption glyph spacing in pixels.
            - `wordGapEm` number: Gap between caption runs as a multiple of base font size; default 0.35.
            - `lineGapEm` number: Gap between caption lines as a multiple of base font size; default 0.25.
            - `emphasisColor` string
            - `emphasisGradient` string
            - `emphasisScale` number
            - `emphasisFontFamily` string
            - `emphasisFontWeight` integer
            - `emphasisTextTransform` 'none' | 'uppercase' | 'capitalize'
            - `emphasisLetterSpacing` number
            - `emphasisFontStyle` 'normal' | 'italic'
            - `entrance` 'none' | 'fade' | 'word-pop' | 'stagger-up'
            - `entranceMs` number
            - `entranceStaggerMs` number
            - `exitMs` number
            - `emphasisPlate` boolean
            - `emphasisPlateColor` string
            - `emphasisPlateTextColor` string
            - `emphasisPlateAltColor` string
            - `emphasisPlateAltTextColor` string
            - `emphasisPlateRadius` number
            - `emphasisPlatePadX` number
            - `emphasisPlatePadY` number
            - `emphasisPlateReveal` boolean: Grow a shared emphasis plate as saved words appear while reserving its final layout width.
            - `annotationColor` string
            - `annotationStrokeWidth` number: Annotation stroke width in its 100×100 SVG coordinate system; default 4.
            - `annotationTexture` 'clean' | 'pencil': Native annotation stroke finish; default clean.
            - `maxWidthPercent` number
          - `layouts` object[]
            - `segmentIndex` integer, required
            - `wordStartIndex` integer, required
            - `wordEndIndex` integer, required: Exclusive word index in the saved caption segment.
            - `region` object, required
              - …
            - `scale` number
            - `rotation` number
            - `style` object
              - …
            - `holdThroughWordIndex` integer: Inclusive saved-word index in this segment. The layout stays visible until that word ends.
            - `wordMarks` object[]
              - …
            - `wordSignature` string, required
          - `zPlane` 'front' | 'behind-subject'
        - object
          - `source` 'authored', required
          - `segments` object[], required
            - `words` object[], required
              - …
          - `style` object
            - `fontFamily` string
            - `fontSize` number: Font size as % of composition height (1-15, default 5). NOT px.
            - `fontWeight` integer
            - `color` string
            - `highlightColor` string
            - `backgroundColor` string
            - `plate` 'glass' | 'solid' | 'none'
            - `position` 'top' | 'center' | 'bottom'
            - `region` object: Optional caption layout box {x,y,w,h} in normalized output-frame coordinates. Overrides position; text starts at its top edge and wraps/pages within its width and height.
              - …
            - `textTransform` 'none' | 'uppercase' | 'capitalize'
            - `letterSpacing` number: Base caption glyph spacing in pixels.
            - `wordGapEm` number: Gap between caption runs as a multiple of base font size; default 0.35.
            - `lineGapEm` number: Gap between caption lines as a multiple of base font size; default 0.25.
            - `emphasisColor` string
            - `emphasisGradient` string
            - `emphasisScale` number
            - `emphasisFontFamily` string
            - `emphasisFontWeight` integer
            - `emphasisTextTransform` 'none' | 'uppercase' | 'capitalize'
            - `emphasisLetterSpacing` number
            - `emphasisFontStyle` 'normal' | 'italic'
            - `entrance` 'none' | 'fade' | 'word-pop' | 'stagger-up'
            - `entranceMs` number
            - `entranceStaggerMs` number
            - `exitMs` number
            - `emphasisPlate` boolean
            - `emphasisPlateColor` string
            - `emphasisPlateTextColor` string
            - `emphasisPlateAltColor` string
            - `emphasisPlateAltTextColor` string
            - `emphasisPlateRadius` number
            - `emphasisPlatePadX` number
            - `emphasisPlatePadY` number
            - `emphasisPlateReveal` boolean: Grow a shared emphasis plate as saved words appear while reserving its final layout width.
            - `annotationColor` string
            - `annotationStrokeWidth` number: Annotation stroke width in its 100×100 SVG coordinate system; default 4.
            - `annotationTexture` 'clean' | 'pencil': Native annotation stroke finish; default clean.
            - `maxWidthPercent` number
          - `layouts` object[]
            - `segmentIndex` integer, required
            - `wordStartIndex` integer, required
            - `wordEndIndex` integer, required: Exclusive word index in the saved caption segment.
            - `region` object, required
              - …
            - `scale` number
            - `rotation` number
            - `style` object
              - …
            - `holdThroughWordIndex` integer: Inclusive saved-word index in this segment. The layout stays visible until that word ends.
            - `wordMarks` object[]
              - …
            - `wordSignature` string, required
          - `zPlane` 'front' | 'behind-subject'
      - `sourceSuggestionId` string
      - `license` object
        - `type` string, required
        - `source` string
        - `notes` string
      - `licenseVerification` 'attested' | 'cueframe-verified' | 'third-party-verified'
      - `accessibility` object
        - `audioDescriptionTrackId` string
        - `captionsTrackId` string
        - `signLanguageTrackId` string
        - `notes` string
      - `ownerOrgId` string
      - `acl` object
        - `public` boolean
        - `readerOrgIds` string[]
        - `writerOrgIds` string[]
    - `composition_id` string, required
    - `revision` integer, required
    - `dependencies` union, required
      - object
        - `mode` 'guarded', required
        - `basis` object[], required
          - `key` string, required
          - `token` string, required
        - `absentClipToken` 'null', required
      - object
        - `mode` 'exact', required
        - `reason` string, required
    - `expectedBrandIdentity` string
    - `brandAuthorityError` string
    - `needsUpgrade` CompositionUpgradeNeed[]
      - `clipId` string, required
      - `kind` 'unpinned-component' | 'v3-component' | 'retired-primitive' | 'legacy-keyframes', required
      - `channels` string[]
      - `componentId` string
      - `sourceVersionId` string
      - `primitiveId` string
      - `successorComponentId` string
      - `successorSourceVersionId` string
  - CompositionRead: A composition as GET /projects/:id/composition answers it: the kernel's Composition, plus `needsUpgrade` when clips are stored in a retired form (absent otherwise).
    - `v` 1, required
    - `format` Format, required
      - `aspectRatio` '16:9' | '9:16' | '1:1' | '4:5', required
      - `fps` union
        - 24
        - 25
        - 30
        - 60
      - `resolution` 'hd' | 'fhd' | '4k'
      - `platform` string
    - `tracks` object[], required
      - `id` string, required
      - `kind` 'video' | 'audio' | 'image' | 'overlay' | 'effect', required
      - `name` string
      - `enabled` boolean
      - `volume` number
      - `contents` union[], required
        - union
          - TimelineClip
            - `id` string, required
            - `startTime` number, required
            - `duration` number, required
            - `source` union, required
              - …
            - `kind` 'video' | 'audio' | 'image' | 'overlay' | 'effect'
            - `opacity` number
            - `scale` number
            - `rotation` number
            - `position` object: Clip CENTRE as a fraction of the frame: {x:0.5,y:0.5} is dead centre, 0 to 1 is inside the frame, and a little overshoot (down to -1, up to 2) is how an entrance starts off-canvas. NOT pixels: the renderer maps x to `left: x*100%`, so `x: 180` sits 180 frame-widths away and draws nothing.
              - …
            - `region` object
              - …
            - `fit` 'cover' | 'contain'
            - `captionVisibility` 'visible' | 'hidden': Video media clip only. Hide native captions while this clip is topmost and covers the lower picture, or when an opaque, effect-free clip has an explicitly full-frame region, even with fit:contain. Caption words and timings remain stored and resume when another visible clip takes over.
            - `effects` object[]
              - …
            - `transitionIn` object
              - …
            - `linkGroupId` string
            - `tweens` object[]
              - …
            - `automation` object
              - …
            - `legacyKeyframes` object
              - …
          - object
            - `id` string, required
            - `startTime` number, required
            - `duration` number, required
    - `markers` object[]
      - `id` string, required
      - `startTime` number, required
      - `endTime` number
      - `kind` string, required
      - `name` string
      - `metadata` object
    - `captions` union
      - object
        - `source` 'derived', required
        - `from` object, required
          - `clipId` string, required
        - `segments` object[], required
          - `words` object[], required
            - `text` string, required
            - `startMs` number, required: Word start on the composition timeline, in milliseconds.
            - `endMs` number, required: Word end on the composition timeline, in milliseconds.
            - `emphasis` boolean
            - `annotate` 'circle' | 'underline'
        - `style` object
          - `fontFamily` string
          - `fontSize` number: Font size as % of composition height (1-15, default 5). NOT px.
          - `fontWeight` integer
          - `color` string
          - `highlightColor` string
          - `backgroundColor` string
          - `plate` 'glass' | 'solid' | 'none'
          - `position` 'top' | 'center' | 'bottom'
          - `region` object: Optional caption layout box {x,y,w,h} in normalized output-frame coordinates. Overrides position; text starts at its top edge and wraps/pages within its width and height.
            - `x` number, required
            - `y` number, required
            - `w` number, required
            - `h` number, required
          - `textTransform` 'none' | 'uppercase' | 'capitalize'
          - `letterSpacing` number: Base caption glyph spacing in pixels.
          - `wordGapEm` number: Gap between caption runs as a multiple of base font size; default 0.35.
          - `lineGapEm` number: Gap between caption lines as a multiple of base font size; default 0.25.
          - `emphasisColor` string
          - `emphasisGradient` string
          - `emphasisScale` number
          - `emphasisFontFamily` string
          - `emphasisFontWeight` integer
          - `emphasisTextTransform` 'none' | 'uppercase' | 'capitalize'
          - `emphasisLetterSpacing` number
          - `emphasisFontStyle` 'normal' | 'italic'
          - `entrance` 'none' | 'fade' | 'word-pop' | 'stagger-up'
          - `entranceMs` number
          - `entranceStaggerMs` number
          - `exitMs` number
          - `emphasisPlate` boolean
          - `emphasisPlateColor` string
          - `emphasisPlateTextColor` string
          - `emphasisPlateAltColor` string
          - `emphasisPlateAltTextColor` string
          - `emphasisPlateRadius` number
          - `emphasisPlatePadX` number
          - `emphasisPlatePadY` number
          - `emphasisPlateReveal` boolean: Grow a shared emphasis plate as saved words appear while reserving its final layout width.
          - `annotationColor` string
          - `annotationStrokeWidth` number: Annotation stroke width in its 100×100 SVG coordinate system; default 4.
          - `annotationTexture` 'clean' | 'pencil': Native annotation stroke finish; default clean.
          - `maxWidthPercent` number
        - `layouts` object[]
          - `segmentIndex` integer, required
          - `wordStartIndex` integer, required
          - `wordEndIndex` integer, required: Exclusive word index in the saved caption segment.
          - `region` object, required
            - `x` number, required
            - `y` number, required
            - `w` number, required
            - `h` number, required
          - `scale` number
          - `rotation` number
          - `style` object
            - `fontFamily` string
            - `fontSize` number: Font size as % of composition height (1-15, default 5). NOT px.
            - `fontWeight` integer
            - `color` string
            - `highlightColor` string
            - `backgroundColor` string
            - `plate` 'glass' | 'solid' | 'none'
            - `textTransform` 'none' | 'uppercase' | 'capitalize'
            - `letterSpacing` number: Base caption glyph spacing in pixels.
            - `wordGapEm` number: Gap between caption runs as a multiple of base font size; default 0.35.
            - `lineGapEm` number: Gap between caption lines as a multiple of base font size; default 0.25.
            - `emphasisColor` string
            - `emphasisScale` number
            - `emphasisFontFamily` string
            - `emphasisFontWeight` integer
            - `emphasisTextTransform` 'none' | 'uppercase' | 'capitalize'
            - `emphasisLetterSpacing` number
            - `emphasisFontStyle` 'normal' | 'italic'
            - `emphasisPlate` boolean
            - `emphasisPlateColor` string
            - `emphasisPlateTextColor` string
            - `emphasisPlateAltColor` string
            - `emphasisPlateAltTextColor` string
            - `emphasisPlateRadius` number
            - `emphasisPlatePadX` number
            - `emphasisPlatePadY` number
            - `emphasisPlateReveal` boolean: Grow a shared emphasis plate as saved words appear while reserving its final layout width.
            - `annotationColor` string
            - `annotationStrokeWidth` number: Annotation stroke width in its 100×100 SVG coordinate system; default 4.
            - `annotationTexture` 'clean' | 'pencil': Native annotation stroke finish; default clean.
            - `entrance` 'none' | 'fade' | 'word-pop' | 'stagger-up'
            - `entranceMs` number
            - `entranceStaggerMs` number
            - `exitMs` number
          - `holdThroughWordIndex` integer: Inclusive saved-word index in this segment. The layout stays visible until that word ends.
          - `wordMarks` object[]
            - `wordIndex` integer, required
            - `emphasis` boolean
            - `annotate` 'circle' | 'underline', nullable
          - `wordSignature` string, required
        - `zPlane` 'front' | 'behind-subject'
      - object
        - `source` 'authored', required
        - `segments` object[], required
          - `words` object[], required
            - `text` string, required
            - `startMs` number, required: Word start on the composition timeline, in milliseconds.
            - `endMs` number, required: Word end on the composition timeline, in milliseconds.
            - `emphasis` boolean
            - `annotate` 'circle' | 'underline'
        - `style` object
          - `fontFamily` string
          - `fontSize` number: Font size as % of composition height (1-15, default 5). NOT px.
          - `fontWeight` integer
          - `color` string
          - `highlightColor` string
          - `backgroundColor` string
          - `plate` 'glass' | 'solid' | 'none'
          - `position` 'top' | 'center' | 'bottom'
          - `region` object: Optional caption layout box {x,y,w,h} in normalized output-frame coordinates. Overrides position; text starts at its top edge and wraps/pages within its width and height.
            - `x` number, required
            - `y` number, required
            - `w` number, required
            - `h` number, required
          - `textTransform` 'none' | 'uppercase' | 'capitalize'
          - `letterSpacing` number: Base caption glyph spacing in pixels.
          - `wordGapEm` number: Gap between caption runs as a multiple of base font size; default 0.35.
          - `lineGapEm` number: Gap between caption lines as a multiple of base font size; default 0.25.
          - `emphasisColor` string
          - `emphasisGradient` string
          - `emphasisScale` number
          - `emphasisFontFamily` string
          - `emphasisFontWeight` integer
          - `emphasisTextTransform` 'none' | 'uppercase' | 'capitalize'
          - `emphasisLetterSpacing` number
          - `emphasisFontStyle` 'normal' | 'italic'
          - `entrance` 'none' | 'fade' | 'word-pop' | 'stagger-up'
          - `entranceMs` number
          - `entranceStaggerMs` number
          - `exitMs` number
          - `emphasisPlate` boolean
          - `emphasisPlateColor` string
          - `emphasisPlateTextColor` string
          - `emphasisPlateAltColor` string
          - `emphasisPlateAltTextColor` string
          - `emphasisPlateRadius` number
          - `emphasisPlatePadX` number
          - `emphasisPlatePadY` number
          - `emphasisPlateReveal` boolean: Grow a shared emphasis plate as saved words appear while reserving its final layout width.
          - `annotationColor` string
          - `annotationStrokeWidth` number: Annotation stroke width in its 100×100 SVG coordinate system; default 4.
          - `annotationTexture` 'clean' | 'pencil': Native annotation stroke finish; default clean.
          - `maxWidthPercent` number
        - `layouts` object[]
          - `segmentIndex` integer, required
          - `wordStartIndex` integer, required
          - `wordEndIndex` integer, required: Exclusive word index in the saved caption segment.
          - `region` object, required
            - `x` number, required
            - `y` number, required
            - `w` number, required
            - `h` number, required
          - `scale` number
          - `rotation` number
          - `style` object
            - `fontFamily` string
            - `fontSize` number: Font size as % of composition height (1-15, default 5). NOT px.
            - `fontWeight` integer
            - `color` string
            - `highlightColor` string
            - `backgroundColor` string
            - `plate` 'glass' | 'solid' | 'none'
            - `textTransform` 'none' | 'uppercase' | 'capitalize'
            - `letterSpacing` number: Base caption glyph spacing in pixels.
            - `wordGapEm` number: Gap between caption runs as a multiple of base font size; default 0.35.
            - `lineGapEm` number: Gap between caption lines as a multiple of base font size; default 0.25.
            - `emphasisColor` string
            - `emphasisScale` number
            - `emphasisFontFamily` string
            - `emphasisFontWeight` integer
            - `emphasisTextTransform` 'none' | 'uppercase' | 'capitalize'
            - `emphasisLetterSpacing` number
            - `emphasisFontStyle` 'normal' | 'italic'
            - `emphasisPlate` boolean
            - `emphasisPlateColor` string
            - `emphasisPlateTextColor` string
            - `emphasisPlateAltColor` string
            - `emphasisPlateAltTextColor` string
            - `emphasisPlateRadius` number
            - `emphasisPlatePadX` number
            - `emphasisPlatePadY` number
            - `emphasisPlateReveal` boolean: Grow a shared emphasis plate as saved words appear while reserving its final layout width.
            - `annotationColor` string
            - `annotationStrokeWidth` number: Annotation stroke width in its 100×100 SVG coordinate system; default 4.
            - `annotationTexture` 'clean' | 'pencil': Native annotation stroke finish; default clean.
            - `entrance` 'none' | 'fade' | 'word-pop' | 'stagger-up'
            - `entranceMs` number
            - `entranceStaggerMs` number
            - `exitMs` number
          - `holdThroughWordIndex` integer: Inclusive saved-word index in this segment. The layout stays visible until that word ends.
          - `wordMarks` object[]
            - `wordIndex` integer, required
            - `emphasis` boolean
            - `annotate` 'circle' | 'underline', nullable
          - `wordSignature` string, required
        - `zPlane` 'front' | 'behind-subject'
    - `sourceSuggestionId` string
    - `license` object
      - `type` string, required
      - `source` string
      - `notes` string
    - `licenseVerification` 'attested' | 'cueframe-verified' | 'third-party-verified'
    - `accessibility` object
      - `audioDescriptionTrackId` string
      - `captionsTrackId` string
      - `signLanguageTrackId` string
      - `notes` string
    - `ownerOrgId` string
    - `acl` object
      - `public` boolean
      - `readerOrgIds` string[]
      - `writerOrgIds` string[]
    - `needsUpgrade` CompositionUpgradeNeed[]
      - `clipId` string, required
      - `kind` 'unpinned-component' | 'v3-component' | 'retired-primitive' | 'legacy-keyframes', required
      - `channels` string[]
      - `componentId` string
      - `sourceVersionId` string
      - `primitiveId` string
      - `successorComponentId` string
      - `successorSourceVersionId` string

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