Workflow Templates

A Workflow Template is a reusable blueprint that defines the structure of a workflow — its tasks, dependencies, and role slots — without running it. Each time you need a new execution of the same workflow shape, you create a WorkflowInstance from the template.

Templates are versioned immutably. Publishing a new version never modifies past instances.

When to use `client.workflowTemplates`

Defining standard operating procedures (e.g., "Customer Onboarding", "Contract Review")
Building a template library that your team can instantiate on demand
Rolling back to a prior template version when a change introduces problems
Pinning instances to specific template versions via aliases like "stable"

Methods

Method	Description
`create(input)`	Create a template (optionally with a v1 manifest and role slots)
`get(templateId)`	Fetch a template
`update(templateId, input)`	Update name or description
`delete(templateId)`	Delete template and all its versions
`list(opts?)`	List templates in a project
`publish(templateId, input)`	Publish a new version with an updated manifest
`listVersions(templateId)`	List immutable version history
`diffVersions(templateId, v1, v2)`	Compare two versions
`rollback(templateId, targetVersion)`	Roll back to a prior version (creates a new version)
`listAliases(templateId)`	List named aliases
`putAlias(templateId, alias, input)`	Point an alias at a specific version
`deleteAlias(templateId, alias)`	Delete an alias

`workflowTemplates.create(input)`

Parameters

Parameter	Type	Required	Description
`name`	`string`	yes	Template name
`description`	`string`	no	Human-readable description
`projectId`	`string`	no	Defaults to your personal project
`manifest`	`Record<string, unknown>`	no	Initial graph snapshot (nodes/edges)
`roles`	`RoleSlotInput[]`	no	Role slots for version 1

Example

typescript

const { data: template } = await client.workflowTemplates.create({
  name: 'Customer Onboarding',
  description: 'Standard new-customer workflow',
  roles: [
    { slotName: 'account-manager', required: true, description: 'Leads the onboarding' },
    { slotName: 'technical-lead', required: false },
  ],
})
 
console.log(template.id, template.version) // tmpl_... 1

`workflowTemplates.publish(templateId, input)`

Publishes a new immutable version. Existing instances are unaffected.

typescript

await client.workflowTemplates.publish('tmpl_abc123', {
  manifest: {
    nodes: [
      { id: 'task-1', name: 'Send welcome email', durationMinutes: 15 },
      { id: 'task-2', name: 'Schedule kickoff call', durationMinutes: 30 },
    ],
    edges: [{ from: 'task-1', to: 'task-2' }],
  },
  roles: [
    { slotName: 'account-manager', required: true },
  ],
})

`workflowTemplates.rollback(templateId, targetVersion)`

Creates a new version that is a copy of the target version. Never mutates history.

typescript

const { data: newVersion } = await client.workflowTemplates.rollback('tmpl_abc123', 3)
console.log(newVersion.version) // 7 (current version after rollback)

`workflowTemplates.putAlias(templateId, alias, input)`

Points a named alias at a specific version. Useful for deployment pipelines:

typescript

await client.workflowTemplates.putAlias('tmpl_abc123', 'stable', { version: 5 })
await client.workflowTemplates.putAlias('tmpl_abc123', 'latest', { version: 6 })

`workflowTemplates.diffVersions(templateId, version, against)`

typescript

const { data: diff } = await client.workflowTemplates.diffVersions('tmpl_abc123', 5, 6)
console.log(diff.added, diff.removed, diff.changed)

Type reference

typescript

interface WorkflowTemplate {
  id: string
  projectId: string
  name: string
  description: string | null
  version: number
  metadata: Record<string, unknown> | null
  createdAt: string
  updatedAt: string
}
 
interface RoleSlotInput {
  slotName: string
  description?: string
  required?: boolean
  constraints?: Record<string, unknown>
}

Workflow Instances — run a template as a live instance
Roles — fill role slots when instantiating a template