Vigile
SearchContents

Documentation

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:

WhereCalled as
MCPthe tool set_task_status
HTTP APIPOST /api/set-task-status
Command linevigile 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

OperationItWho may callWhat it does
create_projectchangesevery userCreate a project, which groups tasks.
set_project_statuschangesevery userChange a project's status.
list_projectsreadsevery userList the projects, with each one's status, progress (finished tasks out of all tasks it contains) and problems.

Tasks

OperationItWho may callWhat it does
create_taskchangesevery userCreate a task.
update_taskchangesevery userChange a task's title, type, description, reason (why), priority, value or size.
set_task_statuschangesevery userChange a task's status.
list_tasksreadsevery userList tasks, without their descriptions, with each one's status, links and calculated state.
list_next_tasksreadsevery userList the tasks you can start now.
list_stale_tasksreadsevery userList assigned tasks that are still in progress after 24 hours without a recorded change to the task.

Any item

OperationItWho may callWhat it does
getreadsevery userRead one project, task or user in full.
list_historyreadsevery userList retained changes across the plan, newest first.
deletechangesevery userDelete a project, task or user.
restorechangesevery userBring back a deleted project, task or user.
override_timestampchangesevery userFor importing work that was created or finished somewhere else.
OperationItWho may callWhat it does
add_linkchangesevery userLink two items.
remove_linkchangesevery userRemove a link between two items.
list_link_typesreadsevery userList the link types that add_link and remove_link accept.

Users

OperationItWho may callWhat it does
list_usersreadsevery userList the users, to find who work can be assigned to.
create_userchangesadmins onlyCreate a user and its API key.
reset_user_keychangesadmins onlyIssue a new API key for a user and cancel the old one.

The guide

OperationItWho may callWhat it does
get_guidereadsevery userRead 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 give kind. 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_violation and limit_exceeded are given before anything is stored. After internal the 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.

OperationTakes a versionSo
set_project_statusyesRefused with version_conflict when the item has changed since the version that is sent.
update_taskyesRefused with version_conflict when the item has changed since the version that is sent.
set_task_statusyesRefused with version_conflict when the item has changed since the version that is sent.
deleteyesRefused with version_conflict when the item has changed since the version that is sent.
override_timestampyesRefused with version_conflict when the item has changed since the version that is sent.
create_projectnoThere is no item yet. Sent twice, it makes two projects, unless a prefix is given: the second is then refused with prefix_taken.
create_tasknoThere is no item yet. Sent twice, it makes two tasks.
restorenoA deleted item cannot be changed, so there is nothing a restore could overwrite. Sent twice, the second is refused with not_deleted.
add_linknoIt adds to a set. A link that is already there is left as it is, and the answer says created: false.
remove_linknoIt takes from a set. A link that is no longer there is not_found.
create_usernoThere is no item yet. A username that is taken is refused with username_taken.
reset_user_keynoEach 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.

FieldSentIs
kindalwaystask.
idalwaysIts ID, as in WEB-003, given when it was created.
titlealwaysIts title.
typealwaysIts type.
statusalwaysIts status.
priorityalwaysAs set.
valuealwaysAs set, or null.
sizealwaysAs set, or null.
versionalwaysThe version to send with the next change that takes one.
contained_inalwaysThe 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_onalwaysThe IDs of what it depends on.
assigned_toalwaysThe usernames of who has it.
is_assignedalwaysWhether anyone has it.
is_nextalwaysWhether 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_waitingalwaysWhether 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_foralwaysThe IDs of what it waits for; empty when it is not waiting.
has_problemsalwaysWhether it has a problem.
completed_atsometimesOnly for a task that is done: when it was last set to done.
progresssometimesOnly for a task that contains tasks: finished and total.
problemssometimesOnly when there are some: what is wrong.
deleted_atsometimesOnly for a deleted task: when.
live_containerssometimesOnly 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 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.