> ## 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.

# Delete a task

> Soft deletes a task by ID. The task will be marked as deleted but not permanently removed from the database. Associated interactive notes will also be deleted.

## Overview

Delete a task by its ID. This is a soft delete operation - the task is marked as deleted but not permanently removed from the database. Associated interactive notes will also be deleted.

Use this endpoint to remove tasks that are no longer needed, clean up completed tasks, or manage task lifecycle.

## Use Cases

* **Task Cleanup**: Remove old or irrelevant tasks
* **Error Correction**: Delete tasks created by mistake
* **Workflow Management**: Remove tasks that are no longer applicable
* **Data Management**: Clean up test or duplicate tasks
* **User Requests**: Allow users to delete their own tasks
* **Automated Cleanup**: Periodically delete old completed tasks

## 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 delete |

## Response Structure

Returns a success status object:

| Field    | Type   | Description              |
| -------- | ------ | ------------------------ |
| `status` | string | Always returns "success" |

## Example Request

```bash theme={null}
curl -X DELETE 'https://api.vambe.me/api/public/tasks/123e4567-e89b-12d3-a456-426614174000' \
  -H 'x-api-key: your_api_key_here'
```

## Example Response

```json theme={null}
{
  "status": "success"
}
```

## Common Use Cases

### 1. Delete a Single Task

```javascript theme={null}
const deleteTask = async (taskId) => {
  const response = await fetch(
    `https://api.vambe.me/api/public/tasks/${taskId}`,
    {
      method: 'DELETE',
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const result = await response.json();
  return result.status === 'success';
};

// Example usage
const deleted = await deleteTask('123e4567-e89b-12d3-a456-426614174000');
if (deleted) {
  console.log('Task deleted successfully');
}
```

### 2. Delete with Confirmation

```javascript theme={null}
const deleteTaskWithConfirmation = async (taskId) => {
  const confirmed = confirm('Are you sure you want to delete this task?');

  if (!confirmed) {
    return { cancelled: true };
  }

  try {
    const response = await fetch(
      `https://api.vambe.me/api/public/tasks/${taskId}`,
      {
        method: 'DELETE',
        headers: {
          'x-api-key': 'your_api_key_here',
        },
      },
    );

    if (!response.ok) {
      throw new Error('Failed to delete task');
    }

    const result = await response.json();
    return { success: result.status === 'success', cancelled: false };
  } catch (error) {
    console.error('Error deleting task:', error);
    return { success: false, error: error.message, cancelled: false };
  }
};

// Example usage
const result = await deleteTaskWithConfirmation(
  '123e4567-e89b-12d3-a456-426614174000',
);
if (result.success) {
  console.log('Task deleted');
} else if (result.cancelled) {
  console.log('Deletion cancelled by user');
} else {
  console.error('Failed to delete:', result.error);
}
```

### 3. Bulk Delete Tasks

```javascript theme={null}
const bulkDeleteTasks = async (taskIds) => {
  const deletePromises = taskIds.map((taskId) =>
    fetch(`https://api.vambe.me/api/public/tasks/${taskId}`, {
      method: 'DELETE',
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    })
      .then((res) => res.json())
      .then((result) => ({ taskId, success: result.status === 'success' }))
      .catch((error) => ({ taskId, success: false, error: error.message })),
  );

  const results = await Promise.all(deletePromises);

  const summary = {
    total: results.length,
    successful: results.filter((r) => r.success).length,
    failed: results.filter((r) => !r.success).length,
    details: results,
  };

  return summary;
};

// Example usage - Delete multiple completed tasks
const taskIdsToDelete = [
  'task-uuid-1',
  'task-uuid-2',
  'task-uuid-3',
  'task-uuid-4',
];

