Gate Agent API Reference

Base URL and authentication

Every agent API request uses the same base URL and authorization pattern.

export STACKSONA_GATE_URL="https://{gate-id}.stacksona.cloud"
export STACKSONA_API_KEY="sg_your_agent_key"

Authorization: Bearer sg_your_agent_key
Content-Type: application/json

API keys are shown only once at creation and are hashed before storage. If a key is lost, regenerate it from Admin → Agents → Regenerate key.

Endpoint overview

1. Log an event

Use events to give reviewers context throughout the task lifecycle.

curl -X POST "$STACKSONA_GATE_URL/api/agent/tasks/task-abc-123/events" \
  -H "Authorization: Bearer $STACKSONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "task.started",
    "event_summary": "Customer requested refund for order #8821",
    "payload": {
      "customer_id": "cus_99",
      "order_id": "ord_8821"
    },
    "images": ["data:image/png;base64,iVBORw0KG..."]
  }'

Revision events

Use revision events when a reviewer asks the agent to change a pending request before approval. The agent sends another event to the same pending review thread with the updated request payload.

{
  "event_type": "revision.task-abc-123.THR-XXXXXXXX",
  "event_summary": "Agent revised the request after reviewer feedback.",
  "payload": {
    "revision": {
      "revision_id": "rev-002",
      "workflow_name": "Customer Support",
      "task_label": "Refund request - Order #8821",
      "tool_name": "issue_refund",
      "subject": "Approve conditional refund for customer cus_99",
      "preview": "Refund releases only after the prepaid return label is scanned.",
      "risk_level": "high",
      "summary": [
        "Reviewer requested a conditional refund",
        "Agent revised the proposal to wait for return-label scan"
      ],
      "request_payload": {
        "amount": 500,
        "currency": "usd",
        "release_condition": "return_label_scanned"
      }
    }
  }
}

The revision payload should include a stable revision_id, the updated request fields, and the revised tool payload that Gate should evaluate through the standard decision rules. Each new revision supersedes the earlier pending revision on that thread.

2. Request a decision

Use this endpoint at the action point. Gate evaluates the request against tool rules and either auto-decides or creates a review thread.

Response fields

3. Poll for a decision

Use polling for short review loops or as a fallback when webhooks fail.

curl "$STACKSONA_GATE_URL/api/agent/decisions?thread_id=THR-4F2A9C1B" \
  -H "Authorization: Bearer $STACKSONA_API_KEY"

Polling response

4. Validate a signed approval token

Use this endpoint when signed approval tokens are enabled for an agent. Do not execute the gated tool until server-side validation succeeds.

curl -X POST "$STACKSONA_GATE_URL/api/agent/approvals/validate" \
  -H "Authorization: Bearer $STACKSONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "task-abc-123",
    "signature": "APPROVAL_TOKEN"
  }'

Signed approval tokens

When signed approval tokens are enabled in Admin → Agents, every approved decision includes a single-use token. Your agent sends that token back to Gate for validation before executing the gated tool.

Decision flow and statuses

Decision action priority is allow < review < escalate < reject. Configure higher-risk rules above broad allow rules so sensitive actions do not pass unintentionally.

Tool rules

Rules auto-decide based on parameters in the request payload. If no rule matches, the tool's default action applies.

1. 1
   Create or open a tool.

   Go to Admin → Tools, then select the tool that maps to the agent action.

2. 2
   Add a rule.

   Select the rule type, parameter, threshold or pattern, and action.

3. 3
   Match payload keys exactly.

   The rule parameter must match a key in the request payload, such as amount, email, or reason.

Webhooks

Configure a webhook URL per agent in Admin → Agents → Update transport. Gate posts to that URL when a reviewer decides.

{
  "thread_id": "THR-4F2A9C1B",
  "task_id": "task-abc-123",
  "decision": "approved",
  "message": "Approved. Verified with customer history.",
  "tenant_id": "<your-tenant-uuid>",
  "workflow_name": "Customer Support",
  "task_label": "Refund request - Order #8821"
}

Response object fields

Errors

Most errors are returned as plain text. Token validation errors from POST /api/agent/approvals/validate are returned as JSON, for example {"valid": false, "reason": "invalid"}. Always check the HTTP status code first.