Start a monitor

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)"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/sessions/{sessionId}/monitors"

	payload := strings.NewReader("{\n  \"name\": \"tests\",\n  \"command\": \"go test ./... -run Ledger\",\n  \"filter\": \"^(FAIL|ok)\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'tests', command: 'go test ./... -run Ledger', filter: '^(FAIL|ok)'})
};

fetch('https://api.example.com/v1/sessions/{sessionId}/monitors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/sessions/{sessionId}/monitors"

payload = {
    "name": "tests",
    "command": "go test ./... -run Ledger",
    "filter": "^(FAIL|ok)"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

POST

sessions

{sessionId}

monitors

Start a monitor

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)"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/sessions/{sessionId}/monitors"

	payload := strings.NewReader("{\n  \"name\": \"tests\",\n  \"command\": \"go test ./... -run Ledger\",\n  \"filter\": \"^(FAIL|ok)\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'tests', command: 'go test ./... -run Ledger', filter: '^(FAIL|ok)'})
};

fetch('https://api.example.com/v1/sessions/{sessionId}/monitors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/sessions/{sessionId}/monitors"

payload = {
    "name": "tests",
    "command": "go test ./... -run Ledger",
    "filter": "^(FAIL|ok)"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

Authorizations

Authorization

string

header

required

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.

Path Parameters

sessionId

string<uuid>

required

The session's id.

Body

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

required

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

required

Required string length: 1 - 4096

filter

string

Maximum string length: 512

Response

The monitor, now running.

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

name

string

required

Unique within its session; this is what stops it.

command

string

required

What runs, under the session's repository.

startedBy

enum<string>

required

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.

Available options:

model,

user

startedAt

string<date-time>

required

filter

string

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

Overview

Host

Sessions

Messages

Events

Lanes

Monitors

Agents

Skills and commands

Permissions

Peers

Packages

Extensions

Workflows

Schedules

Providers

Records

Environments

Sharing

Refinements

Platform

Error handling

Start a monitor

Authorizations

Path Parameters

Body

Response