Vigile
SearchContents

DocumentationOperations

list_projects

List the projects, with each one's status, progress (finished tasks out of all tasks it contains) and problems. Returns at most 100 per call.

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
A list of projects, each in short. Its fields: kind, id, title, status, version, progress, has_problems, and sometimes problems, deleted_at. Not in it: description, links, timeline, created_at, created_by, updated_at and unchanged_since. get has those.
MCP tool
list_projects
HTTP
POST /api/list-projects
Command
vigile list-projects

Input

FieldTakesWhat it is
has_problemsbooleanoptionaltrue to list only projects that have problems.
continuationstringoptionalThe continuation token from the previous page. Return it unchanged to the same operation with the same filters; stop when no token is returned.

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: --has-problems.

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 list-projects --as agent1

HTTP

curl -s http://127.0.0.1:8700/api/list-projects \
  -H 'content-type: application/json' \
  -d '{}'

MCP tool call

{
  "name": "list_projects",
  "arguments": {}
}

The answer

{
  "projects": [
    {
      "kind": "project",
      "id": "APP",
      "title": "Mobile app",
      "status": "open",
      "version": 1,
      "progress": { "finished": 1, "total": 3 },
      "has_problems": false
    },
    {
      "kind": "project",
      "id": "WEB",
      "title": "Website relaunch",
      "status": "open",
      "version": 1,
      "progress": { "finished": 2, "total": 14 },
      "has_problems": false
    }
  ]
}

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

projects: each project in short, with its status, its progress (finished tasks out of the total it contains, at any depth), and has_problems, with the problems when there are some. A continuation token is there when more projects follow.

Rules

  • Deleted projects are not listed.
  • The order is by ID: prefixes in alphabetical order, then the numbered projects.
  • has_problems: true lists only projects with problems; false, only those without.
  • At most 100 projects come in one answer. Send the continuation back, with the same input, for the next page.

Errors

  • invalid_input: a continuation token that is not valid, or that belongs to another list.