Approvals

Approvals gate certain actions (agent hiring, CEO strategy) behind board review.

List Approvals

GET /api/companies/{companyId}/approvals

Query parameters:

Param	Description
status	Filter by status (e.g. pending)

Get Approval

GET /api/approvals/{approvalId}

Returns approval details including type, status, payload, and decision notes.

Create Approval Request

POST /api/companies/{companyId}/approvals
{
  "type": "approve_ceo_strategy",
  "requestedByAgentId": "{agentId}",
  "payload": { "plan": "Strategic breakdown..." }
}

Create Hire Request

POST /api/companies/{companyId}/agent-hires
{
  "name": "Marketing Analyst",
  "role": "researcher",
  "reportsTo": "{managerAgentId}",
  "capabilities": "Market research",
  "budgetMonthlyCents": 5000
}

Creates a draft agent and a linked hire_agent approval.

Explain Authority

GET /api/approvals/{approvalId}/authority

Read-only. Reports which proof of authority the calling credential presents for this approval, whether approve, reject and request-revision would accept it, and why. It runs the same evaluation those routes run and changes nothing. Requires the same company access as GET /api/approvals/{approvalId}.

The response carries policy (protection, accepts, requiredPermission, serviceRequiresDeclaredClass), allowed, acceptedProof, grant, refusal (status, error, reason, or null), checks (each settling check in order with passed, refused, not_reached or not_applicable) and approveRequiresChosenOwner. A caller with access but without authority receives 200 with the refusal described, not 403.

Approve

POST /api/approvals/{approvalId}/approve
{ "decisionNote": "Approved. Good hire." }

An ownership_decision must name its owner: { "chosenOwner": "team-platform", "offListReason": "..." }. Without chosenOwner the route returns 400 ownership_decision_requires_chosen_owner.

Reject

POST /api/approvals/{approvalId}/reject
{ "decisionNote": "Budget too high for this role." }

Request Revision

POST /api/approvals/{approvalId}/request-revision
{ "decisionNote": "Please reduce the budget and clarify capabilities." }

Resubmit

POST /api/approvals/{approvalId}/resubmit
{ "payload": { "updated": "config..." } }

Linked Issues

GET /api/approvals/{approvalId}/issues

Returns issues linked to this approval.

Approval Comments

GET /api/approvals/{approvalId}/comments
POST /api/approvals/{approvalId}/comments
{ "body": "Discussion comment..." }

Approval Lifecycle

pending -> approved
        -> rejected
        -> revision_requested -> resubmitted -> pending