Gate Agent API Reference

Endpoint overview

1. Resolve tool contracts

Resolve registered tool contracts so the runtime can reason over the same names, descriptions, and input schemas configured in Gate.

{
  "tools": ["issue_refund", "send_email"]
}

{
  "tools": [
    {
      "name": "issue_refund",
      "description": "Issue a customer refund",
      "input_schema": {
        "type": "object",
        "required": ["amount"],
        "properties": {"amount": {"type": "number"}}
      }
    }
  ],
  "unregistered": ["send_email"]
}

The request body is limited to 16 KiB, unknown top-level fields are rejected, and the body must contain exactly one JSON object. A body over the current 16 KiB cap surfaces as HTTP 400.

2. Log an event

Append evidence to a runtime task. Ordinary event names are open-ended. The revision. prefix is the one namespace that changes request handling.

{
  "event_type": "tool.execution.completed",
  "event_summary": "Refund executed",
  "payload": {"provider_id": "rf_123"}
}

Success is 201 Created with no JSON body.

Event contract

Processed lifecycle names

Recommended runtime conventions

task.request.loaded, task.input.loaded, task.sop.loaded, task.tools.available, tool.execution.completed, and tool.execution.failed.

Gate-generated names

approval.requested, decision.allow, decision.reject, decision.approved, decision.rejected, task.summary, token_issued, token_consumed, and token_rejected.

3. Request a decision

Evaluate the exact tool call the runtime is about to execute. tool_name is the only required field.

{
  "tool_name": "issue_refund",
  "payload": {
    "amount": 389.99,
    "currency": "usd"
  }
}

An unregistered tool request is still gateable. Gate routes it to human review with an unregistered-tool reason.

Responses

{
  "status": "pending_review",
  "thread_id": "THR-A1B2C3D4",
  "task_id": "order-1042",
  "message": "Rule matched: amount upper_limit",
  "recommended_poll_after_seconds": 15
}

4. Get one decision

Statuses to handle

pending_review, changes_requested, approved, and rejected.

{
  "status": "changes_requested",
  "thread_id": "THR-A1B2C3D4",
  "task_id": "order-1042",
  "message": "Reduce the amount and resubmit",
  "modification": {
    "requested_changes": "Reduce the amount and resubmit",
    "requested_at": "2026-08-09T17:00:00Z"
  },
  "recommended_poll_after_seconds": 3
}

5. List decisions

{
  "decisions": [
    {
      "thread_id": "THR-A1B2C3D4",
      "task_id": "order-1042",
      "status": "approved",
      "updated_at": "2026-08-09T17:00:00Z"
    }
  ]
}

This endpoint is token-safe discovery. Listing a completed decision does not reveal or consume the one-time signed approval token. Fetch the exact decision by thread_id when the runtime is ready to continue.

6. Validate a signed approval

{ "valid": true }

{
  "valid": false,
  "reason": "invalid"
}

Failure reasons include invalid, expired, and used. Tokens are single-use, expiry-bound, agent/context-bound, and invalidated by agent API-key rotation.

Requested changes and revisions

When a reviewer requests changes, polling returns changes_requested. Keep the same review thread and POST a guarded revision event.

{
  "event_type": "revision.order-1042.THR-A1B2C3D4",
  "event_summary": "Revised after reviewer feedback",
  "payload": {
    "revision": {
      "revision_id": "rev-002",
      "tool_name": "issue_refund",
      "subject": "Review issue_refund",
      "request_payload": {"amount": 250}
    }
  }
}

A revision is accepted only for the same agent, task, and thread while the thread is pending, and only after reviewer change-request feedback newer than the latest proposal. Duplicate, stale, or no-longer-pending revisions return 409. A revision that passes policy remains pending for reviewer confirmation; a revision that evaluates to reject may terminate as rejected.

Decision webhooks

When webhook delivery is configured, Gate POSTs completed human decisions to the configured HTTPS endpoint.

{
  "thread_id": "THR-A1B2C3D4",
  "task_id": "order-1042",
  "decision": "approved",
  "message": "Approved",
  "tenant_id": "tenant-uuid",
  "workflow_name": "Customer Support",
  "task_label": "Refund review"
}

Verify the signature

X-Guard-Signature: sha256=<hex-hmac>

HMAC-SHA256(webhook_secret, exact_raw_request_body)

Gate attempts delivery immediately, then retries after 1 second and 3 seconds. Any HTTP status below 300 is treated as success. Webhook destinations must use HTTPS; localhost, loopback, common private ranges, link-local destinations, and unsafe redirect targets are rejected.

Identifiers

There is no live 36-character task-ID contract on this API surface. Avoid path-breaking characters such as /, ?, and #.

Operational limits

HTTP errors

Most Agent API errors are plain HTTP error text rather than a universal JSON envelope. Preserve the response body for diagnostics. The signed approval validation endpoint is the important exception: inspect its JSON valid field even when HTTP is 200.