Vigile
SearchContents

Documentation

The HTTP API

Every operation is an endpoint. A call is a POST with a JSON body, the answer is JSON, and a refusal says what is wrong in one shape.

Calling an operation

The examples ask a running instance on its usual port, 8700, which holds the made-up plan the pictures show. See Install and first run.

An operation is a POST to /api/<name>, with the name written with hyphens, and its input as a JSON body:

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

With a key, where vig_... stands for the key of a user:

curl -s http://127.0.0.1:8700/api/set-task-status \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer vig_...' \
  -d '{"id": "WEB-005", "version": 1, "status": "in_progress"}'
  • The body must say that it is JSON, with the header Content-Type: application/json. A body of any other type is not read. No body at all is an empty input.
  • Authorization: Bearer <key> makes the call act as the user that key belongs to. Without it, the call acts as the keyless user, if the instance has one. See Users and access.
  • The answer is the operation's result, as JSON, with status 200. Operations shows the input and a real answer of each.
  • A body may have at most 1 MB. A larger one is refused as limit_exceeded.
  • Only a POST request may have a body. Any other that brings one is refused as invalid_input.
  • There is no version in the address. The API is the one of the service that answers; GET /health says which version that is.

Errors

A call that is refused gets the status of its code and one shape of body:

{
  "error": {
    "code": "version_conflict",
    "message": "Task WEB-002 changed since you read it: it is at version 2, you sent 1.",
    "current": { "kind": "task", "id": "WEB-002", "version": 2, "status": "in_progress" },
    "actions": ["Check the current item, then repeat the call with its version."]
  }
}

The example is cut short.

Under current is the item as it is now, in short: what a list says of it, which is less than get says.

The item iscurrent hasAnd when there is something to say
a taskkind, id, title, type, status, priority, value, size, version, contained_in, depends_on, assigned_to, is_assigned, is_next, is_waiting, waiting_for, has_problemscompleted_at, progress, problems, deleted_at, live_containers
a projectkind, id, title, status, version, progress, has_problemsproblems, deleted_at
a userkind, id, username, type, built_in, versiondeleted_at

It does not have description, why, links, timeline, created_at, created_by, updated_at or unchanged_since, nor the history. Call get for those.

CodeHTTP statusWhen
invalid_input400The input is not what the operation takes: a value of the wrong type, a required field that is missing, a field it does not know, text that is too long, an ID that matches more than one item, a body that is not JSON, a request other than a POST that brings a body. The message names the field.
not_found404No item matches the ID or name that was given, there is no such link, no such operation, or nothing is served at that address.
unauthorized401The connection may not act as anyone: it has no key where one is required, the key is not valid, or the key's user no longer exists.
forbidden403The caller may not do this: an operation for admins, a permanent delete, or a request one of the guards turns away.
version_conflict409The item changed since the caller read it. The error carries the item as it is now, in short, under current.
rule_violation409The change would break a rule of the plan. The error carries the rule and what to do under actions, and with some rules the items in the way under blocking.
limit_exceeded413The request is too large: a body of more than 1 MB, or a change that touches more records than can be stored in one step.
too_many_requests429Either too many clients are listening to the stream of changes, in all, from one address or from the service's own machine, or a read by get or list_history was overtaken repeatedly by changes to the plan. Close stream clients in the first case; read again in the second.
internal500Something went wrong inside the service that was nobody's mistake. The service's log says what. It is the one code after which a change may have been stored: the message says what stands, or that the change was not confirmed.

Input the operation cannot take is invalid_input, with a message that names the field. Errors and refusals has every code and every rule.

An error does not always mean that nothing was changed. After invalid_input, not_found, forbidden, version_conflict, rule_violation and limit_exceeded nothing was: the change was refused before it was stored. After internal, read the message: it says what stands, or that the change was not confirmed, and then the item is read again before the change is sent again. See what to do with a refusal.

The other endpoints

EndpointAnswersNeeds
GET /health{"status": "ok", "name", "version"}: that a Vigile service is here, which instance and which versionnothing, never a key
GET /api/instanceThe instance's name and version, and under you who the request acts as: username, type, and whether no key was neededto be let in
GET /api/operationsThe operations the caller may call, each with its name, path, kind (read or write), access, description and the JSON Schema of its inputto be let in
GET /api/eventsThe stream of changes, belowto be let in
GET /api/admin/statusDetails of the running service, for the doctor: process, uptime, settings with keys masked, counts, and what a check of the graph foundan admin
POST /mcpMCP, for agents: see MCP for agentsto be let in

Anything else under /api/ is not_found, with how operations are called.

GET /api/operations is the API describing itself. A client can be built from it without this documentation:

curl -s http://127.0.0.1:8700/api/operations

The stream of changes

GET /api/events is a stream of server-sent events, for anything that wants to know when the plan changes:

curl -N http://127.0.0.1:8700/api/events

It keeps running, so it takes a terminal of its own.

event: hello
data: {"revision":5}

event: change
data: {"revision":6}
  • hello comes on connecting, change after every stored change.
  • Each carries the plan's revision, a number that goes up by one with every stored change, and nothing else. What changed is read through the operations.
  • A comment line every 20 seconds keeps the connection from being closed as idle.
  • It needs a key whenever the operations do. Who may listen is asked again before each message, so a key that was reset ends the stream.
  • At most 200 clients may listen at once: 32 from one address, and 168 in all that connect from the service's own machine, whomever they say they speak for. A further one gets too_many_requests. A client that has stopped reading is let go, and can connect again.
  • A stream is the last answer on its connection: what is sent behind it on that connection is not looked at.

Lists and 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.

curl -s http://127.0.0.1:8700/api/list-tasks \
  -H 'content-type: application/json' \
  -d '{"project": "WEB", "continuation": "<token>"}'

A token belongs to the list it came from: with other filters, or made up, it is refused as invalid_input. So is a continuation sent to an operation that does not answer in pages, which does not know the field. A page starts after the last item of the page before, so items that were added or removed in between do not shift it.

Requests that are turned away before they are read

Three guards stand before /api. A request they turn away is not let in, with or without a key:

GuardRefusesConcernsAnswers
Pages of other sitesA request that says it comes from a page of another site: with an Origin that is not the address the request was sent to, or with a Sec-Fetch-Site that is neither same-origin nor none.Only what sends those headers, which is browsers. A program that sends neither is not looked at by this guard.forbidden
The name it is called byWhile the service listens on this machine only, a request whose Host is neither localhost, nor a loopback address, nor the address in the config.Every client, a browser or not: a program that calls the service by another name is refused as well.forbidden
A body that says what it isA request with a body that does not say Content-Type: application/json.Every client, a browser or not.invalid_input

A program that is not a browser is passed by the first guard only, because it sends neither header. The other two are held against it like against a browser. GET /health is not behind them. See the guards for why they are there.

Limits on a connection

A request has 30 seconds to arrive in full, headers and body; one that does not is dropped. The service keeps at most 1,024 connections open at once, 64 of them for one address beyond its own machine, and closes a connection on which nothing moves for a minute. A connection may have at most 8 requests that are not answered yet. Security has the whole of it.

A request that is refused before its body has arrived ends its connection with the answer: the rest of the body is not read, and nothing that came behind it on that connection is carried out.

Answers are never to be cached: they say Cache-Control: no-store.