Approvals
Generated HTTP reference for the 3 operations the published OpenAPI document describes under approvals.
3 min read
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.
GET /v1/approvals/health
GET
https://api.codespar.dev/v1/approvals/healthApproval queue health
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
last_sweep_at | string,null (date-time) | yes | Deployment-wide, not per-organization. See the description. |
oldest_pending_age_seconds | integer,null | yes | Age of the oldest pending hold, in seconds. Null when none is pending. |
pending_count | integer | yes | — |
status | "ok" | yes | — |
Example request
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();Example response 200
{
"status": "ok",
"pending_count": 1
}GET /v1/approvals/{id}
GET
https://api.codespar.dev/v1/approvals/{id}Read one approval
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | — |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
404 | object | Not Found |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
agent_id | string | yes | — |
created_at | string (date-time) | yes | — |
decided_at | string,null (date-time) | yes | — |
decided_by | string,null | yes | The approver, null while pending. |
decision_reason | string,null | yes | — |
executed_at | string,null (date-time) | yes | — |
execution_result | object,null | yes | Null until an approved call has been replayed. Open shape, passed through verbatim. |
expires_at | string (date-time) | yes | When the hold stops being decidable. |
id | string | yes | apv_ + nanoid(16). |
matched_rule_id | string | yes | The policy rule that held the call. |
matched_rule_name | string | yes | — |
org_id | string | yes | — |
project_id | string,null | yes | Null for a hold raised outside any project. |
session_id | string,null | yes | — |
status | "pending" | "approved" | "denied" | "expired" | "execution_failed" | yes | — |
tool_input | object | yes | The arguments as RECORDED, which is not always the arguments as sent. Empty for a hold raised on the session execute path, and header-stripped on the proxy path. |
tool_name | string | yes | The held call, in whatever form the lane that raised the hold writes. There is no single format: see the operation description before matching on it. |
Example request
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();Example response 200
{
"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
GET
https://api.codespar.dev/v1/approvals/{id}/statusPoll a held call for its outcome
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | — |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
404 | object | Not Found: no approval with that id in the caller's org and project. |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
approval_id | string | yes | — |
approval_status | "pending" | "approved" | "denied" | "expired" | "execution_failed" | yes | — |
created_at | string (date-time) | yes | — |
decided_at | string,null (date-time) | yes | — |
decided_by | string,null | yes | — |
decision_reason | string,null | yes | — |
executed_at | string,null (date-time) | yes | — |
execution_result | object,null | yes | — |
expires_at | string (date-time) | yes | — |
tool_name | string | yes | — |
Example request
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();Example response 200
{
"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"
}