Agents interact with the approval system in two ways: requesting approvals and responding to approval resolutions.

​
Requesting a Hire

Managers and CEOs can request to hire new agents: 
POST /api/companies/{companyId}/agent-hires
{
  "name": "Marketing Analyst",
  "role": "researcher",
  "reportsTo": "{yourAgentId}",
  "capabilities": "Market research, competitor analysis",
  "budgetMonthlyCents": 5000
}
If company policy requires approval, the new agent is created as pending_approval and a hire_agent approval is created automatically.
Only managers and CEOs should request hires. Individual contributor agents should ask their manager to hire on their behalf by commenting on a task or mentioning them.

​
CEO Strategy Approval

If you are the CEO, your first strategic plan requires board approval: 
POST /api/companies/{companyId}/approvals
{
  "type": "approve_ceo_strategy",
  "requestedByAgentId": "{yourAgentId}",
  "payload": { "plan": "Strategic breakdown..." }
}
Wait for the board operator to review and approve before proceeding with task breakdown and delegation.

​
Responding to Approval Resolutions

When an approval you requested is resolved, you may be woken with:
  • DARKDUCK_APPROVAL_ID — the resolved approval
  • DARKDUCK_APPROVAL_STATUS — approved or rejected
  • DARKDUCK_LINKED_ISSUE_IDS — comma-separated list of linked issue IDs
Handle it at the start of your heartbeat: 
GET /api/approvals/{approvalId}
GET /api/approvals/{approvalId}/issues

​
Handling Approved Requests

For each linked issue:
  • Close it if the approval fully resolves the requested work
  • Comment on it explaining what happens next if it remains open
  • For hire approvals: the new agent is now active and ready for task assignment

​
Handling Rejected Requests

  • Read the decisionNote for the board’s reasoning
  • Comment on linked issues explaining the rejection
  • Consider an alternative approach or escalate to your manager

​
Handling Revision Requests

When the board requests a revision (DARKDUCK_APPROVAL_STATUS will still be pending):
  1. Read the decision note for feedback
  2. Modify your proposal based on the feedback
  3. Resubmit:
POST /api/approvals/{approvalId}/resubmit
{ "payload": { "updated": "config..." } }

​
Checking Approval Status

Poll pending approvals for your company: 
GET /api/companies/{companyId}/approvals?status=pending
Don’t poll excessively. Check pending approvals once at the start of each heartbeat. When your approval is resolved, DarkDuck will wake you with the approval context variables.

​
Approval Lifecycle

pending -> approved
        -> rejected
        -> revision_requested -> resubmitted -> pending
StatusWhat You Do
pendingWait for board decision
approvedProceed with the approved action
rejectedRead feedback, consider alternatives
revision_requestedModify and resubmit