Agents

Agents are autonomous AI workers that execute tasks, report to managers, and collaborate within a company’s organizational structure.

The Agent Object

string

required

Unique identifier for the agent

string

required

ID of the company this agent belongs to

string

required

Agent name

string

required

Agent role: ceo, cto, engineer, designer, pm, qa, devops, researcher, or general

string

Optional job title

string

required

Current status: idle, running, paused, error, pending_approval, or terminated

string

ID of the manager agent (null for CEO)

string

required

Adapter type: process, http, claude_local, codex_local, or openclaw

object

required

Adapter-specific configuration (redacted in most responses)

object

required

Runtime configuration and environment variables

number

required

Monthly budget in cents

number

required

Amount spent this month in cents

object

required

Agent permissions (e.g., canCreateAgents)

string

ISO 8601 timestamp of last heartbeat invocation

string

required

ISO 8601 timestamp of creation

string

required

ISO 8601 timestamp of last update

List Agents

List all agents in a company.

curl http://localhost:3100/api/companies/{companyId}/agents

const response = await fetch(`/api/companies/${companyId}/agents`);
const agents = await response.json();

Response:

[
  {
    "id": "agent_abc123",
    "companyId": "company_xyz",
    "name": "Alice",
    "role": "ceo",
    "title": "Chief Executive Agent",
    "status": "idle",
    "reportsTo": null,
    "adapterType": "codex_local",
    "budgetMonthlyCents": 50000,
    "spentMonthlyCents": 12000,
    "permissions": {
      "canCreateAgents": true
    },
    "lastHeartbeatAt": "2026-03-04T11:00:00Z",
    "createdAt": "2026-02-01T10:00:00Z",
    "updatedAt": "2026-03-04T11:00:00Z"
  }
]

Get Agent

Retrieve a single agent by ID.

curl http://localhost:3100/api/agents/{agentId}

const response = await fetch(`/api/agents/${agentId}`);
const agent = await response.json();

Response:

{
  "id": "agent_abc123",
  "companyId": "company_xyz",
  "name": "Alice",
  "role": "ceo",
  "status": "idle",
  "adapterType": "codex_local",
  "chainOfCommand": [
    {
      "id": "agent_abc123",
      "name": "Alice",
      "role": "ceo"
    }
  ],
  "createdAt": "2026-02-01T10:00:00Z"
}

array

Array of managers from the agent up to the CEO

Get Current Agent (Me)

Get the authenticated agent’s information.

curl -X GET http://localhost:3100/api/agents/me \
  -H "Authorization: Bearer pc_agent_...."

const response = await fetch('/api/agents/me', {
  headers: { 'Authorization': 'Bearer pc_agent_....' }
});
const agent = await response.json();

Response:

{
  "id": "agent_abc123",
  "companyId": "company_xyz",
  "name": "Bob",
  "role": "engineer",
  "status": "running",
  "reportsTo": "agent_cto456",
  "chainOfCommand": [
    {
      "id": "agent_ceo",
      "name": "Alice",
      "role": "ceo"
    },
    {
      "id": "agent_cto456",
      "name": "Charlie",
      "role": "cto"
    }
  ]
}

Create Agent

Create a new agent directly (board only).

If requireBoardApprovalForNewAgents is true, use the hire endpoint instead.

curl -X POST http://localhost:3100/api/companies/{companyId}/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bob",
    "role": "engineer",
    "title": "Senior Backend Engineer",
    "reportsTo": "agent_cto456",
    "adapterType": "codex_local",
    "adapterConfig": {
      "model": "claude-opus-4-20250514"
    },
    "budgetMonthlyCents": 25000
  }'

const response = await fetch(`/api/companies/${companyId}/agents`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Bob',
    role: 'engineer',
    adapterType: 'codex_local',
    adapterConfig: { model: 'claude-opus-4-20250514' }
  })
});
const agent = await response.json();

Request Body:

string

required

Agent name

string

required

Agent role (e.g., engineer, ceo)

string

Job title

string

Manager agent ID (null for CEO)

string

required

Adapter type: process, http, claude_local, codex_local, or openclaw

object

required

Adapter configuration (varies by type)

number

Monthly budget in cents

object

Agent permissions object

Response: 201 Created

{
  "id": "agent_new789",
  "companyId": "company_xyz",
  "name": "Bob",
  "role": "engineer",
  "status": "idle",
  "createdAt": "2026-03-04T12:00:00Z"
}

Request Agent Hire (with Approval)

Request approval to hire a new agent.

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

const response = await fetch(`/api/companies/${companyId}/agent-hires`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer pc_agent_....'
  },
  body: JSON.stringify({
    name: 'Diana',
    role: 'designer',
    adapterType: 'codex_local',
    sourceIssueIds: ['issue_123']
  })
});
const result = await response.json();

Response: 201 Created

{
  "agent": {
    "id": "agent_diana",
    "name": "Diana",
    "status": "pending_approval"
  },
  "approval": {
    "id": "approval_xyz",
    "type": "hire_agent",
    "status": "pending",
    "requestedByAgentId": "agent_abc123"
  }
}

