Hold a Spend for Approval

Write an approval-required rule, watch it hold a matching spend before the provider is ever called, poll the hold from the agent side, and decide it from an operator seat.

Prerequisites

npm install @codespar/sdk

Three credentials, and they are not interchangeable.

The dashboard does both service-credential steps for you: rules live at /dashboard/policies, the queue at /dashboard/approvals.

1. Write the rule

type is approval-required. The match is (agents, tools) by glob, with * as the only metacharacter.

curl -X POST https://api.codespar.dev/v1/policies \
  -H "x-codespar-service-key: $CODESPAR_SERVICE_KEY" \
  -H "x-codespar-org: $CODESPAR_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "Hold payouts for review",
    "type": "approval-required",
    "agents": ["*"],
    "tools": ["wallet:pay", "wallet:withdraw", "asaas:post:transfers"],
    "config": {},
    "enabled": true
  }'

The 201 returns the Policy, including its pol_… id. Keep it: step 2 needs it.

config accepts an approvers array. It is validated and stored, and nothing reads it. Who can decide is decided by org role, not by that list.

2. Move the rule above every allow rule that matches

Creation inserts at MAX(sort_order) + 1, so a new rule lands last. The engine scans in order and stops at the first match. One earlier allow rule covering the same pair swallows the hold completely, and nothing warns you.

curl -X POST https://api.codespar.dev/v1/policies/reorder \
  -H "x-codespar-service-key: $CODESPAR_SERVICE_KEY" \
  -H "x-codespar-org: $CODESPAR_ORG_ID" \
  -H "content-type: application/json" \
  -d '{ "ids": ["pol_hold_payouts", "pol_allow_reads", "pol_daily_budget"] }'

204, no body. Send every rule id you have. The endpoint accepts a partial list and assigns index + 1 only to the ids you sent, so posting 2 of 5 rules leaves the other three tied at positions you did not choose.

3. The call gets held

The guard runs before the route handler, so the provider is never touched. What the caller receives depends on which path it used.

That 403 envelope mixes conventions in one object: reason, ruleType and ruleId in camelCase, approval_id and expires_at in snake_case.

import { CodeSpar, CodesparApiError } from "@codespar/sdk";

const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY! });
const session = await cs.create("user_123", { servers: ["asaas"] });

interface HeldCall {
  reason?: string;
  ruleType?: string;
  ruleId?: string;
  approval_id?: string;
  expires_at?: string;
}

try {
  const res = await session.proxyExecute({
    server: "asaas",
    endpoint: "/v3/transfers",
    method: "POST",
    body: { value: 250.0, pixAddressKey: "loja@example.com" },
  });
  console.log("dispatched", res.status, res.data);
} catch (e) {
  if (!(e instanceof CodesparApiError) || e.status !== 403) throw e;

  const held = e.body as HeldCall;
  if (!held.approval_id) {
    // A deny rule matched, not an approval rule. There is no hold to decide.
    throw e;
  }
  console.log("held", held.approval_id, "by rule", held.ruleId, "until", held.expires_at);
}

proxyExecute throws CodesparApiError and hands you the parsed body. execute does not throw on 403: it returns { success: false, data: null, error: "403: <raw body text>" }, so the approval id is inside a string you have to parse. Prefer proxyExecute when you plan to catch a hold, and note that it is also the only session path that records the real tool_input.

In the chat loop the hold arrives as a tool result, and the SDK ships a guard for it.

import { CodeSpar, isApprovalRequired } from "@codespar/sdk";

const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY! });
const session = await cs.create("user_123", { preset: "brazilian" });

for await (const event of session.sendStream("Pay R$250 to loja@example.com")) {
  if (event.type !== "tool_result") continue;
  const out = event.toolCall.output;
  if (isApprovalRequired(out)) {
    console.log("held", out.approval_id, "until", out.expires_at);
  }
}

There is a third way to find the hold, and it needs no string parsing and no exception. Every match also writes an evaluation row carrying the approval id.

