Skip to navigation
ReferenceAPI Referencetemplates

Create Template

Create a reusable workflow template in the current workspace.

Templates are workspace-private on creation (is_public=false, is_starter=false). The full WorkflowDefinition (graph + execution config) is validated at write time — structural errors (duplicate node/edge IDs, port mismatches, etc.) surface here rather than when a caller later clones the template into a workflow.

Use this to capture a workflow configuration you intend to reuse or share. To make a template available in the public gallery, an admin must mark it public via the admin API. To create a runnable workflow from an existing template, use POST /templates/{id}/clone instead.

Requires workspace editor role or higher.

Authentication

AuthorizationBearer
Clerk JWT token

Headers

X-Workspace-Idstring or nullOptional

Request

This endpoint expects an object.
namestringRequired1-200 characters

Display name for the template (1–200 characters, not blank).

descriptionstring or nullOptional<=2000 characters

Optional human-readable description shown in the gallery (max 2,000 characters).

categoryenum or nullOptional
Optional category tag used for gallery filtering.
Allowed values:
definitionobjectOptional

Full workflow definition (graph + execution config). Validated at write time — structural errors are rejected with 422.

Response

Successful Response
dataobject

Response shape. workspace_id is intentionally omitted so the gallery endpoint (which returns rows from any workspace) does not leak tenant ownership IDs across tenants. created_by is retained as author provenance for public/starter rows.

definition is the serialized WorkflowDefinition JSONB (same shape as Workflow.definition) — a template is a reusable workflow snapshot.

metaobject

Errors

422
Unprocessable Entity Error