CueFrame

Explicitly acquire a selected external candidate through the pinned maintained installer in disposable staging. Pass body:{snapshot,name,expectedManifestSha256,variables,commandId}; native author sessions supply their replay-stable top-level commandId automatically through the existing adapter. Keep the snapshot and manifest digest exactly as observed. The response owns immutable original/transformed bytes and dependency/installer provenance; it does not execute source, convert arbitrary HTML or mark it CueFrame compatible. Inspect the receipt with get_registry_acquisition, then author through existing admitted component/template operations with the acquisition receipt ancestry. Changed source versions remain provenance-pending until exact adaptation bytes are captured. Never force-overwrite authored work or use an upstream preview as a CueFrame preview.

Atomically apply an array of CompositionOps to a project composition. All ops succeed or none do (transactional). Call describe_composition_ops without type for the compact operation list, then with a type for its exact JSON Schema. For negotiated component execution, read get_composition with componentExecutionVersions=["3","4"] and includeDependencies="true", then send componentExecutionVersions:[3,4] and that exact expectedBrandIdentity. A changed brand refuses the command; never refresh the witness to conceal a conflict. Explicit builtinSources selectors attach only the approved exact source pins referenced by the final composition. The additive `concurrency` envelope requires an endpoint confirmed to enforce guardedCompositionV1; unsupported hosted endpoints refuse it with unsupported_concurrency. Obtain dependency expectations from the observed composition; never rebuild a stale basis from current state. Every committing call REQUIRES `if_match`, the composition ETag from a fresh get_composition, or the `concurrency` envelope; a call with neither is refused with 428 precondition_required. On 409 stale_etag, read get_composition again and reconsider the batch against what changed; never copy the error's currentEtag into a retry without that read. `dry_run: true` validates without persisting. For negotiated component execution, EVERY dry-run and commit must still carry the observed `composition_id`, `concurrency:{mode:"exact",expectedRevision:<observed project revision>}` (or supported guarded dependency expectations), `componentExecutionVersions` and exact `expectedBrandIdentity`; retain the observed `if_match` too. Only non-negotiated legacy dry-runs may omit revision preconditions. Ops land on the project's ACTIVE composition unless you pass `composition_id` (mutually exclusive with `session_id`), which targets a specific one — that is how you author a second composition minted with new_composition and run an A/B. Use this to seed a composition (add media cl…

Insert a resolved builtin component package into an existing project. Pass template as the selected builtin id and body with projectId, the resolved documentSha256, insert:{startTime,idPrefix}, parameter values and explicit media bindings. Read get_composition first and retain expectedRevision, commandId, componentExecutionVersions:[3,4] and expectedBrandIdentity as required by the contract. Insertion preserves existing timeline content and package source offsets. Select pinned samples explicitly with media:{slot:{sample:true}}, or bind real media IDs. Missing required media is refused; samples are never selected implicitly. A stale revision, pin or brand refuses; do not silently refresh the witness. For ordinary templates, this operation retains its existing apply behavior.

Cancel an in-flight compose job (stop a runaway/mis-priced ensemble). Needs projectId + composeJobId (from compose). The director cancel is confirmed before the row flips; any linked charge is released. No-op-reject (422) if already terminal.

Cancel an in-flight NLE export (fcpxml/premiere). Needs projectId + exportId (from the export enqueue). No-op-reject (422) if already terminal.

Cancel a running async job (verify / preview / brand-kit-extract) returned by an enqueue call — abort a mis-priced job instead of waiting out its TTL. For box-backed jobs the warm box is reaped best-effort; cancel never meters. No-op-reject (422) if already terminal.

Cancel an in-flight render (stop a runaway/queued job). Needs projectId + renderId (from create_render). No-op if already terminal.

Compare a certified reference frame with an existing full-resolution PNG preview. Returns unaligned side-by-side and overlay images with exact source identities. Read editorial_run_source for the reference identity and preview_frame then wait_job for the candidate artifact. This call never rerenders or edits the composition. Frame numbers refer to the certified representation; use explicit event correspondence after intentional retiming. Optional views and identical-coordinate crop change only diagnostic evidence.

Start an async Director compose job: it authors an ensemble of full composition candidates, verifies each, and saves the winner to the project. Body must set EXACTLY ONE source (mutually exclusive): `briefId` — author FROM a persisted Brief (the PLANNED path: create_brief first; every Brief field is honored or the compose is refused loudly naming the field); `fromComposition: true` — author from the project's CURRENT composition (the GENERAL path: seed it with apply_composition first — your media clips are the intent, and any graphics you authored are CARRIED VERBATIM as locked clips the Director authors around, never re-authors or drops); or `suggestionId` — author from an AI clip suggestion (the CLIPPING path, paired with suggest_briefs). Returns { composeJobId, status, streamUrl }. Then call wait_job(kind="compose", id=composeJobId, projectId=...) to block until the winner is selected.

Ask the Director for editing advice on the project's CURRENT composition — it NEVER writes your composition (you stay the decider). Async: returns a consultJobId; then wait_job(kind="consult", id=consultJobId, projectId=...) surfaces the advisory envelope (assessment / proposals / principles / plan). `body.mode`: 'advise' = the planner agent (fast, ~30s-2min) returns a `plan` (framing/cuts/captions/graphics intents) as GUIDANCE you re-author from — no grounded scores, nothing to adopt; 'amend' (default) = the full author→judge→refine loop (minutes) returns a graded `assessment` + a fix candidate you ADOPT via select_candidate with its candidateIndex. ('explore' is coming soon → use amend.) `body.intent` = your goal in plain English; optional `body.focus` (editorial|spatial|brand|caption); `body.ifMatch` binds to your current etag. Use advise for a fast directional nudge, amend for a grounded, adoptable fix.

Create or UPSERT a brand kit (re-POSTing the same kitId updates it in place — this is also the brand-kit UPDATE path). Sets fonts/colors/logo. This is brand step 0 of the workflow: author the kit, then bind it to a PROJECT so colors/fonts/motion theme the output AUTOMATICALLY — pass its kitId as brandKitId to create_project, or attach it to an existing project via update_project (PATCH /projects/:id over REST). Without a bound kit, create_render produces UNBRANDED output. Tenant-scoped (no project arg).

Persist the video's INTENT as a Brief — the Director's rich input contract (spec: the storyboard skill's output lands here). Fields: goal (required), audience, platform, format, durationSec, tone, cta, locale (output language — all on-screen copy + captions), hook, caption, beats[] (each with an editorial intent and optional MOMENT PINNING {mediaId, startSec, endSec} — honored to-the-frame or refused), mustIncludes, captions {styleId, emphasisPhrases} (the big-serif emphasis treatment), motionStyle, seededGraphics (your authored overlay/component/card clips, carried VERBATIM as locked clips — never re-authored), exclusions (hard negatives: graphic kinds the Director must NEVER author + 'no-transitions'), gates {holdAt, autoApprove}. Then compose it: compose with {briefId}. The response carries the QUOTE (compose + estimated render) — relay it to your human BEFORE composing.

Top up the CURRENT org's credit wallet. Body { plan: "credit_pack_10"|"credit_pack_30"|"credit_pack_100" } → returns { url }: a hosted Stripe checkout page to open in a browser and confirm payment. There are no subscription tiers — a pack is a one-off top-up, and it is also the only thing that raises the generation (premium_credits) allowance. Always a URL — an existing saved card is NEVER charged silently; the human confirms on Stripe. The org is resolved from your key, never the body. Requires the billing:write scope. Only send a user here when get_account shows the relevant `balance` at or near zero. Discover the packs with list_plans.

Create and store a custom component for the tenant: a native scene that arranges its declared images and videos as tiles in 3D space. Returns the ComponentResponse (id + metadata) you can then reference from a composition. No project arg — components are tenant-scoped. SOURCE CONTRACT (version 4; the server instructions' Component Contract has the full rules and an example): send the complete source object {version:4, componentId, template, manifest, definition}. `template` is one sub-composition: a root <div id="root" data-composition-id="<componentId>" data-width data-height data-no-timeline data-composition-variables='…'> holding <div data-cf-scene></div>, and one inline script ending in __cfScene.mount({ root: document.getElementById('root'), component, variables: __hyperframes.getVariables() }). data-composition-variables is the definition's projection (scalar inputSchema properties, then manifest slots). The manifest is {version:4, runtime:'hyperframes', hfContract:1, kind:'scene', assets, graphics:{api:'webgl2',…}, alphaPolicy}; slots are image or video. The source is admitted before it is stored: template lint, determinism (no timers, Date, network or CSS animation) and the declaration are checked, and a refusal names the rule. A version-3 source is retired and refused as component_source_retired. Place it with execution {version:4, componentId, sourceVersionId, params, seed, assets:{ slot: mediaId }} and placement {version:3, kind:'clip'}; slots never travel in params.

Create a new project — the unit you compose and render into. compose / apply_composition / create_render / the preview family all require a projectId; this mints one. Pass name (required) plus optionally a format (aspectRatio/fps/resolution) and brandKitId. brandKitId binds a brand kit to the PROJECT (pass the kitId from create_brand_kit): colors/fonts/motion theme every render of this project automatically (omit it and the output is unbranded). Bind or change it later via update_project (PATCH /projects/:id over REST). Returns the ProjectResponse (id + metadata).

Queue an MP4 render of a project's composition (in a compose session, the session's scratch). Returns { id (renderId), status, warnings? } — `warnings[]` carries non-fatal advisories (omitted when none). The render themes from the project's brand kit (bind one via create_project / update_project with brandKitId — or PATCH /projects/:id over REST; without one the output is unbranded). Then call wait_job(kind="render", id=renderId, projectId=...) to block until the file is ready and get the download URL, or register a webhook (create_webhook on render.completed — status rides the payload).

Reserve a LOCAL portable CueFrame template package ZIP for import into the organization library. Supply idempotencyKey, archiveSha256 (exact lowercase SHA256) and archiveBytes (1..128MiB). Returns uploadId and a short-lived single PUT uploadUrl. PUT the exact raw archive bytes with Content-Type application/zip, then call import_template_package using uploadId. A reservation is not an import or a media item. Organization-library operation; project-bound editor credentials are refused.

Ingest a LOCAL file — bytes you hold, when there is no public URL to hand import_media (prefer import_media whenever the bytes already sit at an https URL). TWO steps: (1) this tool reserves a media item and returns { id, uploadUrl, expiresAt } — a short-lived PUT URL. PUT the raw file bytes to uploadUrl over HTTPS with your declared Content-Type (≤ ~5 GB per PUT). (2) call finalize_upload({ mediaItemId: id }) to start processing. Body: filename, contentType (allowed enum), size (bytes). Thereafter it is async exactly like import_media: poll list_media for processingStatus, or register a webhook (create_webhook on media.completed). Use the returned id with get_media_context, suggest_briefs, or as a composition source.

Register a webhook so long-running jobs notify you instead of blocking on wait_job — the right pattern for fan-out/async agents. Pass url + events — ONE terminal event per job kind with status INSIDE the payload (render.completed, compose.completed, media.completed, suggest.completed) plus checkpoint.ready (a held compose paused for review). DELIVERY: a POST { event, timestamp, projectId?, data } with Standard-Webhooks headers (webhook-id, webhook-timestamp, webhook-signature: v1,<base64>); the secret (whsec_<base64>) is returned ONCE — verify the RAW body with new Webhook(secret).verify(rawBody, headers). ACTIVATION is synchronous: CueFrame POSTs a signed webhook.verify challenge and your endpoint must reply 2xx echoing data.token — otherwise it returns status:"pending" and receives NO events (recover with verify_webhook, no delete/recreate). Read the cueframe://webhook-events resource (or GET /webhooks/events) for the full contract + every event's data shape BEFORE building your receiver.

Delete a brief. Compose jobs already run from it are unaffected (they snapshot).

Delete a composition (and its version history) from a project. REFUSES the ACTIVE composition (409) — make another one active first, or delete the project. Use list_compositions to see which is active.

Delete a registered critic by its criticId. It stops running in the Director gates and score_composition immediately.

Permanently delete a media item from your library (cleanup). Irreversible. Compositions referencing it will fail to render — only delete media no composition still needs.

Permanently delete a project you created (cleanup). Removes its composition and render history. Irreversible — only call on a project you own and no longer need.

Delete a webhook subscription (stop receiving its deliveries). Irreversible — the signing secret is invalidated.

Derive a reframed SIBLING composition for a different aspect ratio (the agent-native Auto-Reframe / Magic-Resize). Pass projectId + body { fromCompositionId, targetFormat: { aspectRatio, fps?, resolution? } }. CueFrame copies the source composition's authored intent and content-aware-reframes every clip for the new aspect (point/face/active-speaker focus), then saves a new independent composition in the same project. Returns { compositionId } — render it with create_render, or refine it with apply_composition. Use this to make 9:16 + 1:1 + 4:5 cuts from one 16:9 edit. (To only change resolution within the SAME aspect, pass create_render.format instead — that is a scale-only export override, not a new composition.)

Discover the exact CompositionOp vocabulary accepted by apply_composition. Omit type for a compact list of operation names and descriptions; pass type for only that operation's JSON Schema. Read this before authoring edits or captions.

Return the exact JSON Schema for a body field the tool list abbreviates. An abbreviated field names this tool in its description. Pass that tool and field.

Get a presigned download URL for a media item's stored SOURCE file — the bytes CueFrame composes from (the raw upload, or its conformed transcode). This is how you copy media OUT of a library: fetch the URL directly (no auth header) and PUT the bytes elsewhere with create_upload, or hand it to import_media on another account. Works as soon as the upload or import is stored, before processing completes. The URL expires at `expiresAt` (about an hour) — call again for a fresh one rather than caching it. Read-only and free; nothing is persisted. For a render's MP4 use refresh_render_url instead.

Commit an integrated editorial edit to the saved project composition with both runExpectedRevision and guarded composition fields. Preserve the observed concurrency basis and the composition journal identity: nested composition.commandId must equal composition.clientId + ":" + composition.sequence. The session call commandId is a separate HTTP request identity.

Persist an authored brief for the selected project. The projectId belongs in body.brief; use the returned briefId to start an editorial run.

Start an editorial run from a persisted brief and explicitly selected certified source ranges. Read editorial_run_source for each project media source first; use its exact identity, revision, frame count and fps ratio. Never invent a source pin or infer inspection from an index.

Persist one evidence-backed observation. A nothing_useful outcome may cover only what the cited evidence actually inspected; sparse stills do not certify an unsampled interval.

Read durable observations, including useful, nothing-useful and uncertain outcomes, in bounded pages. Pass nextCursor as cursor until done; retain evidence IDs, supersession and uncertainty when recovering decisions.

Read a persisted editorial run, including its revision, state, inputs, outline, selected finding IDs, omitted reasons and unresolved integration gaps. Read findings and evidence separately for complete coverage.

Deliver a bounded 16 kHz source audio interval and save an audio evidence receipt. The interval must lie inside a certified run input.

Deliver one exact decoded source frame as JPEG and save its evidence receipt. Only that sampled frame is visually inspected; preserve the returned evidenceId and coverage.

Deliver at most 100 verified transcript words with their mapped certified decode interval and save a transcript evidence receipt.

Save selected finding IDs, explicit omitted reasons and unresolved gaps with the observed run revision. Read the run and findings before deciding.

Recover persisted authored briefs for a project. Read bounded pages; pass nextCursor as cursor until done. Brief IDs link to editorial runs.

Read delivered evidence and inspection coverage for a run in bounded pages. Pass nextCursor as cursor until done; an empty page does not prove the whole source was inspected.

Recover persisted editorial runs for a project in bounded pages. Pass nextCursor as cursor until done, then read each relevant run for its integration decisions and unresolved gaps.

Read the certified decode representation for media selected in this project before starting an editorial run. Supply projectId and mediaId; a null representation means this source cannot be pinned. The response omits internal storage paths. Select a bounded range from the returned frameCount and exact fps ratio; do not invent a source identity.

Deliver bounded sampled motion frames and save their evidence receipt. The sampled frames do not certify continuous visual coverage.

Export an exact SAVED project snapshot as a portable template package. Supply idempotencyKey, expectedRevision, name, new slug and optional bounded mediaParams/textParams selectors for existing clip/leaf sites. Reads actual saved composition/components/media through the maintained extractor; no caller document, source, sample URL or provenance assertions. Returns a durable library-export job; poll get_template_job until ready, then pass its receiptId to get_template_package_download. An existing slug conflicts. A project-bound editor may export only its bound project. Does not render or create a new project.

Queue brand-token extraction from a website URL — ASYNC: returns a jobId immediately; then wait_job(kind="brand_kit_extract", id=jobId) for the tokens (colors/fonts/title/description, fetched + regex-parsed from the site's HTML/CSS — NOT a screenshot/vision pass). It does NOT persist — review the tokens, then call create_brand_kit to save a kit. A blocked (private/SSRF), non-2xx, non-HTML, or slow (>20s) URL degrades to EMPTY token arrays (a succeeded job) rather than erroring — JS-rendered SPAs typically extract empty; author the kit manually from the compiled CSS in that case.

Finalize a direct upload once you have PUT the bytes to the uploadUrl from create_upload. Confirms the bytes landed and starts ingest: image/asset become ready immediately (status "complete"); audio/video enter processing (status "processing"). Returns { id, status, processingPhase }. 400 if no bytes were uploaded (PUT first) or the item is not yours. Then call wait_job(kind="media", id=mediaItemId), or use a media.completed webhook.

Delete one entry from the org's learned taste by its id (from get_profile `taste` or remember_taste). This is how the user's "undo" works.

Generate one first-class Library media item from a prompt. Choose generator: text-to-video | text-to-image | image-to-video | text-to-music | text-to-speech | text-to-sfx | auto. Put supported presentation controls in body.style and first/last/image references in body.refs. Returns { id, status:"generating", estimateUsd? }; returns 402 if the estimate exceeds the per-call ceiling. Async — call wait_job(kind="media", id=mediaItemId) or use a webhook (media.completed — status rides the payload). Use the returned id like any other media item.