API reference

Try it

One request, one human. Your API key is shown in Settings → API key — the full value is visible once, when you create or rotate it, so copy it then. Pick an approver who has confirmed their phone, and run:

# 1. Settings → API key shows your key (apk_live_…; the full value is visible once, when you create or rotate it).
# 2. Approvers → copy the id (a UUID) of someone who has confirmed their phone.
export APPROV_API_BASE="https://<project>.supabase.co/functions/v1/approvals"
export APPROV_KEY="apk_live_…"

curl -X POST "$APPROV_API_BASE/" \
  -H "Authorization: Bearer $APPROV_KEY" \
  -H "Idempotency-Key: hello-1" \
  -H "Content-Type: application/json" \
  -d '{ "approver_id": "bb07d4a7-22f6-4188-a139-66f16dc2b6e8", "action": "Hello from the API docs" }'

# → { "id": "ff5bb3be-73ea-4cc6-92ae-fd1cc606bd2f", "status": "pending", "expires_at": "…", "replayed": false }
# Their phone buzzes within seconds. Reply there, then read the decision with GET /:id.

Quickstart

Two calls. Create an approval — AI Approvel messages your approver on WhatsApp or SMS and returns immediately with an id — then poll that id (or receive a webhook) to learn the decision, and only then run the risky step.

1. Create

curl -X POST "$APPROV_API_BASE/" \
  -H "Authorization: Bearer $APPROV_KEY" \
  -H "Idempotency-Key: refund-8831" \
  -H "Content-Type: application/json" \
  -d '{
    "approver_id": "bb07d4a7-22f6-4188-a139-66f16dc2b6e8",
    "action": "Refund $4,200 to customer #8831",
    "amount": 4200,
    "currency": "USD",
    "context": { "ticket": "ZD-4411" },
    "timeout_seconds": 1800
  }'

HTTP/1.1 202 Accepted

{
  "id": "ff5bb3be-73ea-4cc6-92ae-fd1cc606bd2f",
  "status": "pending",
  "expires_at": "2026-10-01T12:30:02.000Z",
  "replayed": false
}

2. Poll

# every few seconds, until status is
# decided, expired or failed
curl "$APPROV_API_BASE/ff5bb3be-73ea-4cc6-92ae-fd1cc606bd2f" \
  -H "Authorization: Bearer $APPROV_KEY"

HTTP/1.1 200 OK

{
  "id": "ff5bb3be-73ea-4cc6-92ae-fd1cc606bd2f",
  "status": "decided",
  "decision": {
    "outcome": "approved",
    "decided_via": "whatsapp_button",
    "decided_by": "+14155550101",
    "decided_at": "2026-10-01T12:04:11.000Z"
  },
  "…": "…"
}

decision is null until the approver replies; branch on decision.outcome (approved | rejected). Ready-made versions of this loop for your framework are under Recipes.

Authentication

Send your project API key as a Bearer token on every request. Create and rotate keys in Settings. Keys look like apk_live_<8 hex>_<secret>; the part before the second underscore (apk_live_1a2b3c4d) is a non-secret identifier the dashboard shows so you can tell keys apart, everything after it is the secret. The full key is shown once; keep it server-side and never ship it in a browser or app bundle. A missing, malformed, rotated or unknown key returns 401 unauthorized.

Authorization: Bearer apk_live_1a2b3c4d_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create an approval

Returns 202 with an id while delivery happens in the background. Send an Idempotency-Key header so a retry can never ask twice — see Idempotency. The body is validated strictly: unknown fields are rejected with 400 validation_error and details.fieldErrors names the offenders. Only approvers who have confirmed their phone number (opted in) can receive requests; otherwise you get 400 validation_error with details.approver_id.

POST /
Idempotency-Key: refund-8831-attempt-1

{
  "approver_id": "bb07d4a7-22f6-4188-a139-66f16dc2b6e8",
  "action": "Refund $4,200 to customer #8831",
  "amount": 4200,
  "currency": "USD",
  "context": { "ticket": "ZD-4411", "source": "support-agent" },
  "params_hash": "c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00",
  "callback_url": "https://agent.example.com/hooks/approv",
  "locale": "en",
  "timeout_seconds": 1800,
  "metadata": { "run_id": "run_42" }
}

