Put the control layer in front of your agent.

import { SevraGuard } from "sevra/guard";

const sevra = new SevraGuard({
  apiKey: process.env.SEVRA_GUARD_KEY!,
  baseUrl: "https://sevra.dev",
});

const decision = await sevra.guard({
  agent: "refund-bot",
  action: "refund",
  target: "order:ord_8231",
  params: { orderId: "ord_8231", amountMinor: 500, currency: "USD" },
  idempotencyKey: "refund:ord_8231",
  amountMinor: 500,
  currency: "USD",
  direction: "out",
});
// decision.verdict is "allow", "require_approval", or "block"

SDK source preview. The registry command will be npm install sevra, with imports from sevra/guard, after the source candidate is explicitly published and verified. The HTTP reference below is the current integration contract.

Handling the three verdicts

Waiting on a held action

The guard endpoint returns without waiting for a human. A held action comes back as a ticket, and there are three ways to learn the outcome. Default block mode: the SDK re-polls the decision endpoint with bounded 25 second server waits until the hold resolves or your overallTimeoutMs passes, at which point it returns a block. Poll mode: you get the ticket immediately and call sevra.decision(requestId) on your own schedule. Webhook mode: pass a callbackUrl (https, public hostname) and Sevra POSTs a signed guard.resolved notification when the hold resolves. The payload never carries the execution token; treat it as a wake-up and claim the decision with sevra.decision(requestId). Verify the x-sevra-signature header: t=<unix>,v1=<hex>, HMAC-SHA256 of the timestamp, a dot, then the raw body, keyed with the tenant callback key from Channels, not the workflow bearer key, with a 300 second tolerance. Delivery is best-effort with one retry, so keep a poll as the fallback.

// If your agent cannot block, take the held ticket and poll later.
const ticket = await sevra.guard({ ...request, mode: "poll" });
if (ticket.status === "held") {
  // Persist ticket.requestId, then poll until status leaves "held".
  const decision = await sevra.decision(ticket.requestId);
}

The one rule

Execute only when the verdict is allow and an executionToken is present. A thrown network error, a malformed response, or any other status means the action does not run. That discipline is what keeps your integrated caller fail-closed. Sevra cannot control a provider call made on a path that bypasses this check.

POST /api/app/gate/guard

Evaluate an action your caller submits before execution. Allow and Block are terminal; Require approval returns a held ticket. The endpoint does not hold a connection open waiting for a human decision.

curl -s https://sevra.dev/api/app/gate/guard \
  -H "Authorization: Bearer $SEVRA_GUARD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "refund-bot",
    "action": "refund",
    "target": "order:ord_8231",
    "params": { "orderId": "ord_8231", "amountMinor": 500, "currency": "USD" },
    "idempotencyKey": "refund:ord_8231",
    "amountMinor": 500,
    "currency": "USD",
    "direction": "out"
  }'

{
  "requestId": "3f7c9a1e-...",
  "verdict": "allow",
  "status": "approved",
  "executionToken": "sx_kQ2v...",
  "score": 120,
  "reasons": ["..."],
  "mode": "live"
}

{
  "requestId": "3f7c9a1e-...",
  "verdict": "require_approval",
  "status": "held",
  "score": 512,
  "reasons": ["...", "tier:role=admin,count=1"],
  "mode": "live"
}

{
  "requestId": "3f7c9a1e-...",
  "verdict": "block",
  "status": "blocked",
  "score": 940,
  "reasons": ["..."],
  "mode": "live"
}

GET /api/app/gate/requests/{id}/decision?wait=0..25

Poll a held request. wait optionally holds the connection up to 25 seconds and returns the instant the request leaves held; otherwise it answers immediately. A 204 means still held, so poll again. When the hold has been approved and the linked guard request has been released successfully, the first poll claims the single execution and returns status: "executed" with the token; polling again is safe and returns the same token. If approval evidence commits but release fails, the request remains held and token-free and requires operator intervention; automated reconciliation is not implemented. A denied hold returns denied, an expired one timed_out, both with verdict block. An unknown id returns a 200 with verdict block and reasons: ["not_found"], the fail-closed shape.

curl -s "https://sevra.dev/api/app/gate/requests/$REQUEST_ID/decision?wait=25" \
  -H "Authorization: Bearer $SEVRA_GUARD_KEY"

{
  "requestId": "3f7c9a1e-...",
  "verdict": "allow",
  "status": "executed",
  "executionToken": "sx_kQ2v...",
  "score": 512,
  "reasons": ["..."]
}

GET /api/app/gate/requests/{id}

Fetch the full request record plus the linked approval's decision timeline, with approver identity stripped: { request, approval }. The approval carries id, required, status, and decisions as { verdict, via, at } entries. Returns 404 not_found for an unknown id and 401 on a bad key.

curl -s https://sevra.dev/api/app/gate/requests/$REQUEST_ID \
  -H "Authorization: Bearer $SEVRA_GUARD_KEY"