​
Tasks API

The Tasks API allows you to manage tasks in the Bytebot agent system. It’s available at http://localhost:9991/tasks when running the full agent setup.

​
Task Model

{
  id: string;
  description: string; 
  status: 'PENDING' | 'IN_PROGRESS' | 'NEEDS_HELP' | 'NEEDS_REVIEW' | 'COMPLETED' | 'CANCELLED' | 'FAILED';
  priority: 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT';
  createdAt: string; 
  updatedAt: string; 
}

​
Endpoints

​
Create Task

Create a new task for the agent to process.

POST /tasks

Create a new task

​
Request Body

{
  "description": "This is a description of the task",
  "priority": "MEDIUM" // Optional: LOW, MEDIUM, HIGH, URGENT
}

​
With File Upload

To upload files with a task, use multipart/form-data: 
curl -X POST http://localhost:9991/tasks \
  -F "description=Analyze the uploaded contracts and extract key terms" \
  -F "priority=HIGH" \
  -F "[email protected]" \
  -F "[email protected]"
Uploaded files are automatically saved to the desktop and can be referenced in the task description.

​
Response

{
  "id": "task-123",
  "description": "This is a description of the task",
  "status": "PENDING",
  "priority": "MEDIUM",
  "createdAt": "2025-04-14T12:00:00Z",
  "updatedAt": "2025-04-14T12:00:00Z"
}

​
Get All Tasks

Retrieve a list of all tasks.

GET /tasks

Get all tasks

​
Response

[
  {
    "id": "task-123",
    "description": "This is a description of the task",
    "status": "PENDING",
    "priority": "MEDIUM",
    "createdAt": "2025-04-14T12:00:00Z",
    "updatedAt": "2025-04-14T12:00:00Z"
  },
  // ...more tasks
]

​
Get In-Progress Task

Retrieve the currently in-progress task, if any.

GET /tasks/in-progress

Get the currently in-progress task

​
Response

{
  "id": "task-123",
  "description": "This is a description of the task",
  "status": "IN_PROGRESS",
  "priority": "MEDIUM",
  "createdAt": "2025-04-14T12:00:00Z",
  "updatedAt": "2025-04-14T12:00:00Z"
}
If no task is in progress, the response will be null.

​
Get Task by ID

Retrieve a specific task by its ID.

GET /tasks/:id

Get a task by ID

​
Response

{
  "id": "task-123",
  "description": "This is a description of the task",
  "status": "PENDING",
  "priority": "MEDIUM",
  "createdAt": "2025-04-14T12:00:00Z",
  "updatedAt": "2025-04-14T12:00:00Z",
  "messages": [
    {
      "id": "msg-456",
      "content": [
        {
          "type": "text",
          "text": "This is a message"
        }
      ],
      "role": "USER",
      "taskId": "task-123",
      "createdAt": "2025-04-14T12:05:00Z",
      "updatedAt": "2025-04-14T12:05:00Z"
    }
    // ...more messages
  ]
}

​
Update Task

Update an existing task.

PATCH /tasks/:id

Update a task

​
Request Body

{
  "status": "COMPLETED", 
  "priority": "HIGH" 
}

​
Response

{
  "id": "task-123",
  "description": "This is a description of the task",
  "status": "COMPLETED",
  "priority": "HIGH",
  "createdAt": "2025-04-14T12:00:00Z",
  "updatedAt": "2025-04-14T12:01:00Z"
}

​
Delete Task

Delete a task.

DELETE /tasks/:id

Delete a task

​
Response

Status code 204 No Content with an empty response body.

​
Message Content Structure

Messages in the Bytebot agent system use a content block structure compatible with Anthropic’s Claude API: 
type MessageContent = MessageContentBlock[];

interface MessageContentBlock {
  type: string;  
  [key: string]: any;  
}

interface TextContentBlock {
  type: "text";
  text: string;
}

interface ImageContentBlock {
  type: "image";
  source: {
    type: "base64";
    media_type: string;  
    data: string;  
  };
}

​
Error Responses

The API may return the following error responses:
Status CodeDescription
400Bad Request - Invalid parameters
404Not Found - Resource does not exist
500Internal Server Error - Server side error
Example error response: 
{
  "statusCode": 404,
  "message": "Task with ID task-123 not found",
  "error": "Not Found"
}

​
Code Examples

const axios = require('axios');

async function createTask(description) {
  const response = await axios.post('http://localhost:9991/tasks', {
    description
  });
  return response.data;
}

async function findInProgressTask() {
  const response = await axios.get('http://localhost:9991/tasks/in-progress');
  return response.data;
}

// Example usage
async function main() {
  // Create a new task
  const task = await createTask('Compare React, Vue, and Angular for a new project');
  console.log('Created task:', task);
  
  // Get current in-progress task
  const inProgressTask = await findInProgressTask();
  console.log('In progress task:', inProgressTask);
}