Operations
Everything that reads or changes a plan is one of these operations. Each is offered three ways, with the same input, the same answer and the same rules.
An operation called set_task_status is:
| Where | Called as |
|---|---|
| MCP | the tool set_task_status |
| HTTP API | POST /api/set-task-status |
| Command line | vigile set-task-status |
Each page below is made from the operation's own definition: its description, its input and who may call it. The example on each page was run against a real service when this site was built, on the made-up plan its pictures show.
Projects
| Operation | It | Who may call | What it does |
|---|---|---|---|
create_project | changes | every user | Create a project, which groups tasks. |
set_project_status | changes | every user | Change a project's status. |
list_projects | reads | every user | List the projects, with each one's status, progress (finished tasks out of all tasks it contains) and problems. |
Tasks
| Operation | It | Who may call | What it does |
|---|---|---|---|
create_task | changes | every user | Create a task. |
update_task | changes | every user | Change a task's title, type, description, reason (why), priority, value or size. |
set_task_status | changes | every user | Change a task's status. |
list_tasks | reads | every user | List tasks, without their descriptions, with each one's status, links and calculated state. |
list_next_tasks | reads | every user | List the tasks you can start now. |
list_stale_tasks | reads | every user | List assigned tasks that are still in progress after 24 hours without a recorded change to the task. |
Any item
| Operation | It | Who may call | What it does |
|---|---|---|---|
get | reads | every user | Read one project, task or user in full. |
list_history | reads | every user | List retained changes across the plan, newest first. |
delete | changes | every user | Delete a project, task or user. |
restore | changes | every user | Bring back a deleted project, task or user. |
override_timestamp | changes | every user | For importing work that was created or finished somewhere else. |
Links
| Operation | It | Who may call | What it does |
|---|---|---|---|
add_link | changes | every user | Link two items. |
remove_link | changes | every user | Remove a link between two items. |
list_link_types | reads | every user | List the link types that add_link and remove_link accept. |
Users
| Operation | It | Who may call | What it does |
|---|---|---|---|
list_users | reads | every user | List the users, to find who work can be assigned to. |
create_user | changes | admins only | Create a user and its API key. |
reset_user_key | changes | admins only | Issue a new API key for a user and cancel the old one. |
The guide
| Operation | It | Who may call | What it does |
|---|---|---|---|
get_guide | reads | every user | Read the guide to this service. |
What they share, and where they differ
- Input is checked before anything is done. A field of the wrong type, a required field that is missing or a field the operation does not know is refused as
invalid_input, and the message names the field. An operation for admins asks who is calling before that. - A change to the plan is one step. It is stored whole, with its history, or not at all. A user's key is kept in the config file, apart from the plan: the exception below is about that.
- An item is named by its ID. Where a bare number could be a project or a task, put the kind in front, as in
task:042, or givekind. A user can be named by its username. - A refusal says what is wrong and names actions to take. See Errors and refusals.
- A refusal means nothing was changed, with one exception.
invalid_input,not_found,forbidden,version_conflict,rule_violationandlimit_exceededare given before anything is stored. Afterinternalthe message says what stands, or that the change was not confirmed: read the item again before sending the change again. See what an error leaves behind.
Which operations take a version
Not every change does. An operation that changes or deletes an item that is there takes the version the caller last read, and is refused when the item has changed since. See Versions, conflicts and history.
| Operation | Takes a version | So |
|---|---|---|
set_project_status | yes | Refused with version_conflict when the item has changed since the version that is sent. |
update_task | yes | Refused with version_conflict when the item has changed since the version that is sent. |
set_task_status | yes | Refused with version_conflict when the item has changed since the version that is sent. |
delete | yes | Refused with version_conflict when the item has changed since the version that is sent. |
override_timestamp | yes | Refused with version_conflict when the item has changed since the version that is sent. |
create_project | no | There is no item yet. Sent twice, it makes two projects, unless a prefix is given: the second is then refused with prefix_taken. |
create_task | no | There is no item yet. Sent twice, it makes two tasks. |
restore | no | A deleted item cannot be changed, so there is nothing a restore could overwrite. Sent twice, the second is refused with not_deleted. |
add_link | no | It adds to a set. A link that is already there is left as it is, and the answer says created: false. |
remove_link | no | It takes from a set. A link that is no longer there is not_found. |
create_user | no | There is no item yet. A username that is taken is refused with username_taken. |
reset_user_key | no | Each reset that is carried out replaces the key: the last one carried out is the one in force. |
Which lists come in pages
Six list operations answer in pages of at most 100: list_projects, list_history, list_tasks, list_next_tasks, list_stale_tasks and list_users. When there is more, the answer carries a top-level continuation token: send it back unchanged, with the same operation and filters, for the next page. list_link_types answer with the whole list at once, and take no token.
get can page each cut list of one item separately. more.links[<type>], more.timeline or more.history carries that list's total and continuation token. Send the token back to get with the same item ID. Link pages continue forward by ID; timeline and history pages continue to older entries. Combine item pages only while their unchanged_since values match. If one differs, read the item again from the first page.
See Lists and pages.
What an answer about a task carries
The operations that create, change or list tasks answer with the task in short. So does a conflict, under current.
| Field | Sent | Is |
|---|---|---|
kind | always | task. |
id | always | Its ID, as in WEB-003, given when it was created. |
title | always | Its title. |
type | always | Its type. |
status | always | Its status. |
priority | always | As set. |
value | always | As set, or null. |
size | always | As set, or null. |
version | always | The version to send with the next change that takes one. |
contained_in | always | The IDs of the projects and tasks that contain it. A project whose ID is a number is written with its kind, as project:001. |
depends_on | always | The IDs of what it depends on. |
assigned_to | always | The usernames of who has it. |
is_assigned | always | Whether anyone has it. |
is_next | always | Whether it can be started now: The task is open, is not deleted, has an active path through its projects and groups, and has no unfinished dependency. See Next and waiting. |
is_waiting | always | Whether it is held back: The task is not deleted, is draft, open, in_progress, paused or in_review, and either depends on something unfinished or every path through its projects and groups is inactive. |
waiting_for | always | The IDs of what it waits for; empty when it is not waiting. |
has_problems | always | Whether it has a problem. |
completed_at | sometimes | Only for a task that is done: when it was last set to done. |
progress | sometimes | Only for a task that contains tasks: finished and total. |
problems | sometimes | Only when there are some: what is wrong. |
deleted_at | sometimes | Only for a deleted task: when. |
live_containers | sometimes | Only for a task with a deleted group among its containers: the IDs of the live projects and tasks that hold it now, through the deleted ones. contained_in still names the deleted group. |
| The item is | get adds |
|---|---|
| a task | description, why, links, timeline, created_at, created_by, updated_at, unchanged_since |
| a project | description, links, timeline, created_at, created_by, updated_at, unchanged_since |
| a user | links, created_at, created_by, updated_at, unchanged_since |
With history: true it also has history, for an item of any of the three kinds.