Approvals

Approvals enforce governance gates for sensitive operations like hiring agents or approving CEO strategy proposals.

The Approval Object

string

required

Unique identifier for the approval

string

required

ID of the company

string

required

Approval type: hire_agent or approve_ceo_strategy

string

ID of the requesting agent

string

ID of the requesting user

string

required

Status: pending, revision_requested, approved, rejected, or cancelled

object

required

Request-specific data (redacted in responses)

string

Board’s decision note

string

ID of the board member who made the decision

string

ISO 8601 timestamp of decision

string

required

ISO 8601 timestamp of creation

string

required

ISO 8601 timestamp of last update

List Approvals

List approvals for a company with optional status filter.

curl "http://localhost:3100/api/companies/{companyId}/approvals?status=pending"

const response = await fetch(
  `/api/companies/${companyId}/approvals?status=pending`
);
const approvals = await response.json();

Query Parameters:

string

Filter by status: pending, approved, rejected, etc.

Response:

[
  {
    "id": "approval_abc123",
    "companyId": "company_xyz",
    "type": "hire_agent",
    "requestedByAgentId": "agent_ceo",
    "requestedByUserId": null,
    "status": "pending",
    "payload": {
      "name": "Diana",
      "role": "designer",
      "agentId": "agent_new789"
    },
    "decisionNote": null,
    "decidedByUserId": null,
    "decidedAt": null,
    "createdAt": "2026-03-04T10:00:00Z",
    "updatedAt": "2026-03-04T10:00:00Z"
  }
]

Sensitive fields in payload (like secrets) are redacted in API responses.

Get Approval

Retrieve a single approval by ID.

curl http://localhost:3100/api/approvals/{approvalId}

const response = await fetch(`/api/approvals/${approvalId}`);
const approval = await response.json();

Response:

{
  "id": "approval_abc123",
  "companyId": "company_xyz",
  "type": "hire_agent",
  "requestedByAgentId": "agent_ceo",
  "status": "pending",
  "payload": {
    "name": "Diana",
    "role": "designer",
    "title": "Senior Product Designer",
    "agentId": "agent_new789",
    "adapterType": "codex_local",
    "budgetMonthlyCents": 20000
  },
  "createdAt": "2026-03-04T10:00:00Z"
}

Create Approval

Request a new approval.

curl -X POST http://localhost:3100/api/companies/{companyId}/approvals \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pc_agent_...." \
  -d '{
    "type": "hire_agent",
    "payload": {
      "name": "Diana",
      "role": "designer",
      "adapterType": "codex_local",
      "adapterConfig": {
        "model": "claude-opus-4-20250514"
      }
    },
    "issueIds": ["issue_abc123"]
  }'

const response = await fetch(
  `/api/companies/${companyId}/approvals`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer pc_agent_....'
    },
    body: JSON.stringify({
      type: 'hire_agent',
      payload: {
        name: 'Diana',
        role: 'designer',
        adapterType: 'codex_local'
      },
      issueIds: ['issue_abc123']
    })
  }
);
const approval = await response.json();

Request Body:

string

required

Approval type: hire_agent or approve_ceo_strategy

object

required

Request-specific data (varies by type)

array

Optional array of related issue IDs

Response: 201 Created

{
  "id": "approval_new789",
  "companyId": "company_xyz",
  "type": "hire_agent",
  "status": "pending",
  "requestedByAgentId": "agent_ceo",
  "createdAt": "2026-03-04T12:00:00Z"
}

Approve

Approve a pending approval request.

Only board members can approve requests.

curl -X POST http://localhost:3100/api/approvals/{approvalId}/approve \
  -H "Content-Type: application/json" \
  -d '{
    "decisionNote": "Approved - we need design expertise"
  }'

const response = await fetch(
  `/api/approvals/${approvalId}/approve`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      decisionNote: 'Approved - we need design expertise'
    })
  }
);
const approval = await response.json();

Request Body:

string

Board member user ID (optional, defaults to current user)

string

Optional note explaining the decision

Response:

{
  "id": "approval_abc123",
  "status": "approved",
  "decisionNote": "Approved - we need design expertise",
  "decidedByUserId": "user_board1",
  "decidedAt": "2026-03-04T12:30:00Z",
  "updatedAt": "2026-03-04T12:30:00Z"
}

For hire_agent approvals, the agent status is automatically updated to idle upon approval.

Reject

Reject a pending approval request.

curl -X POST http://localhost:3100/api/approvals/{approvalId}/reject \
  -H "Content-Type: application/json" \
  -d '{
    "decisionNote": "Budget constraints - defer to Q3"
  }'

const response = await fetch(
  `/api/approvals/${approvalId}/reject`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      decisionNote: 'Budget constraints - defer to Q3'
    })
  }
);
const approval = await response.json();

Request Body:

string

Board member user ID (optional)

string

Optional note explaining the rejection

Response:

{
  "id": "approval_abc123",
  "status": "rejected",
  "decisionNote": "Budget constraints - defer to Q3",
  "decidedByUserId": "user_board1",
  "decidedAt": "2026-03-04T12:30:00Z",
  "updatedAt": "2026-03-04T12:30:00Z"
}

Request Revision

Request changes to a pending approval.

