Tasks API

The Tasks API provides complete lifecycle management for agent tasks, from creation and assignment through execution, monitoring, and deliverable retrieval.

Base URL

https://api.do/agents/tasks

Overview

Task management includes:

Task Creation - Define work for agents or teams
Assignment - Assign to specific agents or let the system match
Monitoring - Track progress and status in real-time
Deliverables - Retrieve completed work and artifacts
Error Handling - Retry, escalate, or cancel failed tasks

Endpoints

Create Task

Create a new task.

POST /agents/tasks

Request Body

Field	Type	Required	Description
`task`	string	Yes	Task description
`agentId`	string	No	Specific agent (if not provided, auto-assigned)
`teamId`	string	No	Specific team
`context`	object	No	Additional context
`priority`	string	No	low, medium, high, urgent (default: medium)
`deadline`	string	No	ISO 8601 deadline
`deliverables`	string[]	No	Expected deliverable types
`budget`	object	No	Budget constraints

Example Request

curl -X POST "https://api.do/agents/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Analyze Q4 revenue trends and create executive report",
    "agentId": "amy",
    "context": {
      "dataSource": "revenue_q4_2024.csv",
      "focusAreas": ["growth", "churn", "expansion"],
      "targetAudience": "C-suite executives"
    },
    "priority": "high",
    "deadline": "2024-10-30T17:00:00Z",
    "deliverables": ["pdf-report", "presentation", "data-analysis"]
  }'

Example Response

{
  "success": true,
  "data": {
    "taskId": "task_abc123",
    "status": "pending",
    "task": "Analyze Q4 revenue trends and create executive report",
    "agentId": "amy",
    "agentName": "Amy",
    "priority": "high",
    "deadline": "2024-10-30T17:00:00Z",
    "estimatedCompletion": "2024-10-28T15:00:00Z",
    "estimatedDuration": "4 hours",
    "deliverables": ["pdf-report", "presentation", "data-analysis"],
    "trackingUrl": "https://api.do/agents/tasks/task_abc123",
    "createdAt": "2024-10-27T18:00:00Z"
  },
  "metadata": {
    "requestId": "req_task123",
    "timestamp": "2024-10-27T18:00:00Z"
  }
}

Get Task Status

Get the current status of a task.

GET /agents/tasks/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Task identifier

Example Request

curl -X GET "https://api.do/agents/tasks/task_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "taskId": "task_abc123",
    "status": "completed",
    "task": "Analyze Q4 revenue trends and create executive report",
    "agentId": "amy",
    "agentName": "Amy",
    "priority": "high",
    "progress": 100,
    "currentPhase": "completed",
    "timeline": {
      "createdAt": "2024-10-27T18:00:00Z",
      "startedAt": "2024-10-27T18:15:00Z",
      "completedAt": "2024-10-27T21:45:00Z",
      "duration": "3.5 hours"
    },
    "result": {
      "summary": "Q4 revenue grew 23% YoY to $12.5M. Key drivers: expansion revenue (+45%), reduced churn (2.1%).",
      "insights": ["Expansion revenue up 45% due to successful upselling", "Churn decreased from 3.2% to 2.1%", "New customer acquisition cost down 18%"],
      "recommendations": ["Double down on expansion playbook", "Invest in retention programs", "Optimize customer acquisition channels"]
    },
    "deliverables": [
      {
        "type": "pdf-report",
        "name": "Q4_Revenue_Analysis.pdf",
        "url": "https://storage.do/deliverables/task_abc123/report.pdf",
        "size": 2457600,
        "createdAt": "2024-10-27T21:30:00Z"
      },
      {
        "type": "presentation",
        "name": "Q4_Executive_Presentation.pptx",
        "url": "https://storage.do/deliverables/task_abc123/slides.pptx",
        "size": 5242880,
        "createdAt": "2024-10-27T21:40:00Z"
      },
      {
        "type": "data-analysis",
        "name": "Q4_Data_Analysis.xlsx",
        "url": "https://storage.do/deliverables/task_abc123/data.xlsx",
        "size": 1048576,
        "createdAt": "2024-10-27T21:20:00Z"
      }
    ],
    "quality": {
      "score": 0.94,
      "accuracy": 0.96,
      "completeness": 0.98,
      "clarity": 0.92
    }
  },
  "metadata": {
    "requestId": "req_task124",
    "timestamp": "2024-10-27T22:00:00Z"
  }
}

List Tasks

List tasks with optional filtering.

