Vigile
SearchContents

DocumentationOperations

add_link

Link two items. The type is one returned by list_link_types. Built in: "contains" (a project or task groups a task), "depends on" (a task waits for a task or project) and "assigned to" (a task has a user working on it). Either the forward or the reverse name works: "A is contained B" is stored as "B contains A". Use "contains" to put a task into a group (a parent task for a feature or epic) or into another project; a task can be in several. A completed task container, including an ancestor of the named group, must be reopened before work is put inside it. A link that would create a loop is refused. Adding a link that already exists changes nothing. A new link is a change to the task it is about (the one that is contained, depends or is assigned): that task's version goes up.

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 no version: it is carried out on the plan as it is at that moment.
Answers with
The link, and whether it was made now.
MCP tool
add_link
HTTP
POST /api/add-link
Command
vigile add-link

Input

FieldTakesWhat it is
fromstringrequiredThe ID of the item the link starts at.
typestringrequiredThe link type, for example "depends on".
tostringrequiredThe ID of the item the link points at; a username works for a user.

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

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 add-link --from WEB-012 --type "depends on" --to WEB-003 --as agent1

HTTP

curl -s http://127.0.0.1:8700/api/add-link \
  -H 'content-type: application/json' \
  -d '{"from":"WEB-012","type":"depends on","to":"WEB-003"}'

MCP tool call

{
  "name": "add_link",
  "arguments": { "from": "WEB-012", "type": "depends on", "to": "WEB-003" }
}

The answer

{
  "created": true,
  "link": { "from": "WEB-012", "type": "depends on", "to": "WEB-003" }
}

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 add-link --from WEB-001 --type "depends on" --to WEB-013 --as agent1
{
  "error": {
    "code": "rule_violation",
    "message": "This link would create a loop, so none of these could ever finish: WEB-001 → WEB-013 → WEB-001.",
    "rule": "loop",
    "blocking": [
      {
        "kind": "task",
        "id": "WEB-013",
        "title": "Launch: the domain points to the new site",
        "status": "open"
      }
    ],
    "actions": ["Remove one of the links on that path first, or link different items."]
  }
}

What it answers

created, and the link as it is stored: from, type and to. When the link was already there, created is false and nothing has changed.

Rules

  • The type is one of the link types, by either of its names. With the reverse name the two ends are swapped: "A is contained B" is stored as "B contains A".
  • The two ends have to be of the kinds the type connects, exist, and not be deleted.
  • A link that would close a loop of "contains" and "depends on" is refused, with the path it would close. In the refused call above, the launch already waits for the checkout.
  • An item cannot be linked to itself.
  • It takes no version. But the link is a change to the task it is about, the one that is contained, depends or is assigned: that task's version goes up by one, and whoever read it before reads it again.
  • An end that is a project or task records the new link in its history. A user keeps no history of the tasks it is given: an assignment is in the history of the task, and only there.
LinkFrom aTo aRecorded in the history ofThe version goes up of
containsprojecttaskthe project and the taskthe task
containstasktaskthe task that contains and the task that is containedthe task that is contained
depends ontasktaskthe task that depends and the task that is depended onthe task that depends
depends ontaskprojectthe task and the projectthe task
assigned totaskuserthe taskthe task

The same holds when a task is created with its links, and when an item is deleted for good and its links go with it: a project or task at the other end records it in its history, a user does not.

"contains" puts a task into a group or a project; a task can be in several. "depends on" makes a task wait. "assigned to" says who works on it; a task can have several users.

Errors

  • invalid_input: no such link type, or ends of the wrong kinds for it.
  • not_found: one of the two items does not exist.
  • rule_violation: loop, self_link, or deleted.