> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vambe.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Update an existing task

> Updates an existing task by ID. Only the fields provided in the request body will be updated. All fields are optional for updates.

## Overview

Update an existing task by its ID. All fields are optional - only include the fields you want to update. The task can be updated to change its title, description, status, assignees, due date, priority, or associated entities.

Use this endpoint to modify task details, reassign tasks, update completion status, or adjust deadlines.

## Use Cases

* **Task Status Updates**: Mark tasks as complete or change their workflow status
* **Reassignment**: Transfer tasks between team members
* **Deadline Management**: Adjust due dates and times as priorities shift
* **Priority Changes**: Update task priority based on changing business needs
* **Content Updates**: Modify task title or description
* **Association Updates**: Link or unlink tasks from contacts/customers

## Authentication

This endpoint requires authentication using an API key. Include your API key in the request header:

```
x-api-key: your_api_key_here
```

## Path Parameters

| Parameter | Type          | Required | Description                    |
| --------- | ------------- | -------- | ------------------------------ |
| `id`      | string (UUID) | Yes      | The UUID of the task to update |

## Request Body

All fields are optional. Only include the fields you want to update:

| Field               | Type           | Required | Description                                                                                 |
| ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------- |
| `title`             | string         | No       | Task title (minimum 1 character)                                                            |
| `description`       | string \| null | No       | Detailed description of the task                                                            |
| `newStatusPosition` | number         | No       | Update status by position in the status configuration (alternative to newStatusName)        |
| `newStatusName`     | string         | No       | Update status by name (e.g., "Pendiente", "En Progreso") (alternative to newStatusPosition) |
| `dueDate`           | string \| null | No       | Due date (ISO 8601 format: YYYY-MM-DD or full datetime). Set to null to remove due date     |
| `dueTime`           | string \| null | No       | Due time (HH:MM format, e.g., "14:30")                                                      |
| `timezone`          | string \| null | No       | Timezone for due date (e.g., "America/Santiago")                                            |
| `responsibleIds`    | string\[]      | No       | Array of user IDs to assign as responsible (replaces all existing assignees)                |
| `aiContactId`       | string \| null | No       | Associated contact ID                                                                       |
| `aiCustomerId`      | string \| null | No       | Associated customer ID                                                                      |
| `priority`          | string         | No       | Task priority: "0" (low), "1" (medium), or "2" (high)                                       |

**Note**: To update the task status, use either `newStatusPosition` or `newStatusName`. You cannot use both at the same time.

## Response Structure

Returns the updated task object:

### Task Object

| Field                   | Type           | Description                                          |
| ----------------------- | -------------- | ---------------------------------------------------- |
| `id`                    | string (UUID)  | Unique identifier for the task                       |
| `title`                 | string         | Task title                                           |
| `description`           | string         | Detailed description of the task                     |
| `due_timezone`          | string \| null | Timezone for the due date (e.g., "America/Santiago") |
| `due_at`                | string \| null | Due date and time (ISO 8601 format)                  |
| `is_all_day`            | boolean        | Whether the task is an all-day task                  |
| `created_at`            | string         | Task creation date (ISO 8601 format)                 |
| `ai_contact_id`         | string \| null | Associated contact ID if applicable                  |
| `ai_customer_id`        | string \| null | Associated customer ID if applicable                 |
| `task_status_config_id` | string (UUID)  | ID of the status configuration                       |
| `priority`              | number         | Task priority: 0 (low), 1 (medium), or 2 (high)      |
| `creator_id`            | string (UUID)  | ID of the user who created the task                  |
| `task_responsibles`     | array          | Array of responsible user objects                    |
| `status_config`         | object \| null | Custom status configuration object                   |

## Example Request - Mark Task as Complete

```bash theme={null}
curl -X PUT 'https://api.vambe.me/api/public/tasks/123e4567-e89b-12d3-a456-426614174000' \
  -H 'x-api-key: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "newStatusName": "Completado"
  }'
```

**Alternative using position:**