const summary = await bulkDeleteTasks(taskIdsToDelete);
console.log(
  `Deleted ${summary.successful} of ${summary.total} tasks. ${summary.failed} failed.`,
);
```

### 4. Delete Old Completed Tasks

```javascript theme={null}
const deleteOldCompletedTasks = async (daysOld = 90) => {
  // First, fetch old completed tasks
  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - daysOld);

  // Assume you have a way to get completed tasks from GET /api/public/tasks
  const oldTasks = await getCompletedTasksBeforeDate(cutoffDate);

  // Filter to only include tasks older than cutoff
  const tasksToDelete = oldTasks
    .filter((task) => new Date(task.created_at) < cutoffDate)
    .map((task) => task.id);

  if (tasksToDelete.length === 0) {
    return { deleted: 0, message: 'No old tasks to delete' };
  }

  // Delete them
  const deleteResults = await bulkDeleteTasks(tasksToDelete);

  return {
    deleted: deleteResults.successful,
    failed: deleteResults.failed,
    message: `Deleted ${deleteResults.successful} tasks older than ${daysOld} days`,
  };
};

// Example usage - Clean up tasks older than 90 days
const cleanup = await deleteOldCompletedTasks(90);
console.log(cleanup.message);
```

### 5. Delete with UI Update

```javascript theme={null}
const deleteTaskWithUIUpdate = async (taskId, onSuccess, onError) => {
  try {
    const response = await fetch(
      `https://api.vambe.me/api/public/tasks/${taskId}`,
      {
        method: 'DELETE',
        headers: {
          'x-api-key': 'your_api_key_here',
        },
      },
    );

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const result = await response.json();

    if (result.status === 'success') {
      // Update UI - remove task from list
      if (onSuccess) {
        onSuccess(taskId);
      }
      return true;
    } else {
      throw new Error('Delete operation returned non-success status');
    }
  } catch (error) {
    console.error('Error deleting task:', error);
    if (onError) {
      onError(error);
    }
    return false;
  }
};

