Approvals

This page is generated from the published OpenAPI document. It is complete with respect to that document and says nothing about surfaces the document does not describe yet. See what is generated here for what that means.

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

These three reads follow a held call: a policy rule or a non-overridable guard stopped a spend before dispatch and wrote an approval row with an expiry. Poll GET /v1/approvals/{id}/status until it leaves pending. The write that decides it, POST /v1/orgs/{orgId}/approvals/{id}/decide, is not in this document and refuses API keys on purpose: the key that asked for a spend must not be the key that approves it. Who decides, where, and the pattern for confirming a one-off spend in your own channel before dispatch are on the concept page, Mandates, receipts and approvals, and in Guardrails.

Every operation, from the spec

Generated from the published OpenAPI document, so it never drifts from what the API actually serves. The section above is written by hand and carries what a schema cannot: the object model, field rules, and the order to call things in.

GET /v1/approvals/health

Approval queue health

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/approvals/health \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

const res = await fetch("https://api.codespar.dev/v1/approvals/health", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/approvals/health");

{
  "status": "ok",
  "pending_count": 1
}

GET /v1/approvals/{id}

Read one approval

Path parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/approvals/{id} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

const res = await fetch("https://api.codespar.dev/v1/approvals/{id}", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/approvals/{id}", {
  path: {
    id: "approval_0000000000000000"
  }
});

{
  "id": "obj_0000000000000000",
  "org_id": "org_0000000000000000",
  "agent_id": "agt_0000000000000000",
  "matched_rule_id": "matchedrule_0000000000000000",
  "matched_rule_name": "Example",
  "tool_name": "Example",
  "tool_input": {},
  "status": "pending",
  "created_at": "2026-01-15T12:00:00.000Z",
  "expires_at": "2026-01-15T12:00:00.000Z"
}

GET /v1/approvals/{id}/status

Poll a held call for its outcome

Path parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/approvals/{id}/status \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

const res = await fetch("https://api.codespar.dev/v1/approvals/{id}/status", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/approvals/{id}/status", {
  path: {
    id: "approval_0000000000000000"
  }
});

{
  "approval_id": "approval_0000000000000000",
  "approval_status": "pending",
  "tool_name": "Example",
  "created_at": "2026-01-15T12:00:00.000Z",
  "expires_at": "2026-01-15T12:00:00.000Z"
}