Tasks API

The Tasks API manages the lifecycle of development tasks in Dispersl. Tasks represent high-level work items that can be broken down into multiple steps and executed by different AI agents.

Overview

Tasks in Dispersl are:

Coordinated: Managed across multiple AI agents
Trackable: Full lifecycle monitoring from creation to completion
Flexible: Can be edited, paused, or cancelled
Hierarchical: Contain multiple steps for complex workflows

Endpoints

Create New Task

POST /tasks/new

Creates a new task for the authenticated user.

Headers

Authorization: Bearer YOUR_API_KEY

Response

{
  "status": "success",
  "message": "Task created successfully",
  "data": [
    {
      "id": "task_abc123",
      "name": "Build REST API with Authentication",
      "status": "created",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Get All Tasks

GET /tasks

Retrieves all tasks for the authenticated user.

Headers

Authorization: Bearer YOUR_API_KEY

Response

{
  "status": "success",
  "message": "Tasks retrieved successfully",
  "data": [
    {
      "id": "task_abc123",
      "name": "Build REST API with Authentication",
      "status": "in_progress",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T11:45:00Z"
    },
    {
      "id": "task_def456",
      "name": "Generate Test Suite",
      "status": "completed",
      "created_at": "2024-01-14T09:15:00Z",
      "updated_at": "2024-01-14T12:30:00Z"
    }
  ]
}

Get Task by ID

GET /tasks/{id}

Retrieves a specific task by its ID.

Parameters

id (path, required): Task ID

Headers

Authorization: Bearer YOUR_API_KEY

Response

{
  "status": "success",
  "message": "Task retrieved successfully",
  "data": [
    {
      "id": "task_abc123",
      "name": "Build REST API with Authentication",
      "status": "in_progress",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T11:45:00Z"
    }
  ]
}

Edit Task

POST /tasks/{id}/edit

Edits a specific task by its ID.

Parameters

id (path, required): Task ID

Headers

Authorization: Bearer YOUR_API_KEY

Request Body

{
  "name": "Build REST API with Advanced Authentication",
  "status": "paused"
}

Response

{
  "status": "success",
  "message": "Task updated successfully",
  "data": [
    {
      "id": "task_abc123",
      "name": "Build REST API with Advanced Authentication",
      "status": "paused",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T12:00:00Z"
    }
  ]
}

Cancel Task

DELETE /tasks/{id}/cancel

Cancels and deletes a specific task by its ID.

Parameters

id (path, required): Task ID

Headers

Authorization: Bearer YOUR_API_KEY

Response

{
  "status": "success",
  "message": "Task cancelled successfully",
  "data": [
    {
      "id": "task_abc123",
      "name": "Build REST API with Advanced Authentication",
      "status": "cancelled",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T12:15:00Z"
    }
  ]
}

Task Status Values

Status	Description
`created`	Task has been created but not started
`in_progress`	Task is currently being executed
`paused`	Task execution has been paused
`completed`	Task has been successfully completed
`failed`	Task execution failed
`cancelled`	Task was cancelled by user

Task Lifecycle

Integration with Agents

Tasks are typically created and managed through agent interactions:

Creating a Task via Plan Agent

curl -X POST https://api.dispersl.com/v1/agent/plan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Build a user authentication system",
    "model": "anthropic/claude-3-sonnet",
    "task_id": "task_abc123"
  }'

Monitoring Task Progress

# Get task details
curl -X GET https://api.dispersl.com/v1/tasks/task_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
 
# Get task history
curl -X GET https://api.dispersl.com/v1/history/task_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

Task Naming

Use descriptive names that clearly indicate the task purpose
Include key technologies or frameworks when relevant
Keep names concise but informative

Task Management

Monitor regularly: Check task status and progress
Use meaningful IDs: Generate or use meaningful task identifiers
Handle failures: Implement retry logic for failed tasks
Clean up: Cancel or delete unnecessary tasks

Error Handling

async function createTask() {
  try {
    const response = await fetch('/api/tasks/new', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    const task = await response.json();
    return task.data[0];
  } catch (error) {
    console.error('Failed to create task:', error);
    throw error;
  }
}

Error Responses

400: Failed to verify api_key or token
401: No Bearer token provided
404: Task not found
500: Internal server error

Webhooks (Coming Soon)

Subscribe to task events for real-time updates:

{
  "event": "task.completed",
  "task_id": "task_abc123",
  "timestamp": "2024-01-15T12:30:00Z",
  "data": {
    "status": "completed",
    "duration": "2h 15m",
    "steps_completed": 8
  }
}

Authentication Steps