REST API

The SDK is the recommended way to use Eda, but everything it does is a thin wrapper over a plain HTTP API. Use this directly from any language or runtime.

Base URL: https://api.edahq.com
Auth: Authorization: Bearer eda_live_… on every request.
Content type: application/json.

⚠️

Keep your API key server-side. It authenticates as your workspace; anyone with it can create checks and read your audit log.

Authentication

curl https://api.edahq.com/v1/health \
  -H "Authorization: Bearer $EDA_API_KEY"

Errors use standard status codes: 401 (bad/missing key), 402 (quota/payment), 403 (forbidden), 429 (rate limited, with Retry-After), 4xx/5xx otherwise. Bodies are { "error": { "code", "message" } }.

`POST /v1/check`

Evaluate an action.

curl -X POST https://api.edahq.com/v1/check \
  -H "Authorization: Bearer $EDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "support-agent",
    "action": "refund_customer",
    "params": { "amount": 900, "customerId": "cus_8842" },
    "metadata": { "requestId": "req_123" }
  }'

Response

{
  "actionId": "act_9f2c…",
  "status": "pending",
  "reason": "Refunds over $500 require approval",
  "policy": { "id": "pol_12", "priority": 200, "effect": "require_approval" },
  "risk": null,
  "createdAt": "2026-07-03T12:00:00.000Z"
}

status ∈ approved | blocked | pending | denied.

`GET /v1/actions/:id`

Fetch a single action and its current decision.

curl https://api.edahq.com/v1/actions/act_9f2c \
  -H "Authorization: Bearer $EDA_API_KEY"

`GET /v1/approvals/:id`

Poll the approval state for a pending action (this is what the SDK’s waitForApproval calls under the hood).

{ "actionId": "act_9f2c…", "status": "approved", "approverId": "user_44", "resolvedAt": "2026-07-03T12:03:11.000Z" }

`GET /v1/actions`

List recent actions (audit trail), newest first. Query params: status (approved|blocked|pending|denied), limit (default 15, max 100), cursor (opaque, from a previous response).

curl "https://api.edahq.com/v1/actions?status=blocked&limit=50" \
  -H "Authorization: Bearer $EDA_API_KEY"

{
  "items": [
    { "actionId": "act_…", "agent": "ops", "action": "delete_bucket", "status": "blocked", "reason": "…", "createdAt": "…" }
  ],
  "cursor": "eyJwayI6…"
}

`GET /v1/usage`

Current plan, quota, and AI token usage for the period.

{
  "plan": "team",
  "month": "2026-07",
  "checks": { "used": 18422, "included": 100000, "ratePerMin": 600 },
  "ai": { "inputTokens": 512000, "outputTokens": 88000, "pendingCents": 0 }
}

`GET /v1/health`

Liveness + version. No side effects.

{ "status": "ok", "version": "0.2.0" }

AI integration endpoints

eda init is powered by two metered endpoints — POST /v1/init/analyze and POST /v1/init/apply. They’re intended for the CLI (which handles backups, smoke tests, and consent) and are billed pay-per-token. Prefer eda init over calling these directly.

Rate limits

Limits scale with your plan (checks.ratePerMin in /v1/usage). On 429, respect the Retry-After header; the SDK does this automatically with backoff.

CLI Overview