HTTP/1.1 202 Accepted

{
  "id": "ff5bb3be-73ea-4cc6-92ae-fd1cc606bd2f",
  "status": "pending",
  "expires_at": "2026-10-01T12:30:02.000Z",
  "replayed": false
}

# Same Idempotency-Key again → the same body
# with "replayed": true. Nobody is messaged twice.

List approvals

Returns { count, approvals, next_cursor, has_more }— the project's approvals, newest first, as summary rows with the decision included ({ outcome, decided_at, decided_via } or null; fetch GET /:id for decided_by, params_hash and locale). Filtering and paging happen server-side. Reads are not rate-limited and never count against your quota.

# Decided-and-approved refunds, newest first, 50 per page
curl "$APPROV_API_BASE/?status=approved&q=refund&limit=50" \
  -H "Authorization: Bearer $APPROV_KEY"

# Next page: pass next_cursor back as ?cursor= (same filters)
curl "$APPROV_API_BASE/?status=approved&q=refund&cursor=WyIyMDI2LTEwLTAxVDEyOjAwOjAyLjAwMFoiLCJmZjViYjNiZS0uLi4iXQ" \
  -H "Authorization: Bearer $APPROV_KEY"

{
  "count": 2,
  "approvals": [
    {
      "id": "ff5bb3be-73ea-4cc6-92ae-fd1cc606bd2f",
      "status": "decided",
      "action": "Refund $4,200 to customer #8831",
      "amount": 4200,
      "currency": "USD",
      "channel_used": "whatsapp",
      "created_at": "2026-10-01T12:00:02.000Z",
      "expires_at": "2026-10-01T12:30:02.000Z",
      "decision": { "outcome": "approved", "decided_at": "2026-10-01T12:04:11.000Z", "decided_via": "whatsapp_button" }
    },
    {
      "id": "3c0d55a9-e7f1-4b2a-9d6e-0f1a2b3c4d5e",
      "status": "decided",
      "action": "Refund $180 to customer #8714",
      "amount": 180,
      "currency": "USD",
      "channel_used": "sms",
      "created_at": "2026-09-30T09:10:41.000Z",
      "expires_at": "2026-09-30T10:10:41.000Z",
      "decision": { "outcome": "approved", "decided_at": "2026-09-30T09:12:03.000Z", "decided_via": "sms_reply" }
    }
  ],
  "next_cursor": "WyIyMDI2LTA5LTMwVDA5OjEwOjQxLjAwMFoiLCIzYzBkNTVhOS0uLi4iXQ",
  "has_more": true
}

# "decision" is null until the approver replies.
# Keep calling with ?cursor=next_cursor until
# has_more is false (next_cursor is then null).

The dashboard's Approvals page uses exactly these parameters: the status segments map to status (Approved / Rejected to the outcome aliases), the search box to q, and “Load more” follows next_cursor. Only the date presets are applied in the browser. See Status lifecycle for what each status means.

Get status

Poll for the decision. decision is null until the approver replies. Polling every few seconds is fine; the dashboard polls every 2.5s. Stop polling once status is terminal (decided, expired or failed).

curl "$APPROV_API_BASE/ff5bb3be-73ea-4cc6-92ae-fd1cc606bd2f" \
  -H "Authorization: Bearer $APPROV_KEY"

# While the approver has not replied:
# { "status": "delivered", "decision": null, … }

# decided_via is one of whatsapp_button,
# whatsapp_text, sms_reply, web_link, console, api.
# channel_used is whatsapp, sms or console.

{
  "id": "ff5bb3be-73ea-4cc6-92ae-fd1cc606bd2f",
  "status": "decided",
  "action": "Refund $4,200 to customer #8831",
  "amount": 4200,
  "currency": "USD",
  "params_hash": "c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00",
  "channel_used": "whatsapp",
  "locale": "en",
  "expires_at": "2026-10-01T12:30:02.000Z",
  "created_at": "2026-10-01T12:00:02.000Z",
  "updated_at": "2026-10-01T12:04:11.000Z",
  "decision": {
    "outcome": "approved",
    "decided_via": "whatsapp_button",
    "decided_by": "+14155550101",
    "decided_at": "2026-10-01T12:04:11.000Z"
  }
}

