Vigile
SearchContents

DocumentationOperations

update_decision

Amend a decision or explicitly change its status. Withdrawn records remain readable. Changing a decision never changes another item's state.

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 decision in short. Its fields: kind, id, title, status, version, affects, and sometimes deleted_at. Not in it: description, why, links, timeline, created_at, created_by, updated_at and unchanged_since. get has those.
MCP tool
update_decision
HTTP
POST /api/update-decision
Command
vigile update-decision

Input

FieldTakesWhat it is
idstringrequired
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
descriptionstring
at most 4000 characters
optional
whystring | null
1 to 1000 characters
optionalWhy this work matters. Give at least one reason; add more if there are several. Optional, but it helps whoever picks the task up decide and prioritise.
status"proposed" | "active" | "withdrawn"optional

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 after a few changes that set the scene. Over HTTP and MCP, a call without a key acts as agent1 on a new instance.

Command line

vigile update-decision --id WEB-018 --version 1 --status active --as agent1

HTTP

curl -s http://127.0.0.1:8700/api/update-decision \
  -H 'content-type: application/json' \
  -d '{"id":"WEB-018","version":1,"status":"active"}'

MCP tool call

{
  "name": "update_decision",
  "arguments": { "id": "WEB-018", "version": 1, "status": "active" }
}

The answer

{
  "kind": "decision",
  "id": "WEB-018",
  "title": "Show gross prices",
  "status": "active",
  "version": 2,
  "affects": []
}

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 decision in short after the amendment. Use get with history to see previous wording.

Rules

Send the version last read. A withdrawn decision remains readable; changing one decision does not change others.

Errors

version_conflict means the record changed; read it again before amending. A deleted decision must be restored before it can be changed.