```bash theme={null}
curl -X PUT 'https://api.vambe.me/api/public/tasks/123e4567-e89b-12d3-a456-426614174000' \
  -H 'x-api-key: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "newStatusPosition": 3
  }'
```

## Example Request - Update Multiple Fields

```bash theme={null}
curl -X PUT 'https://api.vambe.me/api/public/tasks/123e4567-e89b-12d3-a456-426614174000' \
  -H 'x-api-key: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Updated: Follow up with customer",
    "description": "Updated description with new information",
    "dueDate": "2025-10-26T15:00:00.000Z",
    "dueTime": "15:00",
    "timezone": "America/Santiago",
    "priority": "2",
    "responsibleIds": ["228d7a0d-9072-4ca8-939b-959b75cc606a", "338e8b1e-8183-5db9-a4ab-a6ab86dd717b"]
  }'
```

## Example Response

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Updated: Follow up with customer",
  "description": "Updated description with new information",
  "due_timezone": "America/Santiago",
  "due_at": "2025-10-26T15:00:00.000Z",
  "is_all_day": false,
  "created_at": "2025-10-20T10:30:00.000Z",
  "ai_contact_id": "contact-uuid-123",
  "ai_customer_id": null,
  "task_status_config_id": "status-uuid-789",
  "priority": 2,
  "creator_id": "user-uuid-456",
  "task_responsibles": [
    {
      "responsible_id": "228d7a0d-9072-4ca8-939b-959b75cc606a"
    },
    {
      "responsible_id": "338e8b1e-8183-5db9-a4ab-a6ab86dd717b"
    }
  ],
  "status_config": {
    "id": "status-uuid-789",
    "name": "Pendiente",
    "color": "#60a5fa",
    "type": "initial",
    "order": 1
  }
}
```

## Common Use Cases

### 1. Mark Task as Complete

```javascript theme={null}
const completeTask = async (taskId, completedStatusName) => {
  const response = await fetch(
    `https://api.vambe.me/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        newStatusName: completedStatusName,
      }),
    },
  );

  return await response.json();
};

// Example usage - using status name
const completedTask = await completeTask(
  '123e4567-e89b-12d3-a456-426614174000',
  'Completado',
);

// Alternative - using status position
const completeTaskByPosition = async (taskId, statusPosition) => {
  const response = await fetch(
    `https://api.vambe.me/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        newStatusPosition: statusPosition,
      }),
    },
  );

  return await response.json();
};
```

### 2. Reassign Task to Different User

```javascript theme={null}
const reassignTask = async (taskId, newResponsibleId) => {
  const response = await fetch(
    `https://api.vambe.me/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        responsibleIds: [newResponsibleId],
      }),
    },
  );

  return await response.json();
};

// Example usage
const reassignedTask = await reassignTask(
  '123e4567-e89b-12d3-a456-426614174000',
  'new-agent-uuid',
);
```

### 3. Update Task Priority

```javascript theme={null}
const updateTaskPriority = async (taskId, newPriority) => {
  const response = await fetch(
    `https://api.vambe.me/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        priority: newPriority, // "0", "1", or "2"
      }),
    },
  );

  return await response.json();
};

// Example usage
const urgentTask = await updateTaskPriority(
  '123e4567-e89b-12d3-a456-426614174000',
  '2', // High priority
);
```

### 4. Extend Task Deadline

```javascript theme={null}
const extendDeadline = async (taskId, newDueDate, newDueTime, timezone) => {
  const response = await fetch(
    `https://api.vambe.me/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        dueDate: newDueDate,
        dueTime: newDueTime,
        timezone: timezone,
      }),
    },
  );

  return await response.json();
};

// Example usage - Extend by 2 days
const extendedTask = await extendDeadline(
  '123e4567-e89b-12d3-a456-426614174000',
  '2025-10-28T14:00:00.000Z',
  '14:00',
  'America/Santiago',
);
```

### 5. Add Additional Team Members

```javascript theme={null}
const addTeamMembers = async (taskId, currentResponsibleIds, newMemberIds) => {
  const allResponsibleIds = [...currentResponsibleIds, ...newMemberIds];

  const response = await fetch(
    `https://api.vambe.me/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        responsibleIds: allResponsibleIds,
      }),
    },
  );

  return await response.json();
};

