REST Tasks API Reference

The Tasks API provides RESTful endpoints for creating, managing, and monitoring agent tasks. Tasks represent units of work assigned to agents, with step-by-step progress tracking and human-in-the-loop support.

Base URL: https://platform.ap.xpressai.cloud

Authentication: Authorization: Bearer <platform_token>

---

Endpoints

Method	Endpoint	Description
GET	/api/tasks	List tasks
POST	/api/tasks	Create a task
PUT	/api/tasks/{id}/status	Update task status
PUT	/api/tasks/{id}/agent	Assign or unassign an agent
PUT	/api/tasks/{id}/steps/{stepNum}/status	Update individual step status
POST	/api/tasks/{id}/respond	Submit a user response (for Waiting tasks)
DELETE	/api/tasks/{id}	Delete a task
DELETE	/api/tasks/done	Delete all completed tasks
POST	/api/agent_callback/{id}	Internal: agent callback for task updates

---

Task Object

{
  "id": 123,
  "agent_id": 1,
  "agent_name": "personal-assistant",
  "summary": "Research competitor pricing",
  "details": "Focus on enterprise tier comparison",
  "steps": [
    {"title": "Gather pricing data", "status": "completed"},
    {"title": "Create comparison matrix", "status": "in_progress"}
  ],
  "status": "Doing",
  "source": "user",
  "taskType": "standard",
  "current_step_num": 1,
  "is_active": true,
  "is_waiting": false,
  "waitingDetails": null
}

Task Statuses

Status	Description
Backlog	Created but not yet started
Todo	Queued for an agent to pick up
Doing	Agent is actively working on it
Waiting	Agent needs human input to continue
Done	Task completed successfully
Failed	Task failed during execution

---

List Tasks

GET /api/tasks

Returns all tasks. Optionally filter by status.

Query Parameters:

Parameter	Type	Required	Description
status	string	No	Filter by task status (e.g., Doing)

Example:

# List all tasks
curl https://platform.ap.xpressai.cloud/api/tasks \
  -H "Authorization: Bearer YOUR_TOKEN"

# List only active tasks
curl "https://platform.ap.xpressai.cloud/api/tasks?status=Doing" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

[
  {
    "id": 123,
    "agent_id": 1,
    "agent_name": "personal-assistant",
    "summary": "Research competitor pricing",
    "details": "Focus on enterprise tier comparison",
    "steps": [],
    "status": "Doing",
    "current_step_num": 0,
    "is_active": true,
    "is_waiting": false
  }
]

---

Create Task

POST /api/tasks

Create a new task and optionally assign it to an agent.

Request Body:

Field	Type	Required	Description
summary	string	Yes	Short description of the task
details	string	No	Detailed instructions
steps	array	No	List of step objects with title fields
agent_id	integer	No	Agent to assign the task to

Example:

curl -X POST https://platform.ap.xpressai.cloud/api/tasks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Research competitor pricing",
    "details": "Focus on enterprise tier comparison",
    "steps": [
      {"title": "Gather pricing data"},
      {"title": "Create comparison matrix"},
      {"title": "Write summary report"}
    ],
    "agent_id": 1
  }'

Response:

{
  "id": 124,
  "agent_id": 1,
  "agent_name": "personal-assistant",
  "summary": "Research competitor pricing",
  "details": "Focus on enterprise tier comparison",
  "steps": [
    {"title": "Gather pricing data", "status": "pending"},
    {"title": "Create comparison matrix", "status": "pending"},
    {"title": "Write summary report", "status": "pending"}
  ],
  "status": "Todo",
  "current_step_num": 0,
  "is_active": false,
  "is_waiting": false
}

---

Update Task Status

PUT /api/tasks/{id}/status

Change the status of a task.

Path Parameters:

Parameter	Type	Description
id	integer	Task ID

Request Body:

Field	Type	Required	Description
status	string	Yes	New status (Backlog, Todo, Doing, Waiting, Done, Failed)

Example:

curl -X PUT https://platform.ap.xpressai.cloud/api/tasks/123/status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "Done"}'

---

Assign / Unassign Agent

PUT /api/tasks/{id}/agent

Assign a task to an agent or remove the current assignment.

Request Body:

Field	Type	Required	Description
agent_id	integer	No	Agent ID to assign, or null to unassign

Example:

# Assign to agent
curl -X PUT https://platform.ap.xpressai.cloud/api/tasks/123/agent \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 2}'

# Unassign
curl -X PUT https://platform.ap.xpressai.cloud/api/tasks/123/agent \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": null}'

---

Respond to Waiting Task

POST /api/tasks/{id}/respond

Submit a user response when a task is in Waiting status. The agent will resume execution with the provided input.

Request Body:

Field	Type	Required	Description
response	string	Yes	The user's response to the agent's question

Example:

curl -X POST https://platform.ap.xpressai.cloud/api/tasks/123/respond \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"response": "Focus on the top 5 competitors only"}'

---

Delete Task

DELETE /api/tasks/{id}

Permanently delete a task.

Example:

curl -X DELETE https://platform.ap.xpressai.cloud/api/tasks/123 \
  -H "Authorization: Bearer YOUR_TOKEN"

---

Update Step Status

PUT /api/tasks/{id}/steps/{stepNum}/status

Update the status of an individual step within a task.

Path Parameters:

Parameter	Type	Description
id	integer	Task ID
stepNum	integer	Step number (0-indexed)

Request Body:

Field	Type	Required	Description
status	string	Yes	New step status (pending, in_progress, completed, skipped)

Example:

curl -X PUT https://platform.ap.xpressai.cloud/api/tasks/123/steps/0/status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}'

---

Delete Completed Tasks

DELETE /api/tasks/done

Delete all tasks with status Done. Useful for cleaning up the task board.

Example:

curl -X DELETE https://platform.ap.xpressai.cloud/api/tasks/done \
  -H "Authorization: Bearer YOUR_TOKEN"

---

Agent Callback (Internal)

POST /api/agent_callback/{id}

info

This endpoint is used internally by agents to report task progress. It is not intended for direct use by API consumers.

Agents call this endpoint to update task steps, change status, or request human input. The callback is authenticated using Agent API Headers.