Skip to main content

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.

​
Endpoint

GET /status/:actionId
Agent endpoint to poll the current approval state of a request that was blocked by risk assessment (428 response from POST /proxy).

​
Authentication

Requires Agent-Key header with valid agent API key. 
Agent-Key: your-agent-key-here

​
Path Parameters

​
actionId
string
required
Unique identifier for the approval queue entry. Returned in the action_id field of a 428 Risk-Blocked response.Example: act_7f8e9d0c1b2a3456

​
Response States

The response shape varies based on the current status of the approval queue entry.

​
PENDING

Request is awaiting human approval.
​
status
string
"PENDING"
​
action_id
string
The action identifier
​
created_at
string
ISO 8601 timestamp when the request was created

​
APPROVED

Request has been approved and is ready to execute.
​
status
string
"APPROVED"
​
action_id
string
The action identifier
​
execute_url
string
URL to execute the approved request: /proxy/execute/:actionId

​
DENIED

Request was denied by a human reviewer.
​
status
string
"DENIED"
​
action_id
string
The action identifier
​
resolved_at
string
ISO 8601 timestamp when the request was denied (nullable)

​
EXPIRED

Approval has expired (TTL exceeded before execution).
​
status
string
"EXPIRED"
​
action_id
string
The action identifier

​
EXECUTED

Request has been executed and the result is available.
​
status
string
"EXECUTED"
​
action_id
string
The action identifier
​
result
object
The cached response from the executed request
​
status
number
HTTP status code from the target service
​
headers
object
Response headers from the target service
​
body
string
Response body from the target service

​
Error Responses

​
401 Unauthorized
Invalid or missing Agent-Key header
​
404 Not Found
  • Action not found
  • Action belongs to a different agent (ownership check)
​
500 Internal Server Error
Unknown action status or server error

​
Examples

curl -X GET https://api.gaiterguard.com/status/act_7f8e9d0c1b2a3456 \
  -H "Agent-Key: your-agent-key-here"

​
Polling Strategy

When a request is blocked (428 response), implement a polling loop:
  1. Extract action_id from the 428 response
  2. Poll GET /status/:actionId with exponential backoff
  3. Check the status field:
    • PENDING: Continue polling
    • APPROVED: Call POST /proxy/execute/:actionId to execute
    • DENIED: Handle denial (e.g., log, alert, abort)
    • EXPIRED: Resubmit via POST /proxy if still needed
    • EXECUTED: Use the cached result from the response

​
Ownership Security

The endpoint implements strict ownership checks:
  • Only the agent that created the request can view its status
  • Returns 404 for both “not found” and “wrong agent” cases
  • Prevents information disclosure about other agents’ requests

​
State Transitions

  • PENDING → APPROVED: Human approves the request
  • PENDING → DENIED: Human denies the request
  • PENDING → EXPIRED: Approval TTL expires before decision
  • APPROVED → EXECUTED: Agent calls POST /proxy/execute/:actionId
  • APPROVED → EXPIRED: Execution TTL expires before agent executes

Build docs developers (and LLMs) love

Get started for freeTalk to us