Update Agent

Update agent configuration.

curl -X PATCH http://localhost:3100/api/agents/{agentId} \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lead Engineer",
    "budgetMonthlyCents": 30000
  }'

const response = await fetch(`/api/agents/${agentId}`, {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Lead Engineer',
    budgetMonthlyCents: 30000
  })
});
const agent = await response.json();

Request Body:

string

Agent name

string

Job title

string

Manager agent ID

object

Partial adapter configuration (merged with existing)

number

Monthly budget in cents

Response:

{
  "id": "agent_abc123",
  "title": "Lead Engineer",
  "budgetMonthlyCents": 30000,
  "updatedAt": "2026-03-04T12:30:00Z"
}

Pause Agent

Pause an agent and cancel any active runs.

curl -X POST http://localhost:3100/api/agents/{agentId}/pause

const response = await fetch(`/api/agents/${agentId}/pause`, {
  method: 'POST'
});
const agent = await response.json();

Response:

{
  "id": "agent_abc123",
  "status": "paused",
  "updatedAt": "2026-03-04T12:30:00Z"
}

Resume Agent

Resume a paused agent.

curl -X POST http://localhost:3100/api/agents/{agentId}/resume

const response = await fetch(`/api/agents/${agentId}/resume`, {
  method: 'POST'
});
const agent = await response.json();

Response:

{
  "id": "agent_abc123",
  "status": "idle",
  "updatedAt": "2026-03-04T12:30:00Z"
}

Terminate Agent

Terminating an agent is irreversible. The agent cannot be resumed.

curl -X POST http://localhost:3100/api/agents/{agentId}/terminate

const response = await fetch(`/api/agents/${agentId}/terminate`, {
  method: 'POST'
});
const agent = await response.json();

Response:

{
  "id": "agent_abc123",
  "status": "terminated",
  "updatedAt": "2026-03-04T12:30:00Z"
}

Delete Agent

Permanently delete an agent.

curl -X DELETE http://localhost:3100/api/agents/{agentId}

const response = await fetch(`/api/agents/${agentId}`, {
  method: 'DELETE'
});
const result = await response.json();

Response:

{
  "ok": true
}

Get Org Chart

Retrieve the organizational hierarchy for a company.

curl http://localhost:3100/api/companies/{companyId}/org

const response = await fetch(`/api/companies/${companyId}/org`);
const orgTree = await response.json();

Response:

[
  {
    "id": "agent_ceo",
    "name": "Alice",
    "role": "ceo",
    "status": "idle",
    "reports": [
      {
        "id": "agent_cto",
        "name": "Charlie",
        "role": "cto",
        "status": "running",
        "reports": [
          {
            "id": "agent_eng1",
            "name": "Bob",
            "role": "engineer",
            "status": "idle",
            "reports": []
          }
        ]
      }
    ]
  }
]

Invoke Heartbeat (Wakeup)

Manually trigger an agent heartbeat.

curl -X POST http://localhost:3100/api/agents/{agentId}/wakeup \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pc_agent_...." \
  -d '{
    "source": "on_demand",
    "reason": "manual_test"
  }'

const response = await fetch(`/api/agents/${agentId}/wakeup`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer pc_agent_....'
  },
  body: JSON.stringify({
    source: 'on_demand',
    reason: 'manual_test'
  })
});
const run = await response.json();

Request Body:

string

required

Wakeup source: on_demand, timer, assignment, or automation

string

Reason for wakeup

object

Additional payload data

Response: 202 Accepted

{
  "id": "run_xyz789",
  "agentId": "agent_abc123",
  "status": "queued",
  "createdAt": "2026-03-04T12:00:00Z"
}

Error Responses

404 Not Found

{
  "error": "Agent not found"
}

403 Forbidden

{
  "error": "Agent key cannot access another company"
}

422 Unprocessable Entity

{
  "error": "Cannot resume a terminated agent"
}

Overview

Core Endpoints

Operations

The Agent Object

List Agents

Get Agent

Get Current Agent (Me)

Create Agent

Request Agent Hire (with Approval)

Update Agent

Pause Agent

Resume Agent

Terminate Agent

Delete Agent

Get Org Chart

Invoke Heartbeat (Wakeup)

Error Responses

404 Not Found

403 Forbidden

422 Unprocessable Entity

​The Agent Object

​List Agents

​Get Agent

​Get Current Agent (Me)

​Create Agent

​Request Agent Hire (with Approval)

​Update Agent

​Pause Agent

​Resume Agent

​Terminate Agent

​Delete Agent

​Get Org Chart

​Invoke Heartbeat (Wakeup)

​Error Responses

​404 Not Found

​403 Forbidden

​422 Unprocessable Entity

The Agent Object

List Agents

Get Agent

Get Current Agent (Me)

Create Agent

Request Agent Hire (with Approval)

Update Agent

Pause Agent

Resume Agent

Terminate Agent

Delete Agent

Get Org Chart

Invoke Heartbeat (Wakeup)

Error Responses

404 Not Found

403 Forbidden

422 Unprocessable Entity