Approvals

An Approval is a sign-off gate. It blocks the associated task or workflow from progressing until an authorized person approves or rejects it. Use approvals for compliance checkpoints, legal reviews, or any step where a human decision is required before work continues.

When to use `client.approvals`

Requiring a manager to sign off before an offer letter goes out
Gating artifact acceptance (e.g., a contract must be approved before the deal closes)
Building compliance workflows where every step requires documented approval
Creating human-in-the-loop AI workflows where an agent's output needs review

Methods

Method	Description
`create(input)`	Create an approval request
`list(opts?)`	List approvals in a project
`approve(approvalId, input?)`	Approve the request
`reject(approvalId, input?)`	Reject the request

`approvals.create(input)`

Parameters

Parameter	Type	Required	Description
`taskId`	`string`	no	Gate a specific task
`artifactId`	`string`	no	Gate a specific artifact
`instanceId`	`string`	no	Gate a workflow instance
`requiredRoleId`	`string`	no	Only actors with this role can approve
`requestedByActorId`	`string`	no	Who is requesting approval
`reason`	`string`	no	Explanation shown to the approver

typescript

const { data: approval } = await client.approvals.create({
  taskId: 'tsk_abc123',
  reason: 'Contract requires legal sign-off before countersigning',
  requiredRoleId: 'role_legal',
})
 
console.log(approval.id, approval.status) // appr_... 'pending'

`approvals.approve(approvalId, input?)`

typescript

await client.approvals.approve('appr_abc123', {
  decidedByActorId: 'actor_alice',
  reason: 'Reviewed and approved — all terms acceptable',
})

`approvals.reject(approvalId, input?)`

typescript

await client.approvals.reject('appr_abc123', {
  decidedByActorId: 'actor_alice',
  reason: 'Clause 7 needs revision — see comments in the document',
})

Building an approval inbox

typescript

// Fetch all pending approvals for a project
const { data: pending } = await client.approvals.list({ projectId: 'proj_xyz' })
const pendingApprovals = pending.filter(a => a.status === 'pending')
 
for (const approval of pendingApprovals) {
  console.log(`Approval needed: ${approval.reason}`)
  console.log(`Task: ${approval.taskId}`)
}

Type reference

typescript

type ApprovalStatus = 'pending' | 'approved' | 'rejected'
 
interface Approval {
  id: string
  projectId: string
  executionId: string | null
  instanceId: string | null
  taskId: string | null
  artifactId: string | null
  requiredRoleId: string | null
  requestedByActorId: string | null
  decidedByActorId: string | null
  status: ApprovalStatus
  reason: string | null
  metadata: Record<string, unknown> | null
  createdAt: string
  decidedAt: string | null
}

Artifacts — attach artifacts to approvals
Roles — restrict approvals to specific roles
Guides: Human-in-the-Loop — end-to-end approval workflow guide