Status lifecycle

Every approval walks the same small state machine. status tells you where it is; decision is only ever set in decided. The same transitions appear as events in the audit trail.

Get audit trail

Every state change is hash-chained and signed with Ed25519. The response includes the public key and the exact formula so anyone can verify it independently — you don't have to trust us.

curl "$APPROV_API_BASE/ff5bb3be-73ea-4cc6-92ae-fd1cc606bd2f/audit" \
  -H "Authorization: Bearer $APPROV_KEY"

# Event types: approval.requested, message.queued,
# message.sent, message.failed, approval.decided,
# approval.expired, webhook.delivered, webhook.failed

{
  "approval_request_id": "ff5bb3be-73ea-4cc6-92ae-fd1cc606bd2f",
  "algorithm": {
    "hash": "sha256",
    "signature": "ed25519",
    "hash_formula": "sha256( prev_hash | event_type | canonical_json(payload) | created_at )",
    "field_separator": "U+241F (␟)"
  },
  "public_key": { "key_id": "approv-2026-10", "format": "spki-der-base64", "key": "MCowBQYDK2VwAyEA…" },
  "verification": { "valid": true, "event_count": 4, "issues": [] },
  "events": [
    { "seq": 0, "event_type": "approval.requested", "payload": { "action": "Refund $4,200 to customer #8831", "amount": 4200, "…": "…" },
      "prev_hash": "0000…0000", "hash": "d58c…", "signature": "r4Rx…", "public_key_id": "approv-2026-10", "created_at": "2026-10-01T12:00:02.103Z" },
    { "seq": 1, "event_type": "message.sent",       "payload": { "channel": "whatsapp", "provider": "meta", "attemptNo": 1, "…": "…" },
      "prev_hash": "d58c…", "hash": "8d35…", "signature": "2ow5…", "public_key_id": "approv-2026-10", "created_at": "2026-10-01T12:00:04.418Z" },
    { "seq": 2, "event_type": "approval.decided",   "payload": { "outcome": "approved", "decidedVia": "whatsapp_button", "…": "…" },
      "prev_hash": "8d35…", "hash": "5172…", "signature": "5oM1…", "public_key_id": "approv-2026-10", "created_at": "2026-10-01T12:04:11.007Z" },
    { "seq": 3, "event_type": "webhook.delivered",  "payload": { "callbackUrl": "https://agent.example.com/hooks/approv", "statusCode": 200, "outcome": "approved" },
      "prev_hash": "5172…", "hash": "80f4…", "signature": "v85N…", "public_key_id": "approv-2026-10", "created_at": "2026-10-01T12:04:12.250Z" }
  ]
}

Verify the audit trail

Each event is signed with Ed25519 and hash-chained. You don't have to trust us — recompute it with the public key in the response. Three checks, in order:

1. Chain: seq runs from 0 and every event's prev_hash equals the previous event's hash; the first event chains to the genesis hash, 64 zeros.
2. Hash: recompute hash with algorithm.hash_formula — sha256( prev_hash | event_type | canonical_json(payload) | created_at ). The | is notation: the four strings are joined with algorithm.field_separator, the single character U+241F (␟, SYMBOL FOR UNIT SEPARATOR), which cannot occur in JSON or a timestamp. canonical_json is JSON with keys sorted recursively and no whitespace ({} when there is no payload); the digest is lowercase hex over the UTF-8 bytes.
3. Signature: signature is base64 Ed25519 over the UTF-8 bytes of the hex hash string (not the raw 32-byte digest). Verify it with public_key.key (spki-der-base64) and pin the key by public_key.key_id (also on every event as public_key_id) so a rotated key can't silently re-sign history.

import { createHash, createPublicKey, verify } from "node:crypto";

