GET /status/:actionId

Poll for approval status of a risk-blocked request

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

Poll Status

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

{
  "status": "PENDING",
  "action_id": "act_7f8e9d0c1b2a3456",
  "created_at": "2026-03-03T14:30:00.000Z"
}

{
  "status": "APPROVED",
  "action_id": "act_7f8e9d0c1b2a3456",
  "execute_url": "/proxy/execute/act_7f8e9d0c1b2a3456"
}

{
  "status": "DENIED",
  "action_id": "act_7f8e9d0c1b2a3456",
  "resolved_at": "2026-03-03T14:45:00.000Z"
}

{
  "status": "EXPIRED",
  "action_id": "act_7f8e9d0c1b2a3456"
}

{
  "status": "EXECUTED",
  "action_id": "act_7f8e9d0c1b2a3456",
  "result": {
    "status": 201,
    "headers": {
      "Content-Type": "application/json",
      "X-GitHub-Request-Id": "abc123"
    },
    "body": "{\"id\": 123, \"title\": \"Bug report\", \"state\": \"open\"}"
  }
}

{
  "error": "Action not found"
}

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