# Update a program

`PATCH /programs/{program_uuid}`

- Base: `PATCH https://portal.watcheye.com.au/api/v1/programs/{program_uuid}`

Update an existing program using PATCH semantics: only the fields you supply are changed,
everything else is left as-is. Pass `null` to clear an optional field.

Note: when changing `event_grouping` to `separate` you must also supply
`max_separate_events`. Conversely, when changing it to `grouped`, any supplied
`max_separate_events` is ignored and the stored value is cleared.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `program_uuid` | path | string (uuid) | **Required.** The program UUID |

## Request body

The program fields to update. All fields are optional.

| Field | Type | Description |
|-------|------|-------------|
| `program_name` | string [2..255 characters] |  |
| `status` | string | Enum: `active`, `paused` |
| `report_emails` | array of strings [max 5 items] or null |  |
| `data_retention_months` | integer | Enum: `0`, `1`, `3`, `6`, `12`, `24`, `36`, `48`, `60`, `72`, `84` |
| `event_grouping` | string | Enum: `separate`, `grouped` |
| `max_separate_events` | integer [5..100] or null |  |
| `default_risk_level` | string or null | The risk level pre-filled when a new entity is added to this program. When set to `null` (No risk assigned), new entities start with no risk rating, which may be left unassigned and set later; bulk file uploads assign `low`. Enum: `low`, `medium`, `high` |

**Sample request**

```json
{
    "program_name": "string",
    "status": "active",
    "report_emails": [
        "user@example.com"
    ],
    "data_retention_months": 0,
    "event_grouping": "separate",
    "max_separate_events": 0,
    "default_risk_level": "low"
}
```

## Responses

### 200 Program updated

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | object |  |
| `data.uuid` | string (uuid) | The program's UUID Example: `9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f` |
| `data.program_number` | string | A short obfuscated public identifier for the program (e.g. "P-123-456-789") Example: `P-123-456-789` |
| `data.program_name` | string | The display name of the program Example: `AML Onboarding Program` |
| `data.status` | string | Lifecycle status of the program: * `active` - normal operation * `paused` - monitors do not run; entities and checks remain accessible * `archived` - read-only; the program is hidden from default lists but not deleted Enum: `active`, `paused`, `archived` Example: `active` |
| `data.report_emails` | array of strings | Email addresses (max 5) that receive event report notifications for this program |
| `data.data_retention_months` | integer | How long, in months, to keep entity data for. Permitted values: `0` (no retention), `1`, `3`, `6`, `12`, `24`, `36`, `48`, `60`, `72`, `84`. Example: `12` |
| `data.event_grouping` | string | Whether events from the same entity should be grouped into one event: * `separate` - each event is created as a separate event (capped by `max_separate_events`) * `grouped` - events are merged into a single event per entity Enum: `separate`, `grouped` Example: `separate` |
| `data.max_separate_events` | integer or null | When `event_grouping` is `separate`, the maximum number of separate events to create for a single entity (5-100). Null when `event_grouping` is `grouped`. Example: `10` |
| `data.default_risk_level` | string or null | The risk level pre-filled when a new entity is added to this program: * `low` / `medium` / `high` - new entities pre-fill with this risk rating * `null` - new entities start with no risk assigned; the rating may be left unassigned and set later (bulk file uploads assign `low`) Enum: `low`, `medium`, `high` Example: `low` |
| `data.created_at` | string (date-time) | ISO 8601 timestamp at which the program was created Example: `2025-01-01T00:00:00Z` |
| `data.updated_at` | string (date-time) | ISO 8601 timestamp at which the program was last updated Example: `2025-01-01T00:00:00Z` |
| `api_reference` | string (uuid) |  |

**Sample response**

```json
{
    "data": {
        "uuid": "9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f",
        "program_number": "P-123-456-789",
        "program_name": "AML Onboarding Program",
        "status": "active",
        "report_emails": [
            "compliance@example.com"
        ],
        "data_retention_months": 12,
        "event_grouping": "separate",
        "max_separate_events": 10,
        "default_risk_level": "low",
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
    },
    "api_reference": "00000000-0000-0000-0000-000000000000"
}
```

Standard error responses: 400, 401, 402, 403, 404, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))