// Example usage
const updatedTask = await addTeamMembers(
  '123e4567-e89b-12d3-a456-426614174000',
  ['existing-agent-uuid-1'],
  ['new-agent-uuid-2', 'new-agent-uuid-3'],
);
```

### 6. Update Task Description

```javascript theme={null}
const updateTaskDescription = async (taskId, newDescription) => {
  const response = await fetch(
    `https://api.vambe.me/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        description: newDescription,
      }),
    },
  );

  return await response.json();
};

// Example usage
const updatedTask = await updateTaskDescription(
  '123e4567-e89b-12d3-a456-426614174000',
  'Updated with additional context from meeting notes',
);
```

### 7. Link Task to Contact

```javascript theme={null}
const linkTaskToContact = async (taskId, contactId) => {
  const response = await fetch(
    `https://api.vambe.me/api/public/tasks/${taskId}`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        aiContactId: contactId,
      }),
    },
  );

  return await response.json();
};

// Example usage
const linkedTask = await linkTaskToContact(
  '123e4567-e89b-12d3-a456-426614174000',
  'contact-uuid-789',
);
```

### 8. Bulk Update Task Status

```javascript theme={null}
const bulkUpdateTaskStatus = async (taskIds, newStatusName) => {
  const updatePromises = taskIds.map((taskId) =>
    fetch(`https://api.vambe.me/api/public/tasks/${taskId}`, {
      method: 'PUT',
      headers: {
        'x-api-key': 'your_api_key_here',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        newStatusName: newStatusName,
      }),
    }).then((res) => res.json()),
  );

  return await Promise.all(updatePromises);
};

