> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Watch

> Update a watch (PATCH semantics: partial body)

## Overview

Partial update: omitted fields are unchanged. Requires the `portfolios:manage` scope.

## Path Parameters

<ParamField path="id" type="string" required>Watch ID (`wat_*`).</ParamField>

## Body Parameters

All fields optional.

<ParamField body="name" type="string">1-255 chars.</ParamField>
<ParamField body="query" type="object">Replace the entire saved query DSL. Same validation rules as [Create Watch](/api-reference/monitoring/watches/create).</ParamField>
<ParamField body="delivery_mode" type="string">Only `always_per_alert` is accepted (same as [Create Watch](/api-reference/monitoring/watches/create)).</ParamField>

<ParamField body="status" type="string">
  `active` or `paused`. Use [Pause](/api-reference/monitoring/watches/pause) /
  [Resume](/api-reference/monitoring/watches/resume) instead when you just want to toggle
  evaluation, they're equivalent but read more clearly in your own code. A third status,
  `disabled`, exists but isn't settable here: it's the state a watch moves to when you
  [delete](/api-reference/monitoring/watches/delete) it, and it's excluded from
  [List Watches](/api-reference/monitoring/watches/list) by default.
</ParamField>

<ParamField body="metadata" type="object">Free-form metadata.</ParamField>

## Response

Returns the updated `Watch`.

## Errors

| Status | `type`             | When                                                                              |
| ------ | ------------------ | --------------------------------------------------------------------------------- |
| 400    | `validation_error` | Invalid `query`, an unsupported `delivery_mode`, or an unsupported `status` value |
| 404    | `not_found`        | Watch doesn't exist or belongs to another org                                     |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.signa.so/v1/watches/wat_8kLm2nPq" \
    -H "Authorization: Bearer sig_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: rename-watch-2026-06-12" \
    -d '{ "name": "Class 9 filings (US only)" }'
  ```

  ```typescript TypeScript theme={null}
  import { Signa } from "@signa-so/sdk";
  const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });

  await signa.watches.update("wat_8kLm2nPq", {
    name: "Class 9 filings (US only)",
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json theme={null}
  {
    "id": "wat_8kLm2nPq",
    "object": "watch",
    "name": "Class 9 filings (US only)",
    "watch_type": "class",
    "query": {
      "version": "v2",
      "filters": { "niceClasses": [9], "jurisdictions": ["US"] },
      "trigger_events": ["trademark.created", "trademark.status_changed"]
    },
    "delivery_mode": "always_per_alert",
    "status": "active",
    "alert_count_24h": 2,
    "last_alerted_at": "2026-07-05T09:12:00.000Z",
    "metadata": {},
    "created_at": "2026-05-11T10:00:00.000Z",
    "updated_at": "2026-07-06T08:30:00.000Z",
    "request_id": "req_3vXq7RmT"
  }
  ```
</ResponseExample>

## Related Endpoints

* [Retrieve Watch](/api-reference/monitoring/watches/retrieve) - fetch the current state of a watch
* [Pause Watch](/api-reference/monitoring/watches/pause) - stop evaluation without deleting the watch
* [Resume Watch](/api-reference/monitoring/watches/resume) - restart evaluation
* [Delete Watch](/api-reference/monitoring/watches/delete) - stop evaluation permanently