Skip to main content
POST
/
api
/
v1
/
tasks
/
{id}
/
tools
/
{callId}
/
approve
Approve Tool Call
curl --request POST \
  --url https://api.example.com/api/v1/tasks/{id}/tools/{callId}/approve

Documentation Index

Fetch the complete documentation index at: https://docs.sigmic.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Approve Tool Call

When a task is created with autoExecute=false, tool calls require manual approval before they execute. Use this endpoint to approve or reject pending tool calls.

​
Request

POST /api/v1/tasks/{id}/tools/{callId}/approve
Authorization: Bearer {api_key}
Content-Type: application/json

​
Path Parameters

ParameterTypeDescription
idstringThe unique task identifier
callIdstringThe tool call identifier (from the tool_call event)

​
Request Body

{
  "outcome": "proceed_once"
}
FieldTypeRequiredDescription
outcomestringYesThe approval decision

​
Outcome Values

ValueDescription
proceed_onceExecute this specific tool call only
proceed_alwaysExecute and auto-approve similar calls for this session
cancelReject the tool call

​
Response

{
  "success": true,
  "data": {
    "approved": true
  }
}
FieldTypeDescription
approvedbooleantrue if approved, false if cancelled

​
Workflow

​
1. Create Task with Manual Approval

# Create the task (returns JSON immediately)
curl -s -X POST https://api.sigmic.ai/api/v1/tasks \
  -H "Authorization: Bearer sigmic_your_key_here" \
  -F "message=List all files in the current directory" \
  -F "autoExecute=false"
Response: 
{
  "success": true,
  "data": { "id": "c37c1d78-...", "status": "pending" }
}

​
2. Connect to Stream & Receive Tool Call Event

Connect to the stream endpoint to receive events. When the agent needs to use a tool, you’ll receive: 
event: tool_call
data: {"type":"tool_call","data":{"callId":"call_abc123","toolName":"list_directory","status":"awaiting_approval","args":{"path":"/workspace"}}}
You can also poll GET /api/v1/tasks/:id to check for pendingApprovals without using SSE.

​
3. Approve or Reject

curl -X POST https://api.sigmic.ai/api/v1/tasks/TASK_ID/tools/call_abc123/approve \
  -H "Authorization: Bearer sigmic_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "proceed_once"}'

​
4. Task Continues

After approval, the tool executes and the task continues. You’ll receive:
  • tool_result event with the execution result
  • Continued content events as the agent processes the result

​
Full Example

const API_KEY = 'sigmic_your_key_here';
const BASE_URL = 'https://api.sigmic.ai';

async function createTaskWithApproval(message) {
  // 1. Create the task (returns JSON immediately)
  const formData = new FormData();
  formData.append('message', message);
  formData.append('autoExecute', 'false');

  const createResponse = await fetch(`${BASE_URL}/api/v1/tasks`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${API_KEY}` },
    body: formData
  });

  const { data: { id: taskId } } = await createResponse.json();
  console.log('Task created:', taskId);

  // 2. Connect to the stream endpoint
  const streamResponse = await fetch(`${BASE_URL}/api/v1/tasks/${taskId}/stream`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });

  const reader = streamResponse.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const events = buffer.split('\n\n');
    buffer = events.pop() || '';

    for (const event of events) {
      if (!event.trim() || event.startsWith(':')) continue;
      const lines = event.split('\n');
      const eventType = lines[0]?.replace('event: ', '');
      const dataLine = lines[1]?.replace('data: ', '');
      if (!dataLine) continue;

      const data = JSON.parse(dataLine);

      // Handle tool call requiring approval
      if (eventType === 'tool_call' && data.status === 'awaiting_approval') {
        const { callId, toolName, args } = data;

        console.log(`Tool "${toolName}" wants to execute with args:`, args);

        // Decide whether to approve (in real app, you might prompt user)
        const shouldApprove = true;

        const approvalResponse = await fetch(
          `${BASE_URL}/api/v1/tasks/${taskId}/tools/${callId}/approve`,
          {
            method: 'POST',
            headers: {
              'Authorization': `Bearer ${API_KEY}`,
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              outcome: shouldApprove ? 'proceed_once' : 'cancel'
            })
          }
        );

        const result = await approvalResponse.json();
        console.log('Approval result:', result);
      }

      if (eventType === 'content') {
        process.stdout.write(data.text);
      }

      if (eventType === 'done') {
        console.log('\nTask completed');
      }
    }
  }
}

createTaskWithApproval('Read the contents of package.json');

​
Use Cases

Security Review

Review file system operations before allowing the agent to read or write files

Cost Control

Approve API calls to external services that may incur costs

Audit Trail

Log all tool executions for compliance and debugging

Sensitive Operations

Manually approve operations involving sensitive data

​
Errors

CodeDescription
AUTH_REQUIREDNo authentication provided
INVALID_API_KEYInvalid or expired API key
NOT_FOUNDTask or tool call not found
VALIDATION_ERRORInvalid outcome value