API referenceChat and agents

Workflow Templates

Saveable, parameterized versions of a workflow plan. A template declares typed inputs[] and a list of parameterized stages[]. Invoking one with workflow_id and inputs compiles a fresh steps[] and starts a creative-workflow run that authorizes cost on start.

A template run returns 202 with waitingForCostApproval: true and a preview, then dispatches once released through POST /v1/creative-agent/workflows/:id/confirm-cost. Echo the preview within five minutes. A template that fails to compile returns 422 with details.compileErrors and details.compileWarnings.

#Create a template

POST /v1/creative-agent/workflows/templates Auth required

Returns 201 with the saved template. A template that fails validation returns 422 with the problems in data.validation.issues. A duplicate id returns 409. Each account can store a limited number of templates (403 beyond that), oversized templates return 413, and rapid changes return 429 with retryAfter.

#Body

Name	Type	In	Description
namerequired	string	body	Human-readable template name.
description	string	body	Plain-text description shown in builders and listings.
brief	string	body	Optional planner brief that produced this template.
category	string	body	`portrait`, `video-social`, `makeover`, `cinematic`, `music`, `analysis`, `custom` (default), or `other`.
stability	string	body	`experimental` (default), `beta`, or `production`.
author	object	body	Set by the server to `{ userId, displayName }` for your account. Any value you send is ignored.
visibility	string	body	`private` (default). Publishing a template as `public` is not available to API accounts and returns `403`.
inputs	array	body	Typed input slots: `{ name, type, required, description, default?, options?, multiple? }`, where `type` is `image`, `audio`, `video`, `text`, `number`, `select`, or `boolean`.
stages	array	body	Parameterized stages that compile into `steps[]` at run time. Bind to inputs with `$inputs.<name>`.
exposeToLLM	boolean	body	Optional flag for template discovery surfaces. Defaults to `false`.
tags	string[]	body	Free-form tags.
graph	object	body	Optional visual-builder graph metadata. Round-trips with the form-based view.
previewArtifacts	array	body	Optional preview artifacts for listings: `{ stageId, label, mediaType, url, posterUrl? }`, where `mediaType` is `image` or `video`.
estimatedCapacityUnits	object	body	Optional `{ min, max }` capacity-unit estimate, used to show a price range before a run.
llmPriority	number	body	Optional ranking signal when the LLM exposes saved workflows as tools.
metadata	object	body	Arbitrary caller metadata.
id	string	body	Optional caller-chosen ID. Otherwise minted server-side.

#Response

{
  "status": "success",
  "data": { "template": { "id": "wf_…", "version": "0.0.1", "…": "…" } }
}

#List templates

GET /v1/creative-agent/workflows/templates Auth required

Lists workflow templates, filtered by visibility. Returns data.templates and data.next.

#Query parameters

Name	Type	In	Description
visibility	string	query	`own`, `public`, or `all` (default). Other values are treated as `all`.
offset	integer	query	Default `0`.
limit	integer	query	Default `20`, max `100`.

#Read a template

GET /v1/creative-agent/workflows/templates/:id Auth required

Fetches a single template.

#Update a template

PATCH /v1/creative-agent/workflows/templates/:id Auth required

Send only the fields to change. They are merged into the stored template and re-validated (422 on failure), and the patch version is bumped. id, version, and author are ignored. A template you don't own returns 404.

#Delete a template

DELETE /v1/creative-agent/workflows/templates/:id Auth required

Returns { deleted: true, id }. Existing in-flight runs continue against their pinned template version. A template you don't own returns 404.

#Fork a template

POST /v1/creative-agent/workflows/templates/:id/fork Auth required

Copies a public template, or one you own, into a new private template. Optional body { "name": "…" }. Returns 201; the copy starts at version 0.0.1, records clonedFromTemplateId, and counts toward your template limit.