const BASE = process.env.APPROV_API_BASE; // https://<project>.supabase.co/functions/v1/approvals
const res = await fetch(`${BASE}/${approvalId}/audit`, {
  headers: { Authorization: `Bearer ${process.env.APPROV_KEY}` },
});
const trail = await res.json();

// JSON with sorted keys and no whitespace, recursively.
const canonicalJson = (v) =>
  v && typeof v === "object" && !Array.isArray(v)
    ? "{" + Object.keys(v).sort().map((k) => JSON.stringify(k) + ":" + canonicalJson(v[k])).join(",") + "}"
    : Array.isArray(v) ? "[" + v.map(canonicalJson).join(",") + "]" : JSON.stringify(v);

// 1. Load the Ed25519 public key (public_key.format === "spki-der-base64").
const publicKey = createPublicKey({
  key: Buffer.from(trail.public_key.key, "base64"),
  format: "der",
  type: "spki",
});

// 2. Walk the chain. trail.algorithm.hash_formula is the source of truth:
//    sha256( prev_hash | event_type | canonical_json(payload) | created_at )
//    where "|" means "joined with algorithm.field_separator" = U+241F (␟),
//    and seq 0 chains to the genesis hash (64 zeros).
const SEP = "\u241F";
let prev = "0".repeat(64);
for (const ev of trail.events) {
  if (ev.prev_hash !== prev) throw new Error(`chain broken at seq ${ev.seq}`);

  const recomputed = createHash("sha256")
    .update([ev.prev_hash, ev.event_type, canonicalJson(ev.payload ?? {}), ev.created_at].join(SEP), "utf8")
    .digest("hex");
  if (recomputed !== ev.hash) throw new Error(`hash mismatch at seq ${ev.seq}`);

  // 3. The signature is base64 Ed25519 over the UTF-8 bytes of the hex hash string.
  const ok = verify(null, Buffer.from(ev.hash, "utf8"), publicKey, Buffer.from(ev.signature, "base64"));
  if (!ok) throw new Error(`bad signature at seq ${ev.seq}`);

  prev = ev.hash;
}
console.log(`verified ${trail.events.length} events with key ${trail.public_key.key_id}`);

The hash_formula and field_separator strings returned by the API are authoritative; if they ever change, follow the response rather than this page. Download the JSON from the Audit drawer in the dashboard to keep a copy that verifies without us — Verify offline has a ready-made script for it.

Verify offline

A dependency-free script runs the three checks above on the file the dashboard's Download trail button saves — the exact body of GET /:id/audit. Node 18 or newer, nothing to install, no network: it never talks to AI Approvel.

# 1. Dashboard → open the approval → Audit → "Download trail"
#    (saves ai-approvel-audit-<id>.json — the exact body of GET /:id/audit)
# 2. Fetch the verifier once. Plain Node 18+, nothing to npm install.
curl -fsSLO https://ai-approvel.com/verify-audit.mjs

# 3. Verify
node verify-audit.mjs ai-approvel-audit-ff5bb3be-73ea-4cc6-92ae-fd1cc606bd2f.json

✓ 4 events verified in ai-approvel-audit-ff5bb3be….json · sha256 chain + ed25519 signatures · key approv-2026-10
  formula  sha256( prev_hash | event_type | canonical_json(payload) | created_at )
  fields   prev_hash ␟ event_type ␟ canonical_json(payload) ␟ created_at  (joined with U+241F (␟); prev_hash of seq 0 is 64 zeros; payload {} when absent)
  signing  base64 ed25519 over the utf-8 bytes of the hex hash
$ echo $?
0

✗ 3 problems in ai-approvel-audit-ff5bb3be….json · 4 events · key approv-2026-10
  seq 2     hash      recomputed 9d42c0a1b7e3… ≠ stored 51728ba464f7…
  seq 2     signature signature 5oM1pTMpN+ao… does not verify with key approv-2026-10
  seq 3     chain     prev_hash 51728ba464f7… ≠ hash of seq 2 (9d42c0a1b7e3…)
  formula  sha256( prev_hash | event_type | canonical_json(payload) | created_at )
  fields   prev_hash ␟ event_type ␟ canonical_json(payload) ␟ created_at  (…)
  signing  base64 ed25519 over the utf-8 bytes of the hex hash
  warning  the server marked this trail valid when it was downloaded; it does not verify now — the file was altered after download, or the key/formula changed
