Start an async Director compose workflow

Async sibling of `composeFromSuggestion`. The Director Temporal workflow authors a canonical wire-shape Composition and saves it to `projects.composition`. Watch progress via the SSE stream at `/v1/projects/:id/compose/:composeJobId/stream`.

Authorization

AuthorizationBearer <token>

API key auth. Prefix cf_live_ for production orgs, cf_test_ for sandbox.

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

POST /projects/:id/compose body.

suggestionId?string

Length1 <= length

fromComposition?boolean

Reuse the project's current composition as the compose starting point (critique-retry path). The Director RE-AUTHORS graphics: if the current composition is client-authored and contains graphic clips (overlay/component/card), the request is refused (validation_error naming the clips) — render it verbatim with create_render instead. The director's own output (critique-retry) is exempt.

briefId?string

Compose from a persisted Brief (create_brief) — the intent-first door: every Brief field is HONORED or the request is refused loudly naming the field (window from beat moment-pinning; seeded graphics carried VERBATIM as locked clips; exclusions enforced; locale + caption emphasis threaded to the Director). Exactly ONE of suggestionId | fromComposition | briefId.

Length1 <= length

format?

Optional format override. Phase 2 ignores this — format precedence is project.compositionFormat → 9:16 fhd 30fps default.

scope?unknown

RequestScope discriminated union (per compose-api-contract.md). Editor-only scopes (captions/overlay-track/broll/overlay-instance/segment) require an editor-session token; API tokens get 403 on those.

critique?string

Structured critique block (per compose-api-contract.md decision #11). Capped at 2KB total; per-criterion blocks capped at 500 chars.

Lengthlength <= 2000

parentJobId?string

Pointer to the prior compose job this run iterates on. Surfaced on the resulting composeJobs row as baselineComposeJobId.

maxCandidates?integer

Ensemble size. TEMPORARILY PINNED TO 1 — the multi-candidate ensemble is disabled pending a global capture-concurrency bound (N>1 candidates overflow the org's Daytona capture disk and drop perception), so any value >1 is ignored and every compose runs a single candidate. Still accepted for forward-compat; will honor [1, 5] again once re-enabled.

Range1 <= value <= 5

budgetUsd?number

Per-job budget cap (USD). Clamped at the route against the org's composeMaxBudgetUsdPerJob setting.

Range0 < value

qualityThreshold?number

Composite-score accept threshold. Server default per contract.

Range0 <= value <= 10

seed?integer

Deterministic seed for replay. Threaded into the workflow id.

clientNonce?string

Opaque caller token that disambiguates intentional same-critique retries. Without it, identical (project, sug, seed, critique) tuples deduplicate at Temporal; with it, retries fire fresh workflows.

Lengthlength <= 64

holdAt?array<>

Opt-in checkpoint gates. Each named stage pauses the compose at its boundary (status → awaiting_input) for client review via resume. Absent/empty ⇒ fully autonomous. Non-empty ⇒ the run is a single spine.

Itemsitems <= 3

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/string/compose" \  -H "Content-Type: application/json" \  -d '{}'

{  "composeJobId": "string",  "projectId": "string",  "workflowId": "string",  "status": "queued",  "streamUrl": "string"}

{  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    }  }}

{  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    }  }}

{  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    }  }}

{  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    }  }}

{  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    }  }}

{  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    }  }}

{  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    }  }}

{  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    }  }}

{  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    }  }}

Start an async Director compose workflow

Authorization

Path Parameters

Request Body

Response Body

202application/json

400application/json

401application/json

402application/json

403application/json

404application/json

422application/json

429application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`