Vigile
SearchContents

DocumentationOperations

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.

The operation's own description: what an agent reads to decide whether and how to call it.
It
Changes the plan, as one step that is stored whole or not at all.
Who may call it
Every user.
Version
Takes the version the caller last read, and is refused with version_conflict when the item has changed since. A change moves the version one on. A call that asks for what is already so is refused with already_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

FieldTakesWhat it is
kind"project" | "task" | "user"optionalThe kind of item: "project", "task" or "user". Needed only when the ID alone is ambiguous.
idstringrequiredThe item's ID, or a username for a user.
versioninteger
1 or more
requiredThe version of the item you last read. The call fails with a conflict if the item changed since.
permanentbooleanoptionaltrue 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 agent1

HTTP

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 with restore.
  • 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: true removes 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_in or already_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.