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.
- 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 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_atandunchanged_since.gethas those. - MCP tool
update_task- HTTP
POST /api/update-task- Command
vigile update-task
Input
| Field | Takes | What it is | |
|---|---|---|---|
id | string | required | The task's ID. |
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. |
title | string 1 to 500 characters | optional | |
type | "task" | "bug" | "issue" | "incident" | optional | What 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. |
description | string at most 4000 characters | optional | |
why | string | null 1 to 1000 characters | optional | Why this work matters: at least one reason, more if there are several. null clears it. |
priority | number | optional | The higher, the more important. Not set means 0. |
value | number | null | optional | null clears the value. |
size | number | null | optional | null 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 agent1HTTP
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,valueandsizeare cleared withnull. 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_violationwithdeleted: the task is deleted.not_found: no task has that ID.