// Example usage in React component
const handleDelete = async (taskId) => {
  await deleteTaskWithUIUpdate(
    taskId,
    // Success callback
    (deletedId) => {
      setTasks((prev) => prev.filter((task) => task.id !== deletedId));
      showNotification('Task deleted successfully', 'success');
    },
    // Error callback
    (error) => {
      showNotification('Failed to delete task', 'error');
    },
  );
};
```

### 6. Delete with Undo Capability

```javascript theme={null}
const deleteTaskWithUndo = async (taskId) => {
  // Store task data before deletion for potential undo
  const taskResponse = await fetch(
    `https://api.vambe.me/api/public/tasks?taskId=${taskId}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const taskData = await taskResponse.json();

  // Delete the task
  const deleteResponse = await fetch(
    `https://api.vambe.me/api/public/tasks/${taskId}`,
    {
      method: 'DELETE',
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const result = await deleteResponse.json();

  if (result.status === 'success') {
    return {
      success: true,
      undoData: taskData,
      undo: async () => {
        // Recreate the task if undo is called
        const recreateResponse = await fetch(
          'https://api.vambe.me/api/public/tasks',
          {
            method: 'POST',
            headers: {
              'x-api-key': 'your_api_key_here',
              'Content-Type': 'application/json',
            },
            body: JSON.stringify({
              title: taskData.title,
              description: taskData.description,
              dueDate: taskData.due_at,
              dueTime: taskData.is_all_day ? null : '14:00',
              timezone: taskData.due_timezone,
              responsibleIds: taskData.task_responsibles.map(
                (r) => r.responsible_id,
              ),
              aiContactId: taskData.ai_contact_id,
              aiCustomerId: taskData.ai_customer_id,
              priority: taskData.priority.toString(), // Convert number to string
            }),
          },
        );

        return await recreateResponse.json();
      },
    };
  }

  return { success: false };
};

// Example usage
const result = await deleteTaskWithUndo('123e4567-e89b-12d3-a456-426614174000');
if (result.success) {
  showNotification('Task deleted. Undo?', 'info', {
    action: 'Undo',
    onAction: result.undo,
  });
}
```

### 7. Conditional Delete

```javascript theme={null}
const deleteTaskIfComplete = async (taskId) => {
  // First, check if task is completed
  const taskResponse = await fetch(
    `https://api.vambe.me/api/public/tasks?taskId=${taskId}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const task = await taskResponse.json();

  if (
    task.status_config?.type === 'master_done' ||
    task.status_config?.type === 'done'
  ) {
    // Task is completed, safe to delete
    const deleteResponse = await fetch(
      `https://api.vambe.me/api/public/tasks/${taskId}`,
      {
        method: 'DELETE',
        headers: {
          'x-api-key': 'your_api_key_here',
        },
      },
    );

    const result = await deleteResponse.json();
    return { deleted: result.status === 'success', reason: 'completed' };
  } else {
    return { deleted: false, reason: 'task_not_completed' };
  }
};

// Example usage
const result = await deleteTaskIfComplete(
  '123e4567-e89b-12d3-a456-426614174000',
);
if (result.deleted) {
  console.log('Completed task deleted');
} else {
  console.log('Task not deleted:', result.reason);
}
```

## Validation Rules

### Task ID

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

## Error Responses

| Status Code | Description                                   |
| ----------- | --------------------------------------------- |
| 400         | Bad Request - Invalid task ID format          |
| 401         | Unauthorized - Invalid or missing API key     |
| 404         | Not Found - Task not found or already deleted |
| 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": "Invalid UUID format"
}
```

## Important Notes

### Soft Delete

* Tasks are **soft deleted**, not permanently removed from the database
* The task is marked as deleted but data is retained for audit purposes
* Soft deleted tasks will not appear in normal queries
* Database administrators may be able to recover soft deleted tasks

### Associated Data

* **Interactive Notes**: Any interactive notes associated with the task will also be deleted
* **Task Responsibles**: Responsible user associations are removed
* **Contact/Customer Links**: The task-to-contact/customer associations are removed
* **Audit Trail**: Deletion is logged for compliance and auditing

### Permissions

* Users may need appropriate permissions to delete tasks
* Some organizations may restrict deletion to task creators or administrators
* Deleted tasks may trigger notifications to assigned users

## Best Practices

1. **User Confirmation**: Always ask for confirmation before deleting
2. **Permission Checks**: Verify user has permission to delete the task
3. **Status Check**: Consider only allowing deletion of completed or cancelled tasks
4. **Audit Logging**: Log all deletions for compliance and troubleshooting
5. **UI Feedback**: Provide clear feedback on successful/failed deletion
6. **Undo Capability**: Consider implementing an undo feature
7. **Batch Operations**: Use bulk delete for multiple tasks to reduce API calls
8. **Error Handling**: Handle cases where task is already deleted or doesn't exist

## Performance Tips

* **Batch Deletion**: Group multiple deletions to reduce API overhead
* **Optimistic UI**: Remove from UI immediately, rollback on error
* **Background Processing**: For bulk operations, consider background processing
* **Rate Limiting**: Be mindful of rate limits when deleting many tasks

## Alternatives to Deletion

Before deleting a task, consider these alternatives:

* **Archive Status**: Move task to an "archived" or "cancelled" status instead
* **Hide from View**: Filter out old tasks in the UI without deleting
* **Mark as Inactive**: Use a custom status to indicate the task is no longer active
* **Export First**: Export task data before deletion for records

## 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
* [PUT /api/public/tasks/{id}](/reference/tasks/update-task) - Update a task

## Webhook Events

Deleting a task may trigger webhook events such as:

* `task.deleted` - When a task is deleted
* `task.archived` - If your system treats deletion as archival

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

## Recovery

Since this is a soft delete:

* Contact support or your database administrator if you need to recover a deleted task
* Implement your own recovery API if needed
* Consider implementing a "trash" or "recently deleted" feature for user-initiated recovery


## OpenAPI

````yaml delete /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}:
    delete:
      tags:
        - tasks
      summary: Delete a task
      description: >-
        Soft deletes a task by ID. The task will be marked as deleted but not
        permanently removed from the database. Associated interactive notes will
        also be deleted.
      operationId: TaskPublicController_delete
      parameters:
        - name: id
          required: true
          in: path
          description: The UUID of the task to delete
          schema:
            format: uuid
            type: string
      responses:
        '200':
          description: Task deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '400':
          description: Invalid task ID
        '401':
          description: Unauthorized - Invalid or missing authentication token
        '404':
          description: Task not found

````