Edge Gateway API Reference

Authentication

All requests to the Edge Gateway require a Bearer token in the Authorization header:

Authorization: Bearer <TOKEN>

• AGENT_TOKEN: Required for /v1/execute and /v1/budget.
• ADMIN_TOKEN: Required for /v1/admin/control, /v1/admin/pending, and /v1/reconcile.

---

1. Execute Task (POST /v1/execute)

Dispatches an AI task through the spend firewall with pre-flight reservation.

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer <AGENT_TOKEN>
Idempotency-Key	string	Yes	Unique task identifier (prevents duplicate execution)
X-Agent-Tool	string	Yes	Tool name (openai-chat, openai-embeddings, contract)

Request Body

{
  "input": {
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "Analyze risk metrics." }
    ]
  },
  "acceptance": "json-object"
}

Response (200 OK)

{
  "id": "task-req-12345",
  "state": "COMPLETED",
  "accepted": true,
  "costMicros": 1250,
  "data": { ... }
}

---

2. Get Budget Snapshot (GET /v1/budget)

Retrieves real-time spending and reservation metrics from the edge ledger.

Response (200 OK)

{
  "limitMicros": 50000000,
  "spentMicros": 12450000,
  "reservedMicros": 1000000,
  "frozen": false,
  "paused": false,
  "revision": 3
}

---

3. Administrative Control (POST /v1/admin/control)

Performs administrative commands: topUp, pause, resume, or unfreeze.

Request Body (topUp)

{
  "id": "cmd-topup-001",
  "expectedRevision": 3,
  "action": "topUp",
  "deltaMicros": 10000000,
  "evidence": {
    "reference": "INCIDENT-402",
    "note": "Operator authorized additional $10.00."
  }
}