const rows = await cs.api.get("/v1/policy-evaluations", { query: { limit: 20 } });
// Each row carries decision and approvalId. GET /v1/evaluations is a deprecated
// alias of the same handler.

4. Poll the hold

There is one poll endpoint, and a project key can use it. It is scoped to the caller's org and project.

import { CodeSpar } from "@codespar/sdk";

const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY! });
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

export async function waitForApproval(id: string, timeoutMs = 15 * 60_000) {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const status = await cs.api.get("/v1/approvals/{id}/status", { path: { id } });

    // approval_status: pending | approved | denied | expired | execution_failed
    if (status.approval_status !== "pending") {
      return status; // carries decided_by, decision_reason, execution_result
    }
    await sleep(5_000);
  }
  throw new Error(`approval ${id} is still pending after ${timeoutMs} ms`);
}

A missing or out-of-scope id answers 404 approval_not_found here. The operator read at GET /v1/approvals/{id} answers 404 not_found instead. Two different literals for the same idea, on two endpoints in the same journey.

5. Read the queue and decide

The two operator reads are org-scoped, not project-scoped, and they accept a project key as well. Only the decide write refuses one. That asymmetry has a consequence: a key bound to one project sees holds raised under sibling projects in this queue, and cannot poll any of them at step 4.

# Pending only. Omitting status does NOT mean "all".
curl https://api.codespar.dev/v1/approvals \
  -H "x-codespar-service-key: $CODESPAR_SERVICE_KEY" \
  -H "x-codespar-org: $CODESPAR_ORG_ID"

# History, once you know you want it
curl -G https://api.codespar.dev/v1/approvals \
  -H "x-codespar-service-key: $CODESPAR_SERVICE_KEY" \
  -H "x-codespar-org: $CODESPAR_ORG_ID" \
  --data-urlencode "status=approved,denied,expired"

The response is a raw array, with no envelope and no cursor. limit defaults to 100 and is capped at 100, so past the 100 most recent rows there is no second page. A status value outside the enum, or a limit outside 1 to 100, answers 400 invalid_query.

Read one row to see what is actually being approved.

curl https://api.codespar.dev/v1/approvals/apv_8ZqK3m1e4xW7tb \
  -H "x-codespar-service-key: $CODESPAR_SERVICE_KEY" \
  -H "x-codespar-org: $CODESPAR_ORG_ID"

Two fields on that row mislead if you read them as identifiers. tool_name has no single format: the proxy lane writes <server>:<method>:<endpoint> with the slashes turned into colons, the execute lane writes whatever string the caller sent, the over-cap settlement lane writes codespar_pay, and the operator lanes write admin:account_status_set or admin:withdrawal_resolve. matched_rule_id is not always a pol_ id either: the non-overridable deny list and the settlement lanes write their own literals, such as boleto-over-cap, so GET /v1/policies/{id} with that value answers 404 for most holds.

Then decide it. Both fields are required, and reason must be 1 to 8000 characters of something real.

curl -X POST https://api.codespar.dev/v1/approvals/apv_8ZqK3m1e4xW7tb/decide \
  -H "x-codespar-service-key: $CODESPAR_SERVICE_KEY" \
  -H "x-codespar-org: $CODESPAR_ORG_ID" \
  -H "x-codespar-user-token: $CLERK_USER_TOKEN" \
  -H "x-codespar-user: $CLERK_USER_ID" \
  -H "content-type: application/json" \
  -d '{
    "decision": "approve",
    "reason": "Vendor invoice 4471 matches the purchase order."
  }'

The order the checks run in

This is what tells you how much already happened when a refusal lands.

1. Org mismatch on the id, answered 404.
2. Identity gate: bearer refused, then user token verified, then role floor. 403 or 503.
3. Rate limit for the org. 429.
4. Body validation. 400.
5. Only then the transaction: read the row's project, compare-and-set WHERE id AND org_id AND status = 'pending' AND expires_at > now, and on a hit write the decision, mirror it into the evaluation row, and append approval_decided, all in the same BEGIN.

