Monitor customization

Custom instructions add your organization's policy to Watcher's managed monitors. This API edits the same text as the Custom Instructions editor in the Analyzer. There is one instructions string for the organization, shared by the managed triage and gateway monitors.

Instructions apply when those monitors run, including through gateway hooks. They do not affect custom graders or scheduled summarize and deep_review monitors. They do not replace the monitor's rubric or output format. Calls resolved by deterministic checks do not reach them.

Authentication and permissions

Use your deployment's API authentication. In SSO mode, send an organization API key in x-api-key. In proxy mode, use the credentials your reverse proxy requires.

Method and path, relative to the API base URL	Required permission	Effect
GET /v1/monitors/customization	org:settings:read	Read the saved instructions.
PUT /v1/monitors/customization	org:settings:write	Replace the saved instructions.

For the SSO examples below, set WATCHER_API_URL to your API base URL, including /api, and WATCHER_API_KEY to a key with both permissions. On Apollo cloud, the base URL is https://app.apolloresearch.ai/api. For self-hosting, use https://<your-watcher-host>/api. In proxy mode, replace the x-api-key header with your proxy's required authentication.

Read the current instructions

curl --fail-with-body \
  -H "x-api-key: $WATCHER_API_KEY" \
  "$WATCHER_API_URL/v1/monitors/customization"

Both GET and PUT return HTTP 200 with these fields:

Field	Meaning
instructions	The saved text, or an empty string when none is set.
updated_by	The last writer's identity, or null if never set.
updated_at	The last write time, or null if never set.

Before the first write, the response is:

{"instructions": "", "updated_by": null, "updated_at": null}

Replace the instructions

The request body requires a string field named instructions. Its limit is 32,768 characters. PUT replaces the whole text; it does not append or merge. Save this JSON as monitor-instructions.json, changing the policy to suit your organization:

{"instructions": "Never allow AWS calls by the agent."}

Then send it:

curl --fail-with-body -X PUT \
  -H "x-api-key: $WATCHER_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @monitor-instructions.json \
  "$WATCHER_API_URL/v1/monitors/customization"

Watcher returns HTTP 422 and saves nothing if the text exceeds the limit or contains <organization_instructions> or </organization_instructions> in any letter case. Those tags are reserved; send plain policy text without them.

Check that the response contains the exact text you sent. Repeat GET to verify that it was saved. Later managed-monitor evaluations use the saved policy. Saving it does not regrade prior calls or sessions. Keep your own copy if you need a history: this endpoint retains only the current text.

Clear the instructions

Send an empty string to remove your organization's custom instructions:

curl --fail-with-body -X PUT \
  -H "x-api-key: $WATCHER_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"instructions": ""}' \
  "$WATCHER_API_URL/v1/monitors/customization"

Verify that GET now returns instructions: "". The last writer and write time remain set. Clearing instructions leaves the managed monitors' built-in rubrics in place.