GET /agents/tasks

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status
`agentId`	string	No	Filter by agent
`teamId`	string	No	Filter by team
`priority`	string	No	Filter by priority
`startDate`	string	No	Filter by creation date (from)
`endDate`	string	No	Filter by creation date (to)
`limit`	number	No	Max results (default: 50)
`offset`	number	No	Pagination offset

Task Statuses

pending - Task created, waiting to start
assigned - Agent assigned, not yet started
in_progress - Agent actively working
blocked - Waiting on external dependency
review - Under review
completed - Successfully completed
failed - Task failed
cancelled - Task cancelled

Example Request

curl -X GET "https://api.do/agents/tasks?status=completed&agentId=amy&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Task

Update task details or status.

PATCH /agents/tasks/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Task identifier

Request Body

Field	Type	Required	Description
`priority`	string	No	Update priority
`deadline`	string	No	Update deadline
`context`	object	No	Add/update context
`notes`	string	No	Add notes

Example Request

curl -X PATCH "https://api.do/agents/tasks/task_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": "urgent",
    "deadline": "2024-10-29T12:00:00Z",
    "notes": "CEO needs this for board meeting"
  }'

Cancel Task

Cancel a task that's pending or in progress.

POST /agents/tasks/:id/cancel

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Task identifier

Request Body

Field	Type	Required	Description
`reason`	string	No	Cancellation reason

Example Request

curl -X POST "https://api.do/agents/tasks/task_abc123/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Requirements changed, will create new task"
  }'

Retry Task

Retry a failed task.

POST /agents/tasks/:id/retry

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Task identifier

Request Body

Field	Type	Required	Description
`reassign`	boolean	No	Assign to different agent (default: false)
`context`	object	No	Updated context

Example Request

curl -X POST "https://api.do/agents/tasks/task_abc123/retry" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reassign": true,
    "context": {
      "additionalData": "updated_dataset.csv"
    }
  }'

Get Task Deliverables

Get deliverables for a completed task.

GET /agents/tasks/:id/deliverables

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Task identifier

Example Request

curl -X GET "https://api.do/agents/tasks/task_abc123/deliverables" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "taskId": "task_abc123",
    "deliverables": [
      {
        "type": "pdf-report",
        "name": "Q4_Revenue_Analysis.pdf",
        "url": "https://storage.do/deliverables/task_abc123/report.pdf",
        "downloadUrl": "https://storage.do/download/xyz123",
        "size": 2457600,
        "format": "application/pdf",
        "createdAt": "2024-10-27T21:30:00Z"
      },
      {
        "type": "presentation",
        "name": "Q4_Executive_Presentation.pptx",
        "url": "https://storage.do/deliverables/task_abc123/slides.pptx",
        "downloadUrl": "https://storage.do/download/xyz124",
        "size": 5242880,
        "format": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
        "createdAt": "2024-10-27T21:40:00Z"
      }
    ]
  },
  "metadata": {
    "requestId": "req_task125",
    "timestamp": "2024-10-27T22:00:00Z"
  }
}

Provide Feedback

Provide feedback on a completed task.

POST /agents/tasks/:id/feedback

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Task identifier

Request Body

Field	Type	Required	Description
`rating`	number	Yes	Rating 1-5
`feedback`	string	No	Written feedback
`issues`	string[]	No	Issues encountered

Example Request

curl -X POST "https://api.do/agents/tasks/task_abc123/feedback" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5,
    "feedback": "Excellent analysis with actionable insights. Report was clear and well-structured.",
    "issues": []
  }'

Task Lifecycle

1. Created

Task is created and pending assignment.

const task = await $.Task.create({
  task: 'Analyze revenue',
  agentId: 'amy',
})
// Status: 'pending'

2. Assigned

Agent is assigned and preparing to start.

// System assigns agent and resources
// Status: 'assigned'

3. In Progress

Agent is actively working on the task.

const status = await $.Task.get(taskId)
// Status: 'in_progress'
// Progress: 45%

4. Completed

Task completed successfully with deliverables.

const result = await $.Task.get(taskId)
// Status: 'completed'
// Deliverables available

5. Failed (if issues occur)

Task failed and needs retry or escalation.

const failed = await $.Task.get(taskId)
// Status: 'failed'
// Error details provided

// Retry
await $.Task.retry(taskId)

TypeScript SDK Example

import { $ } from 'sdk.do'

// Create task
const task = await $.Task.create({
  task: 'Analyze Q4 revenue trends',
  agentId: 'amy',
  context: {
    dataSource: 'revenue_q4_2024.csv',
    focusAreas: ['growth', 'churn'],
  },
  priority: 'high',
  deadline: '2024-10-30T17:00:00Z',
  deliverables: ['pdf-report', 'presentation'],
})

