Source: https://docs.sogni.ai/api-reference/templates/

# 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`](https://docs.sogni.ai/api-reference/workflows/#workflows-confirm-cost). Echo the preview within five minutes. A template that fails to compile returns `422` with `details.compileErrors` and `details.compileWarnings`.

### POST /v1/creative-agent/workflows/templates

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`.

### [#](https://docs.sogni.ai/api-reference/templates/#body)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. |

### [#](https://docs.sogni.ai/api-reference/templates/#response)Response

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

### GET /v1/creative-agent/workflows/templates

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

### [#](https://docs.sogni.ai/api-reference/templates/#query-parameters)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`. |

### GET /v1/creative-agent/workflows/templates/:id

Fetches a single template.

### PATCH /v1/creative-agent/workflows/templates/:id

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 /v1/creative-agent/workflows/templates/:id

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

### POST /v1/creative-agent/workflows/templates/:id/fork

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.