$ echo $?
1

Exit code 0 means every check passed; 1 lists each failing event by seq and check (chain, hash or signature); 2is a usage error or unreadable file — so it drops straight into CI or a nightly job. The report always prints the formula, the separator and how the signature was checked, so if the API's hash_formula or field_separatorever changes you see the mismatch instead of guessing. The script is tested against a trail produced by the backend's own audit engine.

node verify-audit.mjs trail.json --key-id approv-2026-10   # fail unless it was signed by the key you pinned
node verify-audit.mjs trail.json --json        # machine-readable result, e.g. for CI
NO_COLOR=1 node verify-audit.mjs trail.json    # or --no-color, for logs
cat trail.json | node verify-audit.mjs -       # read from stdin

# Or import it from your own tooling:
import { verifyTrail } from "./verify-audit.mjs";
const { valid, failures } = verifyTrail(JSON.parse(await readFile("trail.json", "utf8")));

Webhooks

Pass a callback_url when creating an approval. On decision, AI Approvel sends a signed POST so your agent can continue automatically — no polling required. The URL must be https:// and resolve to a public host; private, loopback and cloud-metadata addresses are rejected.

POST <your callback_url>
Content-Type: application/json
X-Approv-Event: approval.decided
X-Approv-Timestamp: 1790251451
X-Approv-Signature: 5f1d3c8e…   # hex HMAC-SHA256 of "<timestamp>.<raw body>"

{
  "id": "ff5bb3be-73ea-4cc6-92ae-fd1cc606bd2f",
  "status": "decided",
  "outcome": "approved",
  "decided_via": "whatsapp_button",
  "decided_at": "2026-10-01T12:04:11.000Z",
  "action": "Refund $4,200 to customer #8831",
  "params_hash": "c0ffee00…",
  "approver_id": "bb07d4a7-22f6-4188-a139-66f16dc2b6e8",
  "amount": 4200,
  "currency": "USD"
}

# Exactly these fields, in this order (you verify
# the raw bytes). params_hash, amount and currency
# are null when not supplied at creation. Fields are
# only ever appended, never changed.

HTTP/1.1 200 OK

# Any 2xx within 10 seconds acknowledges
# the delivery; the body is ignored.
#
# Non-2xx, a redirect or a timeout → retried from
# the queue (about a minute apart, up to 5 tries),
# each attempt recorded as webhook.delivered or
# webhook.failed in the audit trail.

The body carries the decision and what it was about — id, status, outcome, decided_via, decided_at, action, params_hash, approver_id, amount, currency — in a fixed field order, and X-Approv-Event names the event. Respond with any 2xx within 10 seconds. A non-2xx, a redirect or a timeout is retried from the queue (roughly a minute apart, up to five attempts), and every attempt is recorded in the audit trail as webhook.delivered or webhook.failed. Make your handler idempotent on id — a retry can deliver the same decision twice. Compare params_hash with the parameters you are about to act on before you act; GET /:id has the full record if you need more.

Webhook endpoints

Instead of a callback_url on every request, add up to ten endpoints under Webhooks in the dashboard. Every enabled endpoint subscribed to approval.decided receives each decision, signed with its own whsec_… secret (shown once when the endpoint is created, rotatable any time), with the same headers as above plus X-Approv-Delivery: <id>. The Deliveries tab keeps every attempt — request body, response status, error — filterable by endpoint, status and approval, and lets you replay one. The legacy callback_url delivery keeps working and is signed with the project secret.

Verify a webhook

Always verify before acting. The signature is the lowercase hex HMAC-SHA256 of ${timestamp}.${rawBody} using your webhook signing secret. Compute it over the raw request bytes (not a re-serialised object), compare in constant time, and reject anything whose timestamp is more than 300 seconds from your clock. Each project has its own whsec_… signing secret: reveal and copy it under Settings → Webhooks (or GET /account/webhook-secret with your user session — see Dashboard & account endpoints). Rotating it (POST /account/webhook-secret/rotate) takes effect on the very next delivery and the old secret is not honoured in parallel, so deploy the new secret to your verifier first, then rotate.

