compose

Start an async Director compose workflow

Async sibling of composeFromSuggestion. The Director execution authors a canonical wire-shape Composition and saves it as the project's active composition. Watch progress via the SSE stream at /v1/projects/:id/compose/:composeJobId/stream.

post/v1/projects/{id}/compose

Request

  • Base URL: https://api.cueframe.ai
  • URL: https://api.cueframe.ai/v1/projects/{id}/compose
  • 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:write)
    • API key in header PAYMENT-SIGNATURE

Path parameters

idstring required

Request body

suggestionIdstring
fromCompositionboolean

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.

briefIdstring

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.

scopeunknown
critiquestring

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

parentJobIdstring

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

maxCandidatesinteger

Ensemble size, 1–5. Defaults to one; explicit multi-candidate runs divide the job budget across candidates and admit at most two concurrently. A held editorial checkpoint always uses one candidate.

budgetUsdnumber

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

qualityThresholdnumber

Composite-score accept threshold. Server default per contract.

seedinteger

Deterministic seed for replay.

clientNoncestring

Opaque caller token that disambiguates intentional same-critique retries. Without it, identical (project, sug, seed, critique) tuples deduplicate; with it, retries create a fresh execution.

holdAtstring[]

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.

Response

Compose job queued.

composeJobIdstring required

Opaque compose job id; pass to the SSE stream URL.

projectIdstring required
status'queued' | 'failed' required

queued = normal; failed = startup failed and the job is already terminal (the SSE stream will emit a single job_failed frame and close).

reconciliationRequiredboolean
streamUrlstring

Relative SSE endpoint to stream this job's events (per compose-api-contract.md).

Changes

No recorded changes to this operation across all 1 revision of this API.