API Docs

Gateway requests authenticate with an agent API key and return a durable request id plus a signed receipt id after execution.

Gateway Execute

curl -X POST http://localhost:3000/api/v1/gateway/execute \
  -H "Authorization: Bearer agk_sandbox_..." \
  -H "Content-Type: application/json" \
  -d '{"tool":"http","action":"request.post","arguments":{"url":"https://example.com","method":"POST","amount_minor":1000,"currency":"USD"},"idempotency_key":"order-123"}'

TypeScript

await fetch("/api/v1/gateway/execute", {
  method: "POST",
  headers: { authorization: `Bearer ${agentKey}`, "content-type": "application/json" },
  body: JSON.stringify({ tool: "http", action: "request.post", arguments: { amount_minor: 1000, currency: "USD" } })
});

Python

import requests
requests.post(
  "http://localhost:3000/api/v1/gateway/execute",
  headers={"Authorization": f"Bearer {agent_key}"},
  json={"tool":"http","action":"request.post","arguments":{"amount_minor":1000,"currency":"USD"}}
)

Authentication

Register or log in through the dashboard. Internal dashboard APIs require a signed httpOnly session cookie and an x-csrf-token header that matches the csrf cookie.

Agents

Agents are workspace scoped. Active agents can execute, paused agents are blocked, and revoked agents cannot be restored for execution.

API Keys

Create keys from the dashboard or internal API. The plaintext key is returned once; only the hash and prefix are stored.

Policies

Policies are immutable versions. Activating a version deactivates the other versions in the workspace.

Budgets

Policy rules can include amountMinorMax, dailyLimitMinor, and monthlyLimitMinor. Spend is reserved before dispatch and settled, released, or held after outcome.

Approvals

REQUIRE_APPROVAL decisions create pending approvals bound to a request fingerprint. Approved requests consume the approval exactly once.

Idempotency

Pass idempotency_key on every gateway call. Replays return the persisted request status and receipt when one has been signed.

Receipts

Every terminal request signs an AgentReceipt containing request, policy, approval, outcome, and evidence chain hash fields.

Verification

Use GET /api/v1/receipts/{id}/verify or POST payloadJson and signature to verify a detached receipt.

Integrations

HTTP integrations enforce allowlisted hosts, methods, size limits, timeouts, and redirect re-validation. Stripe accepts test-mode keys only.

Security

Secrets are encrypted at rest, redacted from logs, and required in production. Internal mutations are session, role, and CSRF checked.

Errors

INVALID_API_KEY, AGENT_REVOKED, AGENT_PAUSED, POLICY_DENIED, BUDGET_EXCEEDED, APPROVAL_REQUIRED, APPROVAL_EXPIRED, IDEMPOTENCY_CONFLICT, CONNECTOR_ERROR, OUTCOME_UNKNOWN, VALIDATION_ERROR, RATE_LIMITED, INTERNAL_ERROR.