Node

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 300;

/**
 * rawBody MUST be the exact bytes we sent — read it before any JSON parser
 * touches the request (Express: app.post(path, express.raw({ type: "*/*" }), handler)).
 */
export function verifyApprovWebhook(rawBody, headers, secret) {
  const timestamp = headers["x-approv-timestamp"];
  const signature = headers["x-approv-signature"];
  if (!timestamp || !signature) return false;

  // 1. Reject stale or replayed deliveries.
  const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(ageSeconds) || ageSeconds > TOLERANCE_SECONDS) return false;

  // 2. Recompute hex HMAC-SHA256 over "${timestamp}.${rawBody}".
  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex");

  // 3. Constant-time compare (lengths must match first or timingSafeEqual throws).
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(String(signature), "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

// Usage (Express):
// app.post("/hooks/approv", express.raw({ type: "*/*" }), (req, res) => {
//   if (!verifyApprovWebhook(req.body, req.headers, process.env.APPROV_WEBHOOK_SECRET)) {
//     return res.status(401).end();
//   }
//   const event = JSON.parse(req.body.toString("utf8"));
//   // event.id, event.outcome === "approved" | "rejected"
//   res.status(200).end();
// });

Python

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify_approv_webhook(raw_body: bytes, headers: dict, secret: str) -> bool:
    """raw_body must be the exact request bytes (Flask: request.get_data(); FastAPI: await request.body())."""
    timestamp = headers.get("X-Approv-Timestamp")
    signature = headers.get("X-Approv-Signature")
    if not timestamp or not signature:
        return False

    # 1. Reject stale or replayed deliveries.
    try:
        if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
            return False
    except ValueError:
        return False

    # 2. Recompute hex HMAC-SHA256 over f"{timestamp}.{raw_body}".
    expected = hmac.new(
        secret.encode("utf-8"),
        f"{timestamp}.".encode("utf-8") + raw_body,
        hashlib.sha256,
    ).hexdigest()

    # 3. Constant-time compare.
    return hmac.compare_digest(expected, signature.lower())


# Usage (Flask):
# @app.post("/hooks/approv")
# def approv_hook():
#     if not verify_approv_webhook(request.get_data(), request.headers, os.environ["APPROV_WEBHOOK_SECRET"]):
#         abort(401)
#     event = request.get_json()
#     # event["id"], event["outcome"] in ("approved", "rejected")
#     return "", 200

Idempotency

Send an Idempotency-Key header on every POST / — any string that is unique per approval you intend to create (your job id, for instance). A retry with the same key returns the original approval, still with 202, and "replayed": true. Nothing new is created, the approver is not messaged again, and the replay is not charged against your monthly quota.

POST /
Idempotency-Key: refund-8831-attempt-1
→ 202 { "id": "ff5bb3be-…", "status": "pending",   "replayed": false }

POST /   (same key, say after a network timeout)
Idempotency-Key: refund-8831-attempt-1
→ 202 { "id": "ff5bb3be-…", "status": "delivered", "replayed": true }

• Keys are scoped to your project and never expire; two concurrent requests with the same key resolve to one approval.
• Without the header the server generates a random key, so every request creates a new approval — store the returned id immediately and poll it rather than retrying blind.
• The key is not echoed in responses or the webhook; put your own correlation id in context or metadata if you need it in the audit trail.

Rate limits & quotas

Two separate ceilings: a per-minute rate limit on requests, and a monthly quota on approvals created. Both come back as a stable error code you can branch on.

Rate limit

Each project may create 60 approvals per minute by default (fixed one-minute window, counted on POST / before validation; reads are not limited). Over the limit you get 429 rate_limited with a Retry-After header in seconds — back off for that long (or until the next minute boundary if the header is absent), then retry with the same Idempotency-Key. Need more? Contact us and we'll raise it for your project.

HTTP/1.1 429 Too Many Requests
Retry-After: 17

{ "error": { "code": "rate_limited", "message": "Rate limit of 60 approvals/minute exceeded. Try again in 17s.", "details": null } }

Monthly quota

Your plan includes a number of approvals per calendar month (Free: 100, Growth: 5,000, Scale: unlimited). Creating an approval past the quota returns 402 quota_exceeded with details: { plan, limit, used, period } (period is the UTC month, YYYY-MM). It is a billing condition, not a transient one — there is no Retry-After and retrying will not help; stop and upgrade. Only genuinely new, valid requests count — idempotent replays and rejected bodies do not. Usage resets on the 1st; see it and upgrade under Settings → Plan & billing. Reads (GET) never count against the quota.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly plan limit of 100 approvals reached on the Free plan. Upgrade your plan in the dashboard (Billing) to send more this month.",
    "details": { "plan": "free", "limit": 100, "used": 100, "period": "2026-10" }
  }
}

