---
description: >-
  Read, replace, and clear organization instructions for managed live monitors through the Watcher API.
---

> Part of the Watcher docs. Index of all pages, with summaries: https://watcher-docs.apolloresearch.ai/llms.txt
> Before upgrading Watcher, read the release pages and full changelogs for every version crossed: https://watcher-docs.apolloresearch.ai/releases/index.md
> Found an issue with this page? Report it: https://github.com/ApolloResearch/watcher-bin/issues/new?title=Docs%20feedback%3A%20Monitor%20customization&body=Page%3A%20Monitor%20customization%0AURL%3A%20https%3A%2F%2Fwatcher-docs.apolloresearch.ai%2Fapi%2Fmonitor-customization%2F%0A%0A

# Monitor customization

Custom instructions add your organization's policy to Watcher's
[managed monitors](../concepts/graders.md#monitors). This API edits the same text
as the Custom Instructions editor in the [Analyzer](../concepts/analyzer.md).
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](hooks.md). 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](index.md#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

```bash
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:

```json
{"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:

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

Then send it:

```bash
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:

```bash
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.