Workflow Templates | Sogni: Learn

Surface · Reusable recipes

#Workflow Templates

Saveable, parameterized versions of a workflow plan. A template declares typed inputs[] and a list of parameterized stages[]. Invoking by workflow_id + inputs compiles a fresh steps[] and starts a creative-workflow run that authorizes cost on start — it returns 202 with waitingForCostApproval: true and a preview, then dispatches once released via POST /:id/confirm-cost.

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

Create a workflow template. Returns 422 with structured issues when the template fails schema validation.

#Body

Name	Type	In	Description
name*	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	Template category. Defaults to `custom`.
stability	string	body	`experimental` (default), `beta`, or `stable`.
author	string	body	Defaults to `system`.
visibility	string	body	`private` (default), `public`.
inputs*	array	body	Typed input slots. Each entry declares `name`, `type`, optional default + validation.
stages*	array	body	Parameterized stages that compile into `steps[]` at run time. Bind to inputs via `$inputs.<name>`.
exposeToLLM	boolean	body	When `true`, the template appears as a callable tool in chat (`workflow:<id>`).
tags	string[]	body	Free-form tags.
graph	object	body	Optional visual-builder graph metadata. Round-trips with the form-based view.
previewArtifacts	object	body	Optional preview artifacts (sample image URLs etc.) used in template listings.
estimatedCapacityUnits	number\|object	body	Optional capacity-unit estimate. Used by callers to show price before 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", /* … */ } }
}

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

List workflow templates. Filter by visibility.

#Query parameters

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

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

Fetch a single template.

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

Update a template. Same field set as create; the new shape is re-validated before persistence.

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

Delete a template. Existing in-flight runs continue against their pinned template version.

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

Fork a public or shared template into the caller's namespace. Returns the new template.