Approvals

Manage approval requests for high-risk agent actions

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

List pending approvals

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

Headers

Authorization · string · required

Bearer token for authentication. Format: Bearer <jwt>

Response

approvals · object[]

Show properties

action_id · string

Unique UUID identifier for this approval request.

agent_name · string

Name of the agent that made the request.

service_id · number

ID of the service being accessed.

method · string

HTTP method of the request (GET, POST, PUT, DELETE, etc.).

target_url · string

Full URL the agent wants to access.

intent · string

Agent’s stated intent for this action (max 500 characters).

risk_score · number

Risk score from 0-1. Higher values indicate greater risk.

risk_explanation · string

Explanation of why this action was flagged as risky.

request_headers · object

HTTP headers from the request (auth headers stripped).

request_body · string

Request body content. May be null.

created_at · string

ISO 8601 timestamp when the approval request was created.

Status codes

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

cURL

curl --request GET \
  --url https://api.gaiterguard.com/approvals/pending \
  --header 'Authorization: Bearer <jwt>'

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

import requests

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

200

{
  "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"
    }
  ]
}

---

Approve action

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

Approved actions have a limited time window for execution based on the APPROVAL_EXECUTE_TTL_HOURS configuration.

Headers

Authorization · string · required

Bearer token for authentication. Format: Bearer <jwt>

Path parameters

actionId · string · required

The UUID action identifier from the approval request.

Response

status · string

Approval status. Will be “APPROVED”.

action_id · string

The UUID action identifier.

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

cURL

curl --request PATCH \
  --url https://api.gaiterguard.com/approvals/550e8400-e29b-41d4-a716-446655440000/approve \
  --header 'Authorization: Bearer <jwt>'

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();

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()

200

{
  "status": "APPROVED",
  "action_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "error": "Action not found"
}

{
  "error": "Action already resolved"
}

---

Deny action

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

Headers

Authorization · string · required

Bearer token for authentication. Format: Bearer <jwt>

Path parameters

actionId · string · required

The UUID action identifier from the approval request.

Response

status · string

Approval status. Will be “DENIED”.

action_id · string

The UUID action identifier.

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

cURL

curl --request PATCH \
  --url https://api.gaiterguard.com/approvals/550e8400-e29b-41d4-a716-446655440000/deny \
  --header 'Authorization: Bearer <jwt>'

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();

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()

200

{
  "status": "DENIED",
  "action_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "error": "Action not found"
}

{
  "error": "Action already resolved"
}