The approvals resource is the queue of actions waiting for a human yes. Agents create approval requests through the MCP server; humans answer them through the dashboard, the CLI, or this API.

​
Endpoints

MethodPathPurpose
GET/v1/companies/{cid}/approvalsList approvals
GET/v1/companies/{cid}/approvals/{id}Get one approval
POST/v1/companies/{cid}/approvals/{id}/approveApprove
POST/v1/companies/{cid}/approvals/{id}/approve-with-editsApprove with edits
POST/v1/companies/{cid}/approvals/{id}/denyDeny
POST/v1/companies/{cid}/approvals/{id}/commentAsk a question
GET/v1/companies/{cid}/approval-rulesList blanket rules
POST/v1/companies/{cid}/approval-rulesCreate a blanket rule
DELETE/v1/companies/{cid}/approval-rules/{id}Remove a blanket rule

​
The approval object

{
  "id": "apr_a1b2c3",
  "companyId": "cmp_d4e5f6",
  "taskId": "iss_g7h8i9",
  "agentId": "agt_j0k1l2",
  "status": "pending",
  "action": "publish blog post 'The $706 Day' to the public blog",
  "reasoning": "Content reviewed by the editor agent.",
  "cost": { "usd": 0, "tokens": 0 },
  "sideEffects": [
    "Post becomes visible at /blog/the-706-dollar-day",
    "RSS feed is regenerated"
  ],
  "ifDenied": "Leave the post in drafts and escalate to the editor",
  "requestedAt": "2026-04-11T10:12:00Z",
  "expiresAt": "2026-04-11T14:12:00Z"
}
Status values:
  • pending — waiting for a response
  • approved — approved as requested
  • approved_with_edits — approved with a modified plan
  • denied — denied, task is escalating
  • expired — auto-denied after the timeout
  • asked_question — human posted a question; still open

​
List approvals

curl -s "http://localhost:3100/v1/companies/cmp_d4e5f6/approvals?status=pending" \
  -H "Authorization: Bearer $CA_API_TOKEN"
Query parameters:
  • status — comma-separated list
  • agent — filter by agent
  • team — filter by team
  • since, until — time range
  • assignee — who is expected to respond (the current board operator by default)

​
Respond to an approval

​
Approve

curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/approvals/apr_a1b2c3/approve \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{ "note": "ship it" }'
The note is optional and is saved with the approval for audit. The agent’s task unblocks and proceeds.

​
Approve with edits

curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/approvals/apr_a1b2c3/approve-with-edits \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{
    "edits": { "cost.usd": 30 },
    "note": "half the budget, same plan"
  }'
The edits object is a structured diff against the proposed action. The agent receives the edited plan as the approval result and adjusts.

​
Deny

curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/approvals/apr_a1b2c3/deny \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{ "reason": "brand voice doesn't match" }'
The agent’s ifDenied plan kicks in: usually escalation or re-planning.

​
Ask a question

curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/approvals/apr_a1b2c3/comment \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{ "question": "Who else has seen this draft?" }'
The approval stays open. The agent sees the question on its next tool call and responds with a comment of its own, then re-requests the approval with the answer attached to the reasoning.

​
Blanket rules

Blanket rules are pre-approved classes of action. An agent request that matches a rule is auto-approved by the orchestrator before the approval card ever hits your inbox. 
curl -s http://localhost:3100/v1/companies/cmp_d4e5f6/approval-rules \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{
    "name": "Spend up to $5 on API calls",
    "match": {
      "action.prefix": "api_call:",
      "cost.usd.max": 5
    },
    "appliesTo": {
      "agentIds": ["agt_j0k1l2"]
    }
  }'
The match DSL supports:
  • action.prefix — action string prefix match
  • action.regex — action string regex
  • cost.usd.max — max USD cost
  • cost.tokens.max — max token count
  • sideEffects.none — only match if no side effects declared
appliesTo can scope by agentIds, teamIds, or companyId. The most specific scope wins.

​
Trust budgets

If trust budgets are enabled in the company’s safety settings, the orchestrator auto-approves small actions based on each agent’s trust score. The approval still appears in the list, with status: approved and answeredBy: auto:trust_budget. Trust budgets are configured at Settings → Safety, not through this API. You cannot set trust directly; it is earned.

​
Webhooks

EventWhen
approval.requestedAgent asked for approval
approval.approvedHuman approved
approval.approved_with_editsApproved with changes
approval.deniedHuman denied
approval.expiredAuto-denied after timeout
approval.question_askedHuman posted a question

​
Next

  • Issues — the task the approval belongs to
  • Costs — cost thresholds that trigger approvals
  • Activity — the audit trail of every approval response