// Get status
const status = await $.Task.get(task.taskId)
console.log(`Status: ${status.status}, Progress: ${status.progress}%`)

// List tasks
const tasks = await $.Task.list({
  status: 'completed',
  agentId: 'amy',
  limit: 10,
})

// Update task
await $.Task.update(task.taskId, {
  priority: 'urgent',
  notes: 'Need ASAP for board meeting',
})

// Cancel task
await $.Task.cancel(task.taskId, {
  reason: 'Requirements changed',
})

// Retry failed task
await $.Task.retry(task.taskId, {
  reassign: true,
})

// Get deliverables
const deliverables = await $.Task.deliverables(task.taskId)
deliverables.forEach((d) => {
  console.log(`${d.name}: ${d.downloadUrl}`)
})

// Provide feedback
await $.Task.feedback(task.taskId, {
  rating: 5,
  feedback: 'Excellent work!',
})

Python SDK Example

from do_sdk import Task

# Create task
task = Task.create(
    task='Analyze Q4 revenue trends',
    agent_id='amy',
    context={
        'dataSource': 'revenue_q4_2024.csv',
        'focusAreas': ['growth', 'churn']
    },
    priority='high',
    deadline='2024-10-30T17:00:00Z',
    deliverables=['pdf-report', 'presentation']
)

# Get status
status = Task.get(task.task_id)
print(f'Status: {status.status}, Progress: {status.progress}%')

# List tasks
tasks = Task.list(status='completed', agent_id='amy', limit=10)

# Get deliverables
deliverables = Task.deliverables(task.task_id)
for d in deliverables:
    print(f'{d.name}: {d.download_url}')

CLI Example

# Create task
do task create "Analyze Q4 revenue" \
  --agent amy \
  --data revenue_q4_2024.csv \
  --priority high \
  --deliverables report,presentation

# Get status
do task get task_abc123

# List tasks
do task list --status completed --agent amy

# Update task
do task update task_abc123 \
  --priority urgent \
  --notes "Need ASAP"

# Cancel task
do task cancel task_abc123 --reason "Requirements changed"

# Retry task
do task retry task_abc123 --reassign

# Get deliverables
do task deliverables task_abc123

# Provide feedback
do task feedback task_abc123 --rating 5 --text "Excellent!"

Best Practices

1. Provide Clear Task Descriptions

// Good: Specific and actionable
const task = await $.Task.create({
  task: 'Analyze Q4 revenue trends, identify growth drivers, create executive report with recommendations',
  context: {
    dataSource: 'revenue_q4_2024.csv',
    focusAreas: ['YoY growth', 'churn rate', 'expansion revenue'],
    targetAudience: 'C-suite executives',
    format: 'Executive summary with charts',
  },
})

// Bad: Vague
const task = await $.Task.create({
  task: 'Do revenue analysis',
})

2. Set Realistic Deadlines

// Good: Allow sufficient time
const task = await $.Task.create({
  task: 'Comprehensive market research report',
  deadline: new Date(Date.now() + 5 * 24 * 60 * 60 * 1000), // 5 days
})

// Bad: Unrealistic
const task = await $.Task.create({
  task: 'Comprehensive market research report',
  deadline: new Date(Date.now() + 1 * 60 * 60 * 1000), // 1 hour
})

3. Monitor Progress

const task = await $.Task.create({ task: '...', agentId: 'amy' })

// Poll for updates
const interval = setInterval(async () => {
  const status = await $.Task.get(task.taskId)
  console.log(`Progress: ${status.progress}%`)

  if (status.status === 'completed') {
    clearInterval(interval)
    console.log('Task completed!')
    const deliverables = await $.Task.deliverables(task.taskId)
  }
}, 30000) // Check every 30 seconds

4. Handle Errors Gracefully

try {
  const task = await $.Task.create({ task: '...', agentId: 'amy' })

  const status = await $.Task.get(task.taskId)

  if (status.status === 'failed') {
    console.log('Task failed:', status.error)

    // Retry with updated context
    await $.Task.retry(task.taskId, {
      reassign: true,
      context: { additionalInfo: '...' },
    })
  }
} catch (error) {
  console.error('Error:', error)
}

Agents API Overview - Complete API overview
Named Agents - Individual agents
Teams API - Multi-agent teams
Workflows API - Workflow orchestration

Support

Documentation - docs.do
API Status - status.do
Community - Discord
Support - support@do

Tasks API

On this page