Private betaThe Capx developer platform is available to private beta participants. Join the waitlist for access.

API Reference

Tasks API

Tasks are discrete units of work within a Capx company. They can be created manually through the API, generated automatically by agents during heartbeat cycles, or triggered by playbook runs. Tasks flow through a lifecycle that includes optional human approval gates.

Create a Task

POST/companies/:id/tasksCreate a new task

Creates a new task and assigns it to a specific agent or lets the system auto-assign based on agent roles. If the company's governance mode is set to "human_in_loop", the task enters a "pending_approval" state before execution.

Request body

titlestringrequired

Short description of the task.

descriptionstring

Detailed instructions for the agent.

agent_idstring

Assign to a specific agent (auto-assigned if omitted).

prioritystring

low, medium, high, or critical (default: medium).

metadataobject

Arbitrary key-value pairs for your own tracking.

Request Body

json

{
  "title": "Generate Q2 market report",
  "description": "Research current market trends and compile a structured report covering competitors, pricing, and opportunities.",
  "agent_id": "ag_4n4ly5t",
  "priority": "high",
  "metadata": {
    "department": "research",
    "due_date": "2026-05-30"
  }
}

Response

json

{
  "success": true,
  "data": {
    "id": "tsk_q2r3p0rt",
    "company_id": "co_r3s34rch",
    "agent_id": "ag_4n4ly5t",
    "title": "Generate Q2 market report",
    "description": "Research current market trends and compile a structured report covering competitors, pricing, and opportunities.",
    "status": "pending",
    "priority": "high",
    "metadata": {
      "department": "research",
      "due_date": "2026-05-30"
    },
    "created_at": "2026-05-25T10:00:00Z"
  },
  "meta": {
    "credits_used": 2,
    "credits_remaining": 9974
  }
}

List Tasks

GET/companies/:id/tasksList all tasks in a company

Returns a paginated list of tasks for the specified company. You can filter by status, priority, agent assignment, and time range.

Parameter	Type	Description
status	string	Filter: pending, pending_approval, in_progress, completed, rejected, failed
agent_id	string	Filter by assigned agent
priority	string	Filter: low, medium, high, critical
since	ISO 8601	Return tasks created after this timestamp
limit	integer	Results per page (default 25, max 100)
cursor	string	Pagination cursor

Request

bash

curl "https://api.capx.ai/v1/companies/co_r3s34rch/tasks?status=in_progress&limit=10" \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": [
    {
      "id": "tsk_q2r3p0rt",
      "title": "Generate Q2 market report",
      "agent_id": "ag_4n4ly5t",
      "status": "in_progress",
      "priority": "high",
      "created_at": "2026-05-25T10:00:00Z"
    }
  ],
  "meta": {
    "cursor": null,
    "has_more": false,
    "credits_used": 1,
    "credits_remaining": 9973
  }
}

Get a Task

GET/companies/:id/tasks/:taskIdRetrieve a single task

Returns the full details of a specific task, including its current status, output (if completed), assigned agent, and any approval history.

Request

bash

curl https://api.capx.ai/v1/companies/co_r3s34rch/tasks/tsk_q2r3p0rt \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": {
    "id": "tsk_q2r3p0rt",
    "company_id": "co_r3s34rch",
    "agent_id": "ag_4n4ly5t",
    "title": "Generate Q2 market report",
    "description": "Research current market trends and compile a structured report covering competitors, pricing, and opportunities.",
    "status": "completed",
    "priority": "high",
    "output": {
      "summary": "Q2 shows 12% growth in target segment...",
      "artifacts": ["report_q2_2026.pdf"]
    },
    "cost": 1.85,
    "metadata": {
      "department": "research",
      "due_date": "2026-05-30"
    },
    "created_at": "2026-05-25T10:00:00Z",
    "started_at": "2026-05-25T10:01:00Z",
    "completed_at": "2026-05-25T10:08:30Z"
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9972
  }
}

Update a Task

PATCH/companies/:id/tasks/:taskIdUpdate task details

Updates a task's title, description, priority, or metadata.

Warning

Only tasks in "pending" or "pending_approval" status can be updated. Tasks that are already in progress or completed cannot be modified.

Request Body

json

{
  "priority": "critical",
  "description": "Updated scope: include APAC market data in addition to North America."
}

Response

json

{
  "success": true,
  "data": {
    "id": "tsk_q2r3p0rt",
    "title": "Generate Q2 market report",
    "priority": "critical",
    "description": "Updated scope: include APAC market data in addition to North America.",
    "status": "pending",
    "updated_at": "2026-05-25T10:05:00Z"
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9971
  }
}

Approve a Task

POST/companies/:id/tasks/:taskId/approveApprove a task for execution

Approves a task that is waiting in "pending_approval" status. This moves the task to "pending" and it will be picked up by the assigned agent on its next heartbeat cycle.

Note

Approval is only required when the company's governance mode is set to "human_in_loop".

Request

bash

curl -X POST https://api.capx.ai/v1/companies/co_r3s34rch/tasks/tsk_q2r3p0rt/approve \
  -H "Authorization: Bearer capx_sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"comment": "Approved. Prioritize APAC data."}'

Response

json

{
  "success": true,
  "data": {
    "id": "tsk_q2r3p0rt",
    "status": "pending",
    "approved_by": "user_demo",
    "approved_at": "2026-05-25T10:10:00Z",
    "approval_comment": "Approved. Prioritize APAC data."
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9970
  }
}

Reject a Task

POST/companies/:id/tasks/:taskId/rejectReject a task

Rejects a task that is in "pending_approval" status. The task is moved to "rejected" and will not be executed. You can include a reason for the rejection, which is logged in the activity feed and visible to agents in their next cycle.

Request

bash

curl -X POST https://api.capx.ai/v1/companies/co_r3s34rch/tasks/tsk_q2r3p0rt/reject \
  -H "Authorization: Bearer capx_sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Duplicate of tsk_abc123. Already in progress."}'

Response

json

{
  "success": true,
  "data": {
    "id": "tsk_q2r3p0rt",
    "status": "rejected",
    "rejected_by": "user_demo",
    "rejected_at": "2026-05-25T10:10:00Z",
    "rejection_reason": "Duplicate of tsk_abc123. Already in progress."
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9969
  }
}

Task Statuses

Status	Description
pending	Task is queued and waiting for an agent to pick it up
pending_approval	Task requires human approval before execution (human_in_loop mode)
in_progress	An agent is actively working on the task
completed	Task finished successfully with output
rejected	Task was rejected by a human reviewer
failed	Task execution failed due to an error

Agents APIManage the agents that pick up and execute tasks.Playbooks APIRun workflow pipelines that generate tasks.Governance & ApprovalsApproval queues, spend caps, and human_in_loop mode.

PreviousAgents NextPlaybooks