Delete a task - Welcome 👋

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

curl -X DELETE 'https://api.vambe.ai/api/public/tasks/123e4567-e89b-12d3-a456-426614174000' \
  -H 'x-api-key: your_api_key_here'

Example Response

{
  "status": "success"
}

Common Use Cases

1. Delete a Single Task

const deleteTask = async (taskId) => {
  const response = await fetch(
    `https://api.vambe.ai/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

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.ai/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

const bulkDeleteTasks = async (taskIds) => {
  const deletePromises = taskIds.map((taskId) =>
    fetch(`https://api.vambe.ai/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

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

const deleteTaskWithUIUpdate = async (taskId, onSuccess, onError) => {
  try {
    const response = await fetch(
      `https://api.vambe.ai/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

const deleteTaskWithUndo = async (taskId) => {
  // Store task data before deletion for potential undo
  const taskResponse = await fetch(
    `https://api.vambe.ai/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.ai/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.ai/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

const deleteTaskIfComplete = async (taskId) => {
  // First, check if task is completed
  const taskResponse = await fetch(
    `https://api.vambe.ai/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.ai/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

{
  "statusCode": 404,
  "message": "Task not found"
}

{
  "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

User Confirmation: Always ask for confirmation before deleting
Permission Checks: Verify user has permission to delete the task
Status Check: Consider only allowing deletion of completed or cancelled tasks
Audit Logging: Log all deletions for compliance and troubleshooting
UI Feedback: Provide clear feedback on successful/failed deletion
Undo Capability: Consider implementing an undo feature
Batch Operations: Use bulk delete for multiple tasks to reduce API calls
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

GET /api/public/tasks - Get tasks by filters
POST /api/public/tasks - Create a new task
PUT /api/public/tasks/ - 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

Path Parameters

string<uuid>

required

The UUID of the task to delete

Response

Task deleted successfully

status

string

Example:

"success"

Task Management

​Overview

​Use Cases

​Authentication

​Path Parameters

​Response Structure

​Example Request

​Example Response

​Common Use Cases

​1. Delete a Single Task

​2. Delete with Confirmation

​3. Bulk Delete Tasks

​4. Delete Old Completed Tasks

​5. Delete with UI Update

​6. Delete with Undo Capability

​7. Conditional Delete

​Validation Rules

​Task ID

​Error Responses

​Common Error Examples

​Important Notes

​Soft Delete

​Associated Data

​Permissions

​Best Practices

​Performance Tips

​Alternatives to Deletion

​Related Endpoints

​Webhook Events

​Recovery

Path Parameters

Response

Overview

Use Cases

Authentication

Path Parameters

Response Structure

Example Request

Example Response

Common Use Cases

1. Delete a Single Task

2. Delete with Confirmation

3. Bulk Delete Tasks

4. Delete Old Completed Tasks

5. Delete with UI Update

6. Delete with Undo Capability

7. Conditional Delete

Validation Rules

Task ID

Error Responses

Common Error Examples

Important Notes

Soft Delete

Associated Data

Permissions

Best Practices

Performance Tips

Alternatives to Deletion

Related Endpoints

Webhook Events

Recovery