Steps API

The Steps API manages individual steps within tasks. Steps represent granular work items that are executed by specific AI agents as part of larger task workflows.

Overview

Steps in Dispersl are:

Atomic: Individual units of work within a task
Agent-specific: Executed by specialized AI agents
Trackable: Full execution monitoring and history
Coordinated: Part of larger multi-step workflows

Endpoints

Get All Steps

GET /steps

Retrieves all steps for the authenticated user across all tasks.

Headers

Authorization: Bearer YOUR_API_KEY

Response

{
  "status": "success",
  "message": "Steps retrieved successfully",
  "data": [
    {
      "id": "step_xyz789",
      "task_id": "task_abc123",
      "name": "Generate API endpoints",
      "status": "completed",
      "created_at": "2024-01-15T10:35:00Z",
      "updated_at": "2024-01-15T11:20:00Z"
    },
    {
      "id": "step_uvw456",
      "task_id": "task_abc123", 
      "name": "Write unit tests",
      "status": "in_progress",
      "created_at": "2024-01-15T11:25:00Z",
      "updated_at": "2024-01-15T11:45:00Z"
    }
  ]
}

Get Step by ID

GET /steps/{id}

Retrieves a specific step by its ID.

Parameters

id (path, required): Step ID

Headers

Authorization: Bearer YOUR_API_KEY

Response

{
  "status": "success",
  "message": "Step retrieved successfully",
  "data": [
    {
      "id": "step_xyz789",
      "task_id": "task_abc123",
      "name": "Generate API endpoints",
      "status": "completed",
      "created_at": "2024-01-15T10:35:00Z",
      "updated_at": "2024-01-15T11:20:00Z"
    }
  ]
}

Edit Step

POST /steps/{id}/edit

Edits a specific step by its ID.

Parameters

id (path, required): Step ID

Headers

Authorization: Bearer YOUR_API_KEY

Request Body

{
  "name": "Generate REST API endpoints with validation",
  "status": "paused"
}

Response

{
  "status": "success",
  "message": "Step updated successfully",
  "data": [
    {
      "id": "step_xyz789",
      "task_id": "task_abc123",
      "name": "Generate REST API endpoints with validation",
      "status": "paused",
      "created_at": "2024-01-15T10:35:00Z",
      "updated_at": "2024-01-15T12:00:00Z"
    }
  ]
}

Cancel Step

DELETE /steps/{id}/cancel

Cancels and deletes a specific step by its ID.

Parameters

id (path, required): Step ID

Headers

Authorization: Bearer YOUR_API_KEY

Response

{
  "status": "success",
  "message": "Step cancelled successfully",
  "data": [
    {
      "id": "step_xyz789",
      "task_id": "task_abc123",
      "name": "Generate REST API endpoints with validation",
      "status": "cancelled",
      "created_at": "2024-01-15T10:35:00Z",
      "updated_at": "2024-01-15T12:15:00Z"
    }
  ]
}

Step Status Values

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

Step Types by Agent

Code Agent Steps

Generate API endpoints
Create database models
Implement business logic
Add error handling
Optimize performance

Test Agent Steps

Write unit tests
Create integration tests
Generate test data
Run test suites
Validate coverage

Git Agent Steps

Create feature branch
Commit changes
Merge branches
Tag releases
Manage conflicts

Documentation Agent Steps

Generate API docs
Create README files
Write code comments
Update changelogs
Create user guides

Step Coordination

Steps within a task are coordinated to ensure proper execution order:

Best Practices

Step Management

Monitor progress: Track step status regularly
Handle dependencies: Ensure prerequisite steps complete first
Error recovery: Implement retry logic for failed steps
Resource cleanup: Cancel unnecessary steps to free resources

Error Handling

async function monitorStep(stepId) {
  const maxRetries = 3;
  let retries = 0;
  
  while (retries < maxRetries) {
    try {
      const response = await fetch(`/api/steps/${stepId}`, {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      });
      
      const step = await response.json();
      
      if (step.data[0].status === 'completed') {
        return step.data[0];
      } else if (step.data[0].status === 'failed') {
        throw new Error(`Step failed: ${step.data[0].name}`);
      }
      
      // Wait before checking again
      await new Promise(resolve => setTimeout(resolve, 5000));
      
    } catch (error) {
      retries++;
      if (retries >= maxRetries) {
        throw error;
      }
      await new Promise(resolve => setTimeout(resolve, 1000 * retries));
    }
  }
}

Integration with Tasks

Steps are automatically created when tasks are broken down by the Plan Agent:

# Create a task that generates multiple steps
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 complete user authentication system",
    "model": "anthropic/claude-3-sonnet",
    "task_id": "task_auth_system"
  }'
 
# Monitor the generated steps
curl -X GET https://api.dispersl.com/v1/steps \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses

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

Webhooks (Coming Soon)

Subscribe to step events for real-time updates:

{
  "event": "step.completed",
  "step_id": "step_xyz789",
  "task_id": "task_abc123",
  "timestamp": "2024-01-15T11:20:00Z",
  "data": {
    "status": "completed",
    "duration": "45m",
    "agent": "code_agent"
  }
}

Tasks History