// Example usage - Mark multiple tasks as complete
const completedTasks = await bulkUpdateTaskStatus(
  ['task-uuid-1', 'task-uuid-2', 'task-uuid-3'],
  'Completado',
);
```

## Validation Rules

### Task ID

* **Required**: Yes (in URL path)
* **Format**: Valid UUID
* **Note**: Task must exist and belong to your organization

### Title

* **Required**: No (only if updating)
* **Minimum length**: 1 character (if provided)
* **Type**: String

### Status Updates

You can update the task status using one of two methods:

**Option 1: By Status Name**

* **Field**: `newStatusName`
* **Type**: String
* **Example**: "Pendiente", "En Progreso", "Completado"
* **Note**: Must match an existing status name in your organization

**Option 2: By Status Position**

* **Field**: `newStatusPosition`
* **Type**: Number
* **Example**: 0, 1, 2, 3
* **Note**: Represents the position/order of the status in your status configuration

**Important**: You can only use one method at a time - either `newStatusName` OR `newStatusPosition`, not both.

### Responsible IDs

* **Required**: No (only if updating)
* **Type**: Array of strings (UUIDs)
* **Note**: Must be valid user IDs from your organization
* **Note**: Replaces all existing assignees (not additive)

### Priority

* **Required**: No (only if updating)
* **Type**: String
* **Allowed values**: "0" (low), "1" (medium), "2" (high)
* **Note**: The value is sent as a string but stored as an integer (0, 1, or 2)

## Error Responses

| Status Code | Description                                      |
| ----------- | ------------------------------------------------ |
| 400         | Bad Request - Invalid task ID or request body    |
| 401         | Unauthorized - Invalid or missing API key        |
| 404         | Not Found - Task not found or invalid references |
| 500         | Internal Server Error - Something went wrong     |

### Common Error Examples

```json theme={null}
{
  "statusCode": 404,
  "message": "Task not found"
}
```

```json theme={null}
{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "field": "priority",
      "message": "Priority must be one of: low, medium, high"
    }
  ]
}
```

## Best Practices

1. **Partial Updates**: Only send the fields you want to update - no need to send the entire object
2. **Responsible IDs**: When updating responsibleIds, include ALL users who should be assigned (it replaces, not appends)
3. **Status Updates**: Use `newStatusName` or `newStatusPosition` to update status - don't use both at the same time
4. **Status Validation**: Verify the status name/position exists in your organization before updating
5. **Optimistic UI**: Update UI optimistically and rollback on error for better user experience
6. **Timezone Consistency**: When updating due dates, always include timezone for accuracy
7. **Remove Due Date**: Set `dueDate` to `null` to remove the due date from a task
8. **Priority Format**: Use "0", "1", or "2" for priority (not "low", "medium", "high")
9. **Audit Trail**: Consider logging updates for compliance and debugging
10. **Concurrent Updates**: Be aware of potential race conditions when multiple users update the same task

## Performance Tips

* **Batch Updates**: Group related updates into a single request when possible
* **Conditional Updates**: Check if the value actually changed before making an API call
* **Error Handling**: Implement retry logic with exponential backoff for transient failures
* **Validation**: Validate data on the client side before making API calls

## Important Notes

* **Immutable Fields**: Some fields like `id`, `created_at`, and `creator_id` cannot be updated
* **Organization Scoped**: You can only update tasks that belong to your organization
* **Permission Based**: Users may need appropriate permissions to update certain tasks
* **Status Update Methods**: Use either `newStatusName` OR `newStatusPosition`, not both
* **Cascading Effects**: Changing status may trigger automated actions or notifications
* **Responsible IDs Replacement**: The responsibleIds array replaces all existing assignees - it does not add to them
* **Remove Due Date**: Set `dueDate` to `null` to remove the due date from a task
* **Priority Format**: Priority is sent as a string ("0", "1", "2") but returned as an integer (0, 1, 2) in the response

## Related Endpoints

* [GET /api/public/tasks](/reference/tasks/get-tasks) - Get tasks by filters
* [POST /api/public/tasks](/reference/tasks/create-task) - Create a new task
* [DELETE /api/public/tasks/{id}](/reference/tasks/delete-task) - Delete a task
* [GET /api/public/team-members/all](/reference/team-members/get-all-team-members) - Get team members for assignment

## Webhook Events

Updating a task may trigger webhook events such as:

* `task.updated` - When any task field is updated
* `task.completed` - When task status changes to completed
* `task.reassigned` - When responsible users change

Configure webhooks to receive real-time notifications of task updates.


## OpenAPI

````yaml put /api/public/tasks/{id}
openapi: 3.0.0
info:
  title: Vambe AI API
  description: Vambe AI documentation
  version: '1.0'
  contact: {}
servers:
  - url: https://api.vambe.me
    description: Production Server
security: []
tags:
  - name: Vambe AI
    description: ''
paths:
  /api/public/tasks/{id}:
    put:
      tags:
        - tasks
      summary: Update an existing task
      description: >-
        Updates an existing task by ID. Only the fields provided in the request
        body will be updated. All fields are optional for updates.
      operationId: TaskPublicController_update
      parameters:
        - name: id
          required: true
          in: path
          description: The UUID of the task to update
          schema:
            format: uuid
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskPublicDto'
      responses:
        '200':
          description: Task updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponseDto'
        '400':
          description: Invalid task ID or request body
        '401':
          description: Unauthorized - Invalid or missing authentication token
        '404':
          description: Task not found
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponseDto'
components:
  schemas:
    UpdateTaskPublicDto:
      type: object
      properties:
        title:
          type: string
          minLength: 1
        description:
          type: string
          nullable: true
        dueDate:
          type: string
          nullable: true
        dueTime:
          type: string
          nullable: true
        timezone:
          type: string
          nullable: true
        responsibleIds:
          type: array
          items:
            type: string
        aiContactId:
          type: string
          nullable: true
        aiCustomerId:
          type: string
          nullable: true
        priority:
          type: string
          enum:
            - '0'
            - '1'
            - '2'
        associateToCalendar:
          default: false
          type: boolean
        newStatusPosition:
          type: number
        newStatusName:
          type: string
    TaskResponseDto:
      type: object
      properties: {}

````