---
title: "One-call agent context: composition + media + transcript + brand"
method: GET
path: "/v1/projects/{id}/context"
tags: ["projects"]
---

# One-call agent context: composition + media + transcript + brand

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

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/projects/{id}/context`
- 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`, `media:read`)
  - API key in header `PAYMENT-SIGNATURE`

Everything an authoring agent needs to open a project, in ONE read: the active composition (with its format and markers hoisted), the project's media pool with a `hasTranscript` flag per item, the first transcribed item's word-timed transcript, and the brand kit bound to the project. Replaces the get_composition + get_media_context + get_profile opening sequence. A freshly created project reads back with `composition: null` — that is the empty state, not an error; 404 means the project doesn't exist for your org. Transcript BODIES are never inlined per media item — read another item's with GET /v1/media/{id}/transcript, and its faces/beat/word grids with GET /v1/media/{id}/context. The media pool is capped at 50; mediaPagination reports whether more exists. Continue with paginated GET /v1/media?projectId=... (list_media in MCP) to see the rest.

## Path parameters

- `id` string, required

## Response `200`

Aggregated context.

- ProjectContextResponse: One-call agent context for a project: composition + format + media pool + the lead transcript + the bound brand kit + markers. Replaces get_composition + get_media_context + get_profile at the start of an authoring session. A 404 means the project doesn't exist for your org — never that it is empty.
  - `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
            - `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[]
  - `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
  - `media` ProjectContextMedia[], required: The first 50 items in the org's media library (most recent first) — the pool this project can draw clips from. Check mediaPagination before treating this as complete.
    - `id` string, required
    - `name` string, required
    - `kind` string, nullable, required
    - `durationSec` number, nullable, required: Seconds. Uses the media duration when known; audio without one falls back to its transcript's measured duration (same rule as get_media_context).
    - `hasTranscript` boolean, required: A cached transcript EXISTS for this item. The bodies are never inlined here — fetch one with GET /v1/media/{id}/transcript (or get_media_context for faces + grids too).
  - `mediaPagination` object, required
    - `hasMore` boolean, required: Whether more org media exists beyond this orientation page.
    - `nextCursor` string, nullable, required: Continuation cursor for paginated GET /v1/media (list_media in MCP); null when hasMore is false.
  - `transcript` union, required
    - object
      - `status` 'ready', required
      - `mediaId` string, required
      - `words` object[], required: At most the first 200 words, for orientation; use paginated GET /v1/media/{id}/transcript for exact later words.
        - `text` string, required
        - `start` number, required: Word onset (SECONDS from source start).
        - `end` number, required: Word end (SECONDS from source start).
      - `totalWords` integer, required: Number of words in the lead transcript.
      - `hasMore` boolean, required: True when the lead transcript extends beyond the 200-word orientation preview.
    - object
      - `status` 'unavailable', required
      - `mediaId` string, required
  - `brandKit` BrandKitResponse, required: Brand kit response per §Brand Kits.
    - `id` string, required
    - `name` string, required
    - `description` string, nullable, required
    - `tagline` string, nullable, required
    - `colors` object, required
    - `extraColors` object[]
      - `name` string, required
      - `value` string, required
    - `fonts` object, required
      - `heading` object, nullable, required
        - `family` string, required
        - `weight` union
          - number
          - string
      - `body` object, nullable, required
        - `family` string, required
        - `weight` union
          - number
          - string
    - `voiceGuidelines` string, nullable, required
    - `captions` object, required
      - `sync` boolean, required
      - `profile` object, nullable, required
    - `motion` object
      - `duration` number
      - `easing` union
        - 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out'
        - object
          - `kind` 'cubic-bezier', required
          - `x1` number, required
          - `y1` number, required
          - `x2` number, required
          - `y2` number, required
      - `entrance` 'none' | 'fade' | 'word-pop' | 'stagger-up'
      - `staggerMs` number
      - `exitMs` number
    - `logo` object
      - `src` string, required
      - `alt` string
      - `placement` 'tl' | 'tr' | 'bl' | 'br'
      - `sizePct` number
    - `intro` object
      - `kind` 'card' | 'video', required
      - `src` string
      - `title` string
      - `subtitle` string
      - `durationMs` number
    - `outro` object
      - `kind` 'card' | 'video', required
      - `src` string
      - `title` string
      - `subtitle` string
      - `durationMs` number
    - `watermark` object
      - `src` string, required
      - `opacity` number
      - `placement` 'tl' | 'tr' | 'bl' | 'br'
    - `spacing` object
      - `base` number
      - `lg` number
      - `sm` number
    - `sizing` object
      - `fontSizeHeading` number
      - `fontSizeBody` number
      - `fontSizeLabel` number
      - `borderRadius` number
    - `audio` object
      - `sfxIntensity` 'off' | 'light' | 'standard' | 'dense'
      - `musicEnabled` boolean
      - `musicMood` string
      - `sonicLogo` object: A brand sound signature bound to the intro/outro bookend. `ref` = a palette reference; bound only when the kit carries the matching bumper (intro/outro), else a non-blocking advisory.
        - `ref` string, required
        - `placement` 'intro' | 'outro' | 'both', required
        - `offsetMs` integer
      - `uiSoundSet` object: Per-family SFX overrides (the brand's own tick/pop/…). Highest-priority tier over the org palette + pack default in the compose SFX draw.
        - `tick` string
        - `pop` string
        - `impact` string
        - `confirm` string
        - `error` string
        - `whoosh` string
        - `riser` string
      - `bedStyle` object: Preferred music bed (`bedId`) or a style hint (`genre` / `bpmRange`). Surfaced for driving agents; compose does not auto-select a pack bed.
        - `bedId` string
        - `genre` string
        - `bpmRange` object
          - `min` number, required
          - `max` number, required
      - `ambiencePreference` object, nullable: Preferred ambience bed (`{ref}`) or explicit null (opt-out). Surfaced for driving agents; compose has no ambience auto-placement.
        - `ref` string, required
    - `exemplarKeys` string[]
    - `contactSheetKey` string
    - `motifs` object[]
      - `id` string, required
      - `observed` string, required
      - `body` union, required
        - object
          - `kind` 'card', required
          - `html` string, required
          - `tokens` object
        - object
          - `kind` 'overlay', required
          - `primitiveId` string, required
          - `params` object
        - object
          - `kind` 'component', required
          - `componentId` string, required
          - `props` object
      - `motion` object
        - `preset` 'fade-up' | 'slide-in-left' | 'slide-in-right' | 'scale-pop' | 'stagger-reveal', required
        - `enterMs` integer
        - `exitMs` integer
        - `staggerMs` integer
        - `confidence` 'high' | 'low'
      - `role` 'title-card' | 'stat' | 'lower-third' | 'pull-quote' | 'hero' | 'logo-tag' | 'enumeration' | 'sequence' | 'comparison', required
      - `zone` object
        - `x` number, required
        - `y` number, required
        - `w` number, required
        - `h` number, required
      - `evidence` integer[]
      - `diffScore` number
      - `coverage` 'reproduced' | 'approximated' | 'skipped', required
      - `skipReason` string
    - `styleRubric` string
    - `density` object
      - `graphicsPerMin` number, required
      - `maxSimultaneous` integer, required
    - `inspiration` object
      - `sources` string[], required
      - `extractedAt` number, required
      - `extractionVersion` string, required
    - `createdAt` string, required
    - `updatedAt` string, required
  - `markers` object[], required: The composition's markers — hoisted alongside `format`. Empty when the composition carries none AND when there is no composition yet.
    - `id` string, required
    - `startTime` number, required
    - `endTime` number
    - `kind` string, required
    - `name` string
    - `metadata` object

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