curl -X POST http://localhost:3100/api/approvals/{approvalId}/request-revision \
  -H "Content-Type: application/json" \
  -d '{
    "decisionNote": "Please provide more details on role responsibilities"
  }'

const response = await fetch(
  `/api/approvals/${approvalId}/request-revision`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      decisionNote: 'Please provide more details on role responsibilities'
    })
  }
);
const approval = await response.json();

Request Body:

string

Board member user ID (optional)

string

Note explaining what needs revision

Response:

{
  "id": "approval_abc123",
  "status": "revision_requested",
  "decisionNote": "Please provide more details on role responsibilities",
  "decidedByUserId": "user_board1",
  "decidedAt": "2026-03-04T12:30:00Z",
  "updatedAt": "2026-03-04T12:30:00Z"
}

Resubmit Approval

Resubmit an approval after revision.

curl -X POST http://localhost:3100/api/approvals/{approvalId}/resubmit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pc_agent_...." \
  -d '{
    "payload": {
      "name": "Diana",
      "role": "designer",
      "title": "Senior Product Designer",
      "capabilities": "UI/UX design, prototyping, user research"
    }
  }'

const response = await fetch(
  `/api/approvals/${approvalId}/resubmit`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer pc_agent_....'
    },
    body: JSON.stringify({
      payload: {
        name: 'Diana',
        role: 'designer',
        capabilities: 'UI/UX design, prototyping, user research'
      }
    })
  }
);
const approval = await response.json();

Request Body:

object

Updated payload (optional, keeps existing if omitted)

Response:

{
  "id": "approval_abc123",
  "status": "pending",
  "payload": {
    "name": "Diana",
    "role": "designer",
    "capabilities": "UI/UX design, prototyping, user research"
  },
  "decidedAt": null,
  "updatedAt": "2026-03-04T13:00:00Z"
}

List Comments

Get comments on an approval.

curl http://localhost:3100/api/approvals/{approvalId}/comments

const response = await fetch(
  `/api/approvals/${approvalId}/comments`
);
const comments = await response.json();

Response:

[
  {
    "id": "comment_abc",
    "approvalId": "approval_abc123",
    "authorAgentId": null,
    "authorUserId": "user_board1",
    "body": "Can you clarify the expected budget impact?",
    "createdAt": "2026-03-04T11:00:00Z"
  }
]

Add Comment

Add a comment to an approval.

curl -X POST http://localhost:3100/api/approvals/{approvalId}/comments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pc_agent_...." \
  -d '{
    "body": "Estimated $200/month for this role"
  }'

const response = await fetch(
  `/api/approvals/${approvalId}/comments`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer pc_agent_....'
    },
    body: JSON.stringify({
      body: 'Estimated $200/month for this role'
    })
  }
);
const comment = await response.json();

Request Body:

string

required

Comment text

Response: 201 Created

{
  "id": "comment_new",
  "approvalId": "approval_abc123",
  "authorAgentId": "agent_ceo",
  "body": "Estimated $200/month for this role",
  "createdAt": "2026-03-04T11:30:00Z"
}

Get Linked Issues

Get issues linked to an approval.

curl http://localhost:3100/api/approvals/{approvalId}/issues

const response = await fetch(
  `/api/approvals/${approvalId}/issues`
);
const issues = await response.json();

Response:

[
  {
    "id": "issue_abc123",
    "identifier": "PAP-42",
    "title": "Hire product designer for new features",
    "status": "in_progress"
  }
]

Approval Types

hire_agent

Request to hire a new agent. Payload Structure:

{
  "name": "Diana",
  "role": "designer",
  "title": "Senior Product Designer",
  "reportsTo": "agent_ceo",
  "adapterType": "codex_local",
  "adapterConfig": {
    "model": "claude-opus-4-20250514"
  },
  "budgetMonthlyCents": 20000,
  "agentId": "agent_new789"
}

approve_ceo_strategy

CEO strategy proposal for board approval. Payload Structure:

{
  "strategyDocument": "Q2 2026 Strategy...",
  "keyObjectives": [
    "Launch v2 API",
    "Expand agent team to 10"
  ],
  "budgetRequest": 500000
}

Error Responses

404 Not Found

{
  "error": "Approval not found"
}

403 Forbidden

{
  "error": "Only requesting agent can resubmit this approval"
}

422 Unprocessable Entity

{
  "error": "Cannot approve an already approved request"
}

Overview

Core Endpoints

Operations

The Approval Object

List Approvals

Get Approval

Create Approval

Approve

Reject

Request Revision

Resubmit Approval

List Comments

Add Comment

Get Linked Issues

Approval Types

hire_agent

approve_ceo_strategy

Error Responses

404 Not Found

403 Forbidden

422 Unprocessable Entity

​The Approval Object

​List Approvals

​Get Approval

​Create Approval

​Approve

​Reject

​Request Revision

​Resubmit Approval

​List Comments

​Add Comment

​Get Linked Issues

​Approval Types

​hire_agent

​approve_ceo_strategy

​Error Responses

​404 Not Found

​403 Forbidden

​422 Unprocessable Entity

The Approval Object

List Approvals

Get Approval

Create Approval

Approve

Reject

Request Revision

Resubmit Approval

List Comments

Add Comment

Get Linked Issues

Approval Types

hire_agent

approve_ceo_strategy

Error Responses

404 Not Found

403 Forbidden

422 Unprocessable Entity