Clockwork

Roles

Roles are named slots declared in a workflow template (e.g., "account-manager", "legal-reviewer") that get filled with actual resources when the template is instantiated. This keeps templates generic and reusable while instances remain specific to real people or agents.

Planning v2 availability. The endpoints on this page behave the same with the planning-v2 flag on or off. For reference: planning v2 is merged to main and deployed to production (platform.clockwork-co.com), and the platform flag CLOCKWORK_PLANNING_V2 is currently on globally, in production and in preview, as of 2026-10-12. Per-organization gating (CLOCKWORK_PLANNING_V2=orgs) is merged but not enabled in production, so the global flag is the only access control in effect. Exact dates: Changelog.

When to use client.roles

  • Assigning real people to named positions in a newly created workflow instance
  • Checking which role slots are still unfilled on a running instance
  • Reassigning a role when a team member changes mid-workflow

Methods

MethodDescription
listForInstance(instanceId)List all role slots for an instance, with fulfillment status
fill(instanceId, slotName, resourceId)Fill a slot with a resource

roles.listForInstance(instanceId)

Returns each slot defined in the template, merged with its current fulfillment (if any).

typescript
const { data: roles } = await client.roles.listForInstance('wi_abc123')
 
for (const role of roles) {
  console.log(role.slotName, role.required, role.resourceId ?? 'UNFILLED')
}
// account-manager  true   res_alice
// legal-reviewer   false  null

roles.fill(instanceId, slotName, resourceId)

Assigns a resource to a slot. Reassigning is safe — calling fill() again replaces the previous assignment.

typescript
await client.roles.fill('wi_abc123', 'legal-reviewer', 'res_bob')

Defining slots in a template

Slots are declared when creating or publishing a template:

typescript
await client.workflowTemplates.publish('tmpl_abc123', {
  manifest: { /* task graph */ },
  roles: [
    { slotName: 'account-manager', required: true, description: 'Leads the client relationship' },
    { slotName: 'legal-reviewer', required: false },
    { slotName: 'technical-lead', required: true },
  ],
})

Type reference

typescript
interface InstanceRole {
  slotName: string
  description: string | null
  required: boolean
  constraints: Record<string, unknown>
  resourceId: string | null  // null if unfilled
  assignedAt: string | null
}
 
interface RoleAssignment {
  id: string
  instanceId: string
  slotName: string
  resourceId: string
  assignedAt: string
  unassignedAt: string | null
}

Related