Vigile
SearchContents

DocumentationOperations

update_task

Change a task's title, type, description, reason (why), priority, value or size. Send only the fields to change. To change the status use set_task_status; to change what it depends on, which group or project contains it, or who it is assigned to, use add_link and remove_link.

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 changes nothing, and leaves the version as it is.
Answers with
The task in short. Its fields. Not in it: description, why, links, timeline, created_at, created_by, updated_at and unchanged_since. get has those.
MCP tool
update_task
HTTP
POST /api/update-task
Command
vigile update-task

Input

FieldTakesWhat it is
idstringrequiredThe task's ID.
versioninteger
1 or more
requiredThe version of the item you last read. The call fails with a conflict if the item changed since.
titlestring
1 to 500 characters
optional
type"task" | "bug" | "issue" | "incident"optionalWhat this is. task: planned work (the default). bug: something that should work and does not. issue: a problem or open question that needs attention. incident: something is failing right now and needs urgent action. Bugs, issues and incidents are shown apart from planned work.
descriptionstring
at most 4000 characters
optional
whystring | null
1 to 1000 characters
optionalWhy this work matters: at least one reason, more if there are several. null clears it.
prioritynumberoptionalThe higher, the more important. Not set means 0.
valuenumber | nulloptionalnull clears the value.
sizenumber | nulloptionalnull clears the size.

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: --id.

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 update-task \
  --id WEB-009 \
  --version 1 \
  --priority 7 \
  --why "Half of the searches on the old shop used a filter." \
  --as agent1

HTTP

curl -s http://127.0.0.1:8700/api/update-task \
  -H 'content-type: application/json' \
  -d '{"id":"WEB-009","version":1,"priority":7,"why":"Half of the searches on the old shop used a filter."}'

MCP tool call

{
  "name": "update_task",
  "arguments": {
    "id": "WEB-009",
    "version": 1,
    "priority": 7,
    "why": "Half of the searches on the old shop used a filter."
  }
}

The answer

{
  "kind": "task",
  "id": "WEB-009",
  "title": "Filters for price and category",
  "type": "task",
  "status": "open",
  "priority": 7,
  "value": null,
  "size": null,
  "version": 2,
  "contained_in": ["WEB", "WEB-006"],
  "depends_on": ["WEB-007"],
  "assigned_to": [],
  "is_assigned": false,
  "is_next": true,
  "is_waiting": false,
  "waiting_for": [],
  "has_problems": false
}

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.

What it answers

The task in short, as it is after the change. A short form has no description and no why: when one of those was changed, read it back with get.

Rules

  • Only the fields that are sent are changed.
  • why, value and size are cleared with null. A title and a description cannot be emptied.
  • A call changes nothing when every field sent already has that value.
  • The history keeps what was there before: the old and the new value of a field, and the earlier text of a description or a reason.
  • The status, the links and the assignment are not changed here.

Errors

  • version_conflict: the task changed since it was read. The error holds it as it is now, in short.
  • invalid_input: text that is too long or empty, a field the operation does not know.
  • rule_violation with deleted: the task is deleted.
  • not_found: no task has that ID.