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). Set when iterating on an existing composition.

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. Server default per contract; clamp [1, 5].

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

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    }  }}

Start an async Director compose workflow

Authorization

Path Parameters

Request Body

Response Body

202application/json

400application/json

401application/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`