Vigile
SearchContents

DocumentationOperations

list_users

List the users, to find who work can be assigned to. A user is an admin, a person or an agent. Assign a task with add_link and type "assigned to". Returns at most 100 per call, ordered by ID.

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 users, each in short. Its fields: kind, id, username, type, built_in, version, and sometimes deleted_at. Not in it: links, created_at, created_by, updated_at and unchanged_since. get has those.
MCP tool
list_users
HTTP
POST /api/list-users
Command
vigile list-users

Input

FieldTakesWhat it is
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: --continuation.

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-users --as agent1

HTTP

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

MCP tool call

{
  "name": "list_users",
  "arguments": {}
}

The answer

{
  "users": [
    {
      "kind": "user",
      "id": "USER-001",
      "username": "admin",
      "type": "admin",
      "built_in": true,
      "version": 1
    },
    {
      "kind": "user",
      "id": "USER-002",
      "username": "user",
      "type": "person",
      "built_in": true,
      "version": 1
    }
  ],
  "you": "agent1"
}

This is what a service answered when this page was built; for the page, users shows 2 of 4. 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

users: each user with its id, username, type, whether it is built_in, and its version. And you: the username the call was made as, which tells an agent who it is.

Rules

  • Deleted users are not listed.
  • The order is that of their IDs, which is the order they were created in.
  • Keys are never in an answer of this operation.
  • At most 100 users come in one answer. Send the continuation back unchanged for the next page.

Errors

  • invalid_input: a continuation token is invalid or belongs to another list.

See also

Assign a task with add_link and the type "assigned to", or with assigned_to when creating it.