What the decide route answers

Which refusal a retry fixes

What approve actually does

Denying ends there. Approving starts a replay that runs outside the decide transaction, in three parts: a witness event approval_call_attempted, the provider call, then approval_executed on a 2xx or approval_execution_failed on anything else, carrying execution_result with ok, upstream_status, data, error and duration_ms.

The replay's idempotency key is imposed by the server as apv-<approval_id>. Any Idempotency-Key the agent sent is kept in tool_input for correlation only.

The replay only calls a real provider when PROXY_MODE=real. With PROXY_MODE=mock or NODE_ENV=test the result is stamped mocked: true. Any other value answers proxy_mode_unconfigured and the row becomes execution_failed, on purpose, so the chain never holds an approval_executed that cannot be told apart from a real one.

Header stripping is wider than the spec describes. The document mentions authorization and cookie; the sanitizer also drops any header key ending in -token or -key, case-insensitive.

Read the chain

Five event types cover the whole journey, and event_type is an exact match unless the value ends in a dot. These five are underscore-named, so no prefix catches them together: that is five queries.

for t in approval_pending approval_decided approval_call_attempted \
         approval_executed approval_execution_failed; do
  curl -s -G https://api.codespar.dev/v1/audit-events \
    -H "authorization: Bearer $CODESPAR_API_KEY" \
    --data-urlencode "event_type=$t" \
    --data-urlencode "limit=100"
done

The default window is the last 7 days. Pass from and to for anything older, and before_sequence to walk backwards. A project key reads this endpoint, which makes the chain the one place a caller-side key can reconstruct what happened without operator access.

GET /v1/approvals/health reports pending_count and oldest_pending_age_seconds for your own org, but last_sweep_at is not yours: the sweep log has one row per sweep type and no org column, so that timestamp moves for reasons unrelated to your queue. Read it as "sweeps are alive on this deployment", never as "my queue was swept".

What this does not do

• No way to create a hold. There is no POST /v1/approvals. A hold is born only from an approval-required rule that matched, or from an internal guard such as the boleto mandate cap or the operator lanes.
• No amount threshold. An approval-required rule matches on agents and tools, nothing else. "Hold anything above R$ 5.000" is not expressible: a budget rule denies, it does not hold. Guardrails currently claims otherwise, and the rule grammar does not support it. A budget rule is also a poor substitute from the SDK, because session.execute sends no estimatedCost and the guard reads that as a cost of zero.
• No per-rule expiry. APPROVAL_TTL_HOURS is deployment-wide and defaults to 24. Nothing in the create body takes a deadline.
• No webhook, no trigger, no stream. No approval.* event is published anywhere, and the poll has no streaming variant. Poll, or read the audit chain.
• config.approvers is decorative. It is validated and stored, and never read. Anyone holding admin in the org can decide any hold in it.
• No status alias under /v1/orgs. The org-prefixed aliases cover list, read, health and decide. The caller poll exists only at the canonical path.
• No CLI command. approvals, policies, policy-evaluations and evaluations are all declared outside the CLI surface on purpose.
• No SDK namespace. There is no cs.approvals and no session.approvals, only the generic REST client. cs.api.post("/v1/approvals/{id}/decide", …) compiles and always answers 403 at runtime, because the client can only build an Authorization: Bearer header, and a bearer credential is exactly what the route refuses. The six policy operations fail the same way. There is also no way to attach x-codespar-user-token through the typed client: the operation declares no headers, so TypeScript rejects the key.
• The served document is incomplete here. It does not describe the bearer refusal on the policy routes, it types PolicyCreate.config as an open object with no per-type shape, and its PolicyEvaluation schema is missing approvalId, decidedAt and decidedBy while its decision enum has no approval_required value the handler actually returns. The 404 it documents on the approvals list is unreachable at the canonical path: only the /v1/orgs/{orgId}/approvals alias, called with someone else's org, produces it.

Next steps