> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Shashank-H/gaiter-gaurd/llms.txt
> Use this file to discover all available pages before exploring further.

# Approvals

> Manage approval requests for high-risk agent actions

<Info>All approval endpoints require authentication via Bearer token. These endpoints allow dashboard users to view and manage pending approval requests from their agents.</Info>

## List pending approvals

<api>GET /approvals/pending</api>

Retrieve all pending approval requests for agents owned by the authenticated user.

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <jwt>`
</ParamField>

### Response

<ResponseField name="approvals" type="object[]">
  <Expandable title="properties">
    <ResponseField name="action_id" type="string">
      Unique UUID identifier for this approval request.
    </ResponseField>

    <ResponseField name="agent_name" type="string">
      Name of the agent that made the request.
    </ResponseField>

    <ResponseField name="service_id" type="number">
      ID of the service being accessed.
    </ResponseField>

    <ResponseField name="method" type="string">
      HTTP method of the request (GET, POST, PUT, DELETE, etc.).
    </ResponseField>

    <ResponseField name="target_url" type="string">
      Full URL the agent wants to access.
    </ResponseField>

    <ResponseField name="intent" type="string">
      Agent's stated intent for this action (max 500 characters).
    </ResponseField>

    <ResponseField name="risk_score" type="number">
      Risk score from 0-1. Higher values indicate greater risk.
    </ResponseField>

    <ResponseField name="risk_explanation" type="string">
      Explanation of why this action was flagged as risky.
    </ResponseField>

    <ResponseField name="request_headers" type="object">
      HTTP headers from the request (auth headers stripped).
    </ResponseField>

    <ResponseField name="request_body" type="string">
      Request body content. May be null.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp when the approval request was created.
    </ResponseField>
  </Expandable>
</ResponseField>

### Status codes

* `200` - Approvals retrieved successfully
* `401` - Unauthorized (missing or invalid token)
* `500` - Internal server error

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.gaiterguard.com/approvals/pending \
    --header 'Authorization: Bearer <jwt>'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gaiterguard.com/approvals/pending', {
    headers: {
      'Authorization': 'Bearer <jwt>'
    }
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.gaiterguard.com/approvals/pending',
      headers={'Authorization': 'Bearer <jwt>'}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "approvals": [
      {
        "action_id": "550e8400-e29b-41d4-a716-446655440000",
        "agent_name": "Production Agent",
        "service_id": 1,
        "method": "DELETE",
        "target_url": "https://api.github.com/repos/user/repo",
        "intent": "Delete repository as requested by user",
        "risk_score": 0.85,
        "risk_explanation": "Destructive action: DELETE request to repository endpoint",
        "request_headers": {
          "Content-Type": "application/json",
          "User-Agent": "GaiterGuard/1.0"
        },
        "request_body": null,
        "created_at": "2026-03-03T22:49:00.000Z"
      }
    ]
  }
  ```
</ResponseExample>

***

## Approve action

<api>PATCH /approvals/:actionId/approve</api>

Approve a pending approval request, allowing the agent to execute the action.

<Info>Approved actions have a limited time window for execution based on the `APPROVAL_EXECUTE_TTL_HOURS` configuration.</Info>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <jwt>`
</ParamField>

### Path parameters

<ParamField path="actionId" type="string" required>
  The UUID action identifier from the approval request.
</ParamField>

### Response

<ResponseField name="status" type="string">
  Approval status. Will be "APPROVED".
</ResponseField>

<ResponseField name="action_id" type="string">
  The UUID action identifier.
</ResponseField>

### Status codes

* `200` - Action approved successfully
* `401` - Unauthorized (missing or invalid token)
* `404` - Action not found or does not belong to user
* `409` - Action already resolved (approved, denied, or expired)
* `500` - Internal server error

<RequestExample>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url https://api.gaiterguard.com/approvals/550e8400-e29b-41d4-a716-446655440000/approve \
    --header 'Authorization: Bearer <jwt>'
  ```

  ```javascript JavaScript theme={null}
  const actionId = '550e8400-e29b-41d4-a716-446655440000';
  const response = await fetch(`https://api.gaiterguard.com/approvals/${actionId}/approve`, {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer <jwt>'
    }
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  action_id = '550e8400-e29b-41d4-a716-446655440000'
  response = requests.patch(
      f'https://api.gaiterguard.com/approvals/{action_id}/approve',
      headers={'Authorization': 'Bearer <jwt>'}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": "APPROVED",
    "action_id": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Action not found"
  }
  ```

  ```json 409 theme={null}
  {
    "error": "Action already resolved"
  }
  ```
</ResponseExample>

***

## Deny action

<api>PATCH /approvals/:actionId/deny</api>

Deny a pending approval request, preventing the agent from executing the action.

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <jwt>`
</ParamField>

### Path parameters

<ParamField path="actionId" type="string" required>
  The UUID action identifier from the approval request.
</ParamField>

### Response

<ResponseField name="status" type="string">
  Approval status. Will be "DENIED".
</ResponseField>

<ResponseField name="action_id" type="string">
  The UUID action identifier.
</ResponseField>

### Status codes

* `200` - Action denied successfully
* `401` - Unauthorized (missing or invalid token)
* `404` - Action not found or does not belong to user
* `409` - Action already resolved (approved, denied, or expired)
* `500` - Internal server error

<RequestExample>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url https://api.gaiterguard.com/approvals/550e8400-e29b-41d4-a716-446655440000/deny \
    --header 'Authorization: Bearer <jwt>'
  ```

  ```javascript JavaScript theme={null}
  const actionId = '550e8400-e29b-41d4-a716-446655440000';
  const response = await fetch(`https://api.gaiterguard.com/approvals/${actionId}/deny`, {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer <jwt>'
    }
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  action_id = '550e8400-e29b-41d4-a716-446655440000'
  response = requests.patch(
      f'https://api.gaiterguard.com/approvals/{action_id}/deny',
      headers={'Authorization': 'Bearer <jwt>'}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": "DENIED",
    "action_id": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Action not found"
  }
  ```

  ```json 409 theme={null}
  {
    "error": "Action already resolved"
  }
  ```
</ResponseExample>