Errors

Errors return a JSON body with a stable code, a human message and details — the field-level validation errors ({ formErrors, fieldErrors }), { approver_id } for approver problems, otherwise null. Branch on the code, never on the message.

With scoped keys and teams (Phase C) the dashboard routes add 403 forbidden (your role), 403 insufficient_scope (the key lacks approvals:write or approvals:read), 403 invite_mismatch, 410 invite_expired, 409 last_owner and 409 pending_invite — see Team, roles and invites.

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body.",
    "details": { "formErrors": [], "fieldErrors": { "action": ["String must contain at least 1 character(s)"] } }
  }
}

OpenAPI spec

The whole API is described in an OpenAPI 3.1 document at https://ai-approvel.com/openapi.json, including the approval.decided webhook. Use it to generate a client, mock the API in tests, or browse it with any OpenAPI viewer:

npx @redocly/cli preview-docs https://ai-approvel.com/openapi.json

The spec was checked line by line against the backend source, API build 2026-10 included (list filters and cursors, decision on list rows, 402 quota_exceeded, Retry-After, per-project webhook secrets); nothing in it is inferred. The dashboard's account endpoints are summarised in its info.description. For LLMs and coding agents there is also /llms.txt, a plain-text summary with links.

Dashboard & account endpoints

The dashboard talks to a second edge function, /account, authenticated with the signed-in user's Supabase session (Authorization: Bearer <access token>), never with an API key. You will rarely call these yourself, but they explain what the dashboard shows and are listed here so nothing is a black box. Every error follows the same { error: { code, message, details } } shape as the approvals API.

Team, roles and invites

A workspace has owner, admin and member roles. Owners do everything, including billing, transferring ownership and deleting the workspace; admins manage approvers, API keys, webhooks and members (but cannot grant or remove owner); members can view approvals, approvers, stats and usage. Every route checks the role and answers 403 forbiddenotherwise. The dashboard's Team page drives these; invite links are /invite/<token> and work for 7 days, only for the invited address.

Named API keys with scopes

Projects can hold up to 20 active keys, each with a name, a set of scopes and an optional expiry. approvals:write allows POST /; approvals:read allows the three GET routes. A key without the needed scope gets 403 insufficient_scope; an expired or revoked key gets 401. Manage them under API keys.

Approver opt-in page

The invitation link your approver receives points at /optin/<token>; the token is the only credential. GET /optin/:token returns { approver_name, phone_e164, workspace, opted_in, locale }; POST /optin/:token with an optional { "locale": "en" | "ar" } body records consent and stores the language the approver read the page in, so their approval messages arrive in it. Re-posting is idempotent and can change the locale.

SDKs

Official SDKs for TypeScript and Python are in progress and will ship on npm and PyPI. They will expose the same requireApproval({ action, amount }) call as the helper under Recipes, so code written against it today ports with an import change. Until then the API is small enough to call with fetch or requests, or generate a typed client from the spec:

# TypeScript (fetch)
npx @openapitools/openapi-generator-cli generate \
  -i https://ai-approvel.com/openapi.json -g typescript-fetch -o ./approv-client

# Python
npx @openapitools/openapi-generator-cli generate \
  -i https://ai-approvel.com/openapi.json -g python -o ./approv-client