delete
Delete a project, task or user. By default the item is only hidden: it leaves the lists, stops holding back what depends on it, and can be brought back with restore. A project that still contains tasks cannot be deleted. Deleting users, and deleting anything permanently, is for admins only; a permanent delete also removes the item's links and its history and cannot be undone. A project cannot be deleted permanently while deleted tasks are still in it, and its prefix is never given to another project.
- It
- Changes the plan, as one step that is stored whole or not at all.
- Who may call it
- Every user.
- Version
- Takes the
versionthe caller last read, and is refused withversion_conflictwhen the item has changed since. A change moves the version one on. A call that asks for what is already so is refused withalready_deleted. - Answers with
- That it was deleted, whether for good, and the kind and ID of the item.
- MCP tool
delete- HTTP
POST /api/delete- Command
vigile delete
Input
| Field | Takes | What it is | |
|---|---|---|---|
kind | "project" | "task" | "user" | optional | The kind of item: "project", "task" or "user". Needed only when the ID alone is ambiguous. |
id | string | required | The item's ID, or a username for a user. |
version | integer 1 or more | required | The version of the item you last read. The call fails with a conflict if the item changed since. |
permanent | boolean | optional | true to remove the item for good. Admins only. |
A field that is not listed here is refused, as invalid_input. On the command line each field is an option, with hyphens for underscores: --kind.
Example
The same call three ways, as agent1. It was made on the demo plan the pictures of this site show. Over HTTP and MCP, a call without a key acts as agent1 on a new instance.
Command line
vigile delete --id APP-016 --version 1 --as agent1HTTP
curl -s http://127.0.0.1:8700/api/delete \
-H 'content-type: application/json' \
-d '{"id":"APP-016","version":1}'MCP tool call
{
"name": "delete",
"arguments": { "id": "APP-016", "version": 1 }
}The answer
{ "deleted": true, "permanent": false, "kind": "task", "id": "APP-016" }
This is what a service answered when this page was built. Over HTTP it is the body of the response, over MCP the text of the tool result, and the command line prints it in words unless given --json.
A call that is refused
vigile delete --id WEB --version 1 --as agent1
{
"error": {
"code": "rule_violation",
"message": "Project WEB still contains 14 tasks.",
"rule": "contains_tasks",
"blocking": [
{
"kind": "task",
"id": "WEB-001",
"title": "Checkout: a customer can pay for a basket",
"status": "in_progress"
},
{
"kind": "task",
"id": "WEB-002",
"title": "Cart page lists the items and the total",
"status": "done"
},
{
"kind": "task",
"id": "WEB-003",
"title": "Payment form takes a card",
"status": "in_progress"
},
{
"kind": "task",
"id": "WEB-004",
"title": "Confirmation email is sent after payment",
"status": "open"
},
{
"kind": "task",
"id": "WEB-005",
"title": "Total is wrong when a coupon is applied twice",
"status": "open"
},
{
"kind": "task",
"id": "WEB-006",
"title": "Search: products are found by name and category",
"status": "in_progress"
},
{
"kind": "task",
"id": "WEB-007",
"title": "Index all products every night",
"status": "done"
},
{
"kind": "task",
"id": "WEB-008",
"title": "Search box with suggestions in the header",
"status": "in_review"
},
{
"kind": "task",
"id": "WEB-009",
"title": "Filters for price and category",
"status": "open"
},
{
"kind": "task",
"id": "WEB-010",
"title": "Accounts: customers sign in with their old password",
"status": "in_progress"
},
{
"kind": "task",
"id": "WEB-011",
"title": "Import customer accounts from the old shop",
"status": "in_progress"
},
{
"kind": "task",
"id": "WEB-012",
"title": "Password reset by email",
"status": "open"
},
{
"kind": "task",
"id": "WEB-013",
"title": "Launch: the domain points to the new site",
"status": "open"
},
{
"kind": "task",
"id": "WEB-014",
"title": "Staging site is down after the last deploy",
"status": "in_progress"
}
],
"actions": ["Delete those tasks first, or call remove_link to move them out of the project."]
}
}
What it answers
deleted: true, whether it was permanent, and the kind and id of the item.
Rules
- By default the item is only hidden: it leaves the lists, stops holding back what depends on it, can still be read with
get, and comes back withrestore. - A project that still contains tasks cannot be deleted: delete the tasks first, or move them out with
remove_link. - A user that still has tasks assigned cannot be deleted. Its key stops working when it is deleted.
- The three built-in users cannot be deleted.
- Deleting a user, and deleting anything for good, is for admins.
permanent: trueremoves the item with its description, its links and its history, and cannot be undone. A project or task that was linked to it records in its own history that the link is gone; a user does not. - A project cannot be deleted for good while deleted tasks are still in it. Its prefix is never given to another project.
Errors
version_conflict: the item changed since it was read.forbidden: the caller is not an admin and asked for a permanent delete, or to delete a user.rule_violation:contains_tasks,contains_deleted_tasks,has_assigned_tasks,built_inoralready_deleted.not_found: nothing matches the ID.internal, "User … was deleted, but its API key could not be removed": the user is deleted, and the key lets nobody in while it is. The message says how to remove what is left. Do not delete again.