Start a monitor

Runs command under the session’s repository and streams what it says into the conversation as it happens — batched on the pauses between bursts, so one test failure is one piece of news rather than forty lines. The monitor is announced in the transcript, listed until it is stopped, and killed with the host. A name already in use in this session is refused rather than replaced.

POST /v1/sessions/{sessionId}/monitors

Start a monitor

cURL

curl --request POST \
  --url https://api.example.com/v1/sessions/{sessionId}/monitors \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "tests",
  "command": "go test ./... -run Ledger",
  "filter": "^(FAIL|ok)"
}
'

201

{
  "name": "tests",
  "command": "go test ./... -run Ledger",
  "startedBy": "model",
  "startedAt": "2026-08-23T12:01:03.000Z"
}

Autorizaciones

Authorization · string · header · requerido

Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.

Parámetros de ruta

sessionId · string<uuid> · requerido

The session's id.

Cuerpo

application/json

A request to run a watcher. Monitors started this way are recorded as the person's; the model starts its own through its tool.

name · string · requerido

The watcher's name. Bounded to what a URL path segment carries unchanged, because this same name is the address the request that stops the watcher is sent to.

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$

command · string · requerido

Required string length: 1 - 4096

filter · string

Maximum string length: 512

Respuesta

201

application/json

The monitor, now running.

One long-running watcher a session is keeping beside its conversation.

name · string · requerido

Unique within its session; this is what stops it.

command · string · requerido

What runs, under the session's repository.

startedBy · enum<string> · requerido

Which hand reached the switch. Both may, and the registry treats them identically; this says which one it was, so the model knows before it stops something it did not start.

Opciones disponibles: model, user

startedAt · string<date-time> · requerido

filter · string

A regular expression keeping only the output lines that match it. Absent means every line.