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.
- 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
| Field | Takes | What it is | |
|---|---|---|---|
from | string | required | The ID of the item the link starts at. |
type | string | required | The link type, for example "depends on". |
to | string | required | The 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 agent1HTTP
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
versiongoes 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.
Who records a link
| Link | From a | To a | Recorded in the history of | The version goes up of |
|---|---|---|---|---|
contains | project | task | the project and the task | the task |
contains | task | task | the task that contains and the task that is contained | the task that is contained |
depends on | task | task | the task that depends and the task that is depended on | the task that depends |
depends on | task | project | the task and the project | the task |
assigned to | task | user | the task | the 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, ordeleted.