Vigile
SearchContents

DocumentationOperations

get

Read one project, task or user in full: its description, its links in both directions, its calculated state, its status timeline and its version. Ask for history to also get the recorded changes. Deleted items can still be read. Each list in the answer holds at most 100 entries: the links of each kind, in the order of their IDs; the latest entries of the timeline and of the history, oldest first; and contained_in, depends_on, assigned_to and waiting_for. When a list has more, "more" says how many it has in all ("total") and, for links, timeline and history, gives a continuation token: call get again with the same id and that token to read the next page of that list alone, which for the timeline and the history holds the entries before the ones already read. Each entry of the timeline and of the history says its "place" in the list. A list that is not named in "more" is whole. Every answer carries "unchanged_since": the revision of the plan since which nothing that get shows of the item has changed: the item itself, its links in either direction, its timeline and history, and what its lists show of the items and users at their other end. Pages belong together when they say the same "unchanged_since"; when a page says another, something was added, removed or changed in between: read the item again from the start. An item that contains others says another after any change to any task, since its progress and problems are worked out from all it contains. The item's "version" does not tell: a task that is put into a group, taken out of it or changed changes what the group's lists show and not the group's version. Every answer is of one state of the item; should the plan be changed faster than the item can be read, the call is refused with too_many_requests: call it again.

The operation's own description: what an agent reads to decide whether and how to call it.
It
Reads. It changes nothing.
Who may call it
Every user.
Pages
Answers in pages of at most 100, with a continuation token for the next.
Answers with
The task in full.
MCP tool
get
HTTP
POST /api/get
Command
vigile get

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.
historybooleanoptionaltrue to also return the recorded changes to the item: when, by whom, and what. The latest 100, oldest first.
continuationstringoptionalA continuation token from "more" in an earlier answer for the same item, to read the next page of that one list. The answer then holds the item's kind, id, version and unchanged_since, and that list 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 get --id WEB-003 --as agent1

HTTP

curl -s http://127.0.0.1:8700/api/get \
  -H 'content-type: application/json' \
  -d '{"id":"WEB-003"}'

MCP tool call

{
  "name": "get",
  "arguments": { "id": "WEB-003" }
}

The answer

{
  "kind": "task",
  "id": "WEB-003",
  "title": "Payment form takes a card",
  "type": "task",
  "status": "in_progress",
  "priority": 8,
  "value": null,
  "size": null,
  "version": 2,
  "contained_in": ["WEB", "WEB-001"],
  "depends_on": ["WEB-002"],
  "assigned_to": ["agent1"],
  "is_assigned": true,
  "is_next": false,
  "is_waiting": false,
  "waiting_for": [],
  "has_problems": false,
  "description": "Collect the card details and charge the total. Done when a test card is charged and a declined card says why.",
  "why": "Without it nothing can be sold. It is also where most customers gave up on the old site.",
  "links": {
    "is contained": [
      { "kind": "project", "id": "WEB", "title": "Website relaunch", "status": "open" },
      {
        "kind": "task",
        "id": "WEB-001",
        "title": "Checkout: a customer can pay for a basket",
        "status": "in_progress"
      }
    ],
    "depends on": [
      {
        "kind": "task",
        "id": "WEB-002",
        "title": "Cart page lists the items and the total",
        "status": "done"
      }
    ],
    "is depended on by": [
      {
        "kind": "task",
        "id": "WEB-004",
        "title": "Confirmation email is sent after payment",
        "status": "open"
      }
    ],
    "assigned to": [
      { "kind": "user", "id": "USER-003", "title": "agent1" }
    ]
  },
  "timeline": [
    { "status": "open", "at": "2026-03-02T08:56:00.000Z", "by": "agent1", "place": 0 },
    {
      "status": "in_progress",
      "at": "2026-03-02T12:05:00.000Z",
      "by": "agent1",
      "place": 1
    }
  ],
  "created_at": "2026-03-02T08:56:00.000Z",
  "created_by": "agent1",
  "updated_at": "2026-03-02T12:05:00.000Z",
  "unchanged_since": 35
}

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 item in full: everything a list says of it, and more, by its kind.

The item isget adds
a taskdescription, why, links, timeline, created_at, created_by, updated_at, unchanged_since
a projectdescription, links, timeline, created_at, created_by, updated_at, unchanged_since
a userlinks, created_at, created_by, updated_at, unchanged_since

With history: true it also has history, for an item of any of the three kinds.

  • description, and why, which is null when nobody has said;
  • links: its links in both directions, under the name that reads correctly from this item, such as is contained, depends on, is depended on by and assigned to;
  • timeline: the statuses it went through, oldest first, each with when, by whom and its place in the list. The latest 100 come with the item; more.timeline says how many there are and leads to the earlier ones;
  • history: what was recorded of the item, oldest first, with when, by whom, what was done and the details.

What it says of a linked item

The linked item isIt comes withAnd when it is deleted
a projectkind, id, title, statusdeleted: true
a taskkind, id, title, statusdeleted: true
a userkind, id, titledeleted: true

A linked project or task comes with its status. A linked user has none: its title is the username.

Rules

  • Deleted items can still be read; they carry deleted_at.
  • A bare number can be a project or a task. When it matches both, the call is refused and says how to tell them apart: put the kind in front, as in task:042, or give kind.
  • A user can be read by its username or by its ID.
  • IDs are read without regard to capitals.

Errors

  • not_found: nothing matches the ID.
  • invalid_input: the ID matches more than one item, or is of another kind than the kind given.