> ## 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

> Approve or reject a pending tool call

# 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

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

### Path Parameters

| Parameter | Type   | Description                                           |
| --------- | ------ | ----------------------------------------------------- |
| `id`      | string | The unique task identifier                            |
| `callId`  | string | The tool call identifier (from the `tool_call` event) |

### Request Body

```json theme={null}
{
  "outcome": "proceed_once"
}
```

| Field     | Type   | Required | Description           |
| --------- | ------ | -------- | --------------------- |
| `outcome` | string | Yes      | The approval decision |

### Outcome Values

| Value            | Description                                             |
| ---------------- | ------------------------------------------------------- |
| `proceed_once`   | Execute this specific tool call only                    |
| `proceed_always` | Execute and auto-approve similar calls for this session |
| `cancel`         | Reject the tool call                                    |

## Response

```json theme={null}
{
  "success": true,
  "data": {
    "approved": true
  }
}
```

| Field      | Type    | Description                              |
| ---------- | ------- | ---------------------------------------- |
| `approved` | boolean | `true` if approved, `false` if cancelled |

## Workflow

### 1. Create Task with Manual Approval

```bash theme={null}
# 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:

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL (Approve) theme={null}
  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"}'
  ```

  ```bash cURL (Reject) theme={null}
  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": "cancel"}'
  ```
</CodeGroup>

### 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

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Security Review" icon="shield">
    Review file system operations before allowing the agent to read or write files
  </Card>

  <Card title="Cost Control" icon="dollar-sign">
    Approve API calls to external services that may incur costs
  </Card>

  <Card title="Audit Trail" icon="clipboard-list">
    Log all tool executions for compliance and debugging
  </Card>

  <Card title="Sensitive Operations" icon="lock">
    Manually approve operations involving sensitive data
  </Card>
</CardGroup>

## Errors

| Code               | Description                 |
| ------------------ | --------------------------- |
| `AUTH_REQUIRED`    | No authentication provided  |
| `INVALID_API_KEY`  | Invalid or expired API key  |
| `NOT_FOUND`        | Task or tool call not found |
| `VALIDATION_ERROR` | Invalid `outcome` value     |