Automate Tasks via API

The platform UI is great for managing tasks by hand, but real automation means driving tasks programmatically. The Tasks REST API lets you create, list, update, and delete tasks from scripts, CI pipelines, or external applications. This tutorial covers every operation you need.

Prerequisites

• A platform token with task:read and task:write scopes (Authenticate with the API)
• At least one agent deployed in your project (Create Your First Agent)
• curl and jq installed on your machine

Steps

1. List tasks

Fetch all tasks in your project:

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

Filter by status to get only the tasks that are in progress:

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

Available status values:

Status	Meaning
Backlog	Queued but not started
Todo	Ready to be picked up
Doing	Agent is actively working on it
Waiting	Agent is blocked and needs human input
Done	Completed
Failed	Agent encountered an unrecoverable error

tip

Use the status query parameter to avoid pulling your entire task list on every poll. If you are building a dashboard, query status=Doing and status=Waiting to show only tasks that need attention.

2. Create a task with subtasks

Create a task and assign it to an agent. You need the agent's ID -- you can find it by listing your agents via GraphQL:

curl -X POST https://platform.ap.xpressai.cloud/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ agents { id name } }"}' | jq

The steps array defines subtasks that the agent works through sequentially:

curl -X POST https://platform.ap.xpressai.cloud/api/tasks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Analyze Q2 sales data",
    "details": "Pull data from CRM, identify trends, prepare executive summary",
    "agent_id": 1,
    "steps": [
      {"title": "Export CRM data"},
      {"title": "Run trend analysis"},
      {"title": "Write executive summary"}
    ]
  }'

The response includes the created task with its ID, which you'll use for subsequent operations.

3. Update task status

Move a task to a different status:

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"}'

You can transition a task to any valid status. Common transitions:

• Backlog -> Todo -- ready for the agent to start
• Todo -> Doing -- agent picks it up (usually automatic)
• Doing -> Waiting -- agent needs input from a human
• Waiting -> Doing -- human provides input, agent resumes
• Doing -> Done -- completed successfully
• Doing -> Failed -- something went wrong

4. Respond to a waiting task

When an agent sets a task to Waiting, it is blocked until a human (or another system) responds. Unblock it by posting a response:

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

The agent receives your response as a message in the task's conversation and resumes work. This is how you build human-in-the-loop workflows -- the agent does the heavy lifting, pauses when it needs a decision, and continues after you weigh in.

5. Delete a task

Remove a task entirely:

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

warning

Deletion is permanent. The task, its steps, and its conversation history are removed. If you just want to archive a completed task, set its status to Done instead.

6. Understand the task object

Here is the full shape of a task object returned by the API:

{
  "id": 123,
  "agent_id": 1,
  "agent_name": "Toby",
  "summary": "Analyze Q2 sales data",
  "details": "Pull data from CRM, identify trends, prepare executive summary",
  "steps": [
    {"id": 1, "title": "Export CRM data", "status": "Done"},
    {"id": 2, "title": "Run trend analysis", "status": "Doing"},
    {"id": 3, "title": "Write executive summary", "status": "Todo"}
  ],
  "conversation": [
    {"role": "user", "content": "Please start the analysis"},
    {"role": "assistant", "content": "I've exported the CRM data. Moving to trend analysis."}
  ],
  "status": "Doing",
  "current_step_num": 2,
  "is_active": true,
  "is_waiting": false,
  "waiting_details": null
}

Key fields:

Field	Type	Description
id	integer	Unique task identifier
agent_id	integer	ID of the assigned agent
agent_name	string	Display name of the assigned agent
summary	string	Short description (think of it as the task title)
details	string	Full description with context and instructions
steps	array	Ordered list of subtasks, each with id, title, and status
conversation	array	Message history between the user and agent for this task
status	string	Current task status (see table in Step 1)
current_step_num	integer	Index of the step the agent is currently working on
is_active	boolean	true if the task is in Doing status
is_waiting	boolean	true if the agent is blocked and needs human input
waiting_details	string or null	What the agent is waiting for (only set when is_waiting is true)

7. Build an automation script

Here is a practical example -- a bash script that creates a task, polls until it completes, and prints the result:

#!/bin/bash
TOKEN="$XPRESSAI_TOKEN"
BASE="https://platform.ap.xpressai.cloud/api"

# Create the task
TASK_ID=$(curl -s -X POST "$BASE/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Generate weekly report",
    "details": "Compile metrics from all data sources and produce a summary",
    "agent_id": 1,
    "steps": [
      {"title": "Gather metrics"},
      {"title": "Generate report"}
    ]
  }' | jq -r '.id')

echo "Created task $TASK_ID"

# Poll until done
while true; do
  STATUS=$(curl -s "$BASE/tasks/$TASK_ID" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')

  echo "Status: $STATUS"

  if [ "$STATUS" = "Done" ] || [ "$STATUS" = "Failed" ]; then
    break
  fi

  if [ "$STATUS" = "Waiting" ]; then
    echo "Agent is waiting for input -- check the platform UI"
  fi

  sleep 10
done

echo "Task $TASK_ID finished with status: $STATUS"

tip

When polling, use a reasonable interval (10-30 seconds). Most tasks take minutes, not milliseconds. For production integrations, consider reducing polling frequency or using the GraphQL subscription API if available in your deployment.

What you've done

• Listed tasks with status filtering
• Created a task with subtasks and assigned it to an agent
• Updated task status programmatically
• Responded to a waiting task to unblock an agent
• Deleted a task
• Learned the full task object structure
• Built a simple automation script with polling

Next steps

You now have the building blocks to drive the platform from code. Combine what you have learned across these developer tutorials -- API authentication, custom agents, custom tools, and task automation -- to build end-to-end workflows tailored to your team.

---

See also

• Task Statuses Reference
• Assign a Task
• Authenticate with the API
• Schedule a Recurring Job