Skip to main content

​
Overview

The Approvals API manages the approval workflow for tool executions that require human review. When a tool call requires approval based on policy configuration, an approval record is created and must be resolved before execution can proceed.

​
Main Functions

​
resolveApproval

Resolves a pending approval with an approval or denial decision. This is a workspace mutation that requires admin privileges.
​
approvalId
string
required
The approval identifier to resolve
​
decision
'approved' | 'denied'
required
The approval decision
​
reviewerId
string
Identifier of the reviewer making the decision
​
reason
string
Optional reason for the decision
Returns the updated approval record. 
// Approve a tool execution
await resolveApproval({
  approvalId: 'approval_abc123',
  decision: 'approved',
  reviewerId: 'user_xyz',
  reason: 'Verified request authenticity'
});

// Deny a tool execution
await resolveApproval({
  approvalId: 'approval_abc123',
  decision: 'denied',
  reviewerId: 'user_xyz',
  reason: 'Insufficient justification'
});

​
Internal Functions

​
createApproval

Creates a new approval record for a tool execution.
​
id
string
required
Unique approval identifier
​
taskId
string
required
The task requesting tool execution
​
toolPath
string
required
Full path of the tool being invoked (e.g., "github.create_issue")
​
input
object
The input parameters passed to the tool
​
id
string
Unique approval identifier
​
taskId
string
Associated task ID
​
toolPath
string
Tool path requiring approval
​
input
unknown
Tool input parameters
​
status
ApprovalStatus
Current status: "pending", "approved", or "denied"
​
reason
string
Reason provided for approval/denial decision
​
reviewerId
string
Identifier of the reviewer who resolved the approval
​
createdAt
number
Unix timestamp when approval was created
​
resolvedAt
number
Unix timestamp when approval was resolved
const approval = await createApproval({
  id: 'approval_abc123',
  taskId: 'task_xyz',
  toolPath: 'github.delete_repository',
  input: { owner: 'myorg', repo: 'sensitive-repo' }
});

​
getApproval

Retrieves an approval by its ID.
​
approvalId
string
required
The approval identifier
Returns the approval record or null if not found. 
const approval = await getApproval({ approvalId: 'approval_abc123' });
if (approval && approval.status === 'pending') {
  console.log('Approval is still pending');
}

​
listApprovals

Lists approvals in a workspace, optionally filtered by status.
​
workspaceId
Id<'workspaces'>
required
Workspace to list approvals from
​
status
ApprovalStatus
Filter by status: "pending", "approved", or "denied"
Returns up to 500 approvals, ordered by creation time (most recent first). 
// Get all pending approvals
const pending = await listApprovals({
  workspaceId,
  status: 'pending'
});

// Get all approvals (any status)
const allApprovals = await listApprovals({ workspaceId });

​
listPendingApprovals

Retrieves pending approvals with associated task information.
​
workspaceId
Id<'workspaces'>
required
Workspace identifier
Returns an array of approval records enriched with task details:
​
id
string
Approval identifier
​
taskId
string
Associated task ID
​
toolPath
string
Tool requiring approval
​
input
unknown
Tool input parameters
​
status
'pending'
Always "pending" for this query
​
createdAt
number
When approval was created
​
task
object
Associated task information
​
task.id
string
Task identifier
​
task.status
TaskStatus
Current task status
​
task.runtimeId
string
Runtime environment
​
task.timeoutMs
number
Task timeout
​
task.createdAt
number
Task creation time
Returns up to 500 pending approvals, ordered by creation time (oldest first). 
const pendingWithTasks = await listPendingApprovals({ workspaceId });

for (const approval of pendingWithTasks) {
  console.log(`Tool: ${approval.toolPath}`);
  console.log(`Task: ${approval.task.id} (${approval.task.status})`);
  console.log(`Created: ${new Date(approval.createdAt).toISOString()}`);
}

​
resolveApproval (Internal)

Internal mutation for resolving approvals without workspace context validation.
​
approvalId
string
required
Approval identifier
​
decision
'approved' | 'denied'
required
Approval decision
​
reviewerId
string
Reviewer identifier
​
reason
string
Decision reason
Returns the updated approval or null if the approval wasn’t in pending status.

​
getApprovalInWorkspace

Retrieves an approval only if it belongs to the specified workspace.
​
approvalId
string
required
Approval identifier
​
workspaceId
Id<'workspaces'>
required
Workspace ID to verify against
Returns the approval or null if not found or workspace mismatch. 
const approval = await getApprovalInWorkspace({
  approvalId: 'approval_abc123',
  workspaceId: workspaceId
});

if (!approval) {
  console.log('Approval not found in this workspace');
}

​
Approval Workflow

The typical approval workflow:
  1. Task Execution: A task attempts to call a tool that requires approval
  2. Approval Creation: System creates an approval record with status: "pending"
  3. Notification: Workspace admins are notified of pending approval
  4. Review: Admin reviews the tool path, input parameters, and context
  5. Resolution: Admin calls resolveApproval() with decision
  6. Continuation: Task execution resumes based on the decision
// Monitor pending approvals
const pending = await listPendingApprovals({ workspaceId });

for (const approval of pending) {
  // Review approval details
  console.log(`Tool: ${approval.toolPath}`);
  console.log(`Input:`, approval.input);
  
  // Make decision based on policy
  const shouldApprove = await reviewApprovalPolicy(approval);
  
  await resolveApproval({
    approvalId: approval.id,
    decision: shouldApprove ? 'approved' : 'denied',
    reviewerId: currentUserId,
    reason: shouldApprove 
      ? 'Matches security policy'
      : 'Requires additional authorization'
  });
}
  • ApprovalStatus: "pending" | "approved" | "denied"
  • TaskStatus: "queued" | "running" | "completed" | "failed" | "timed_out" | "denied"

Build docs developers (and LLMs) love

Get started for freeTalk to us