Create Watch

Create a watch that fires alerts when matching trademarks change

POST /v1/watches

cURL

curl -X POST "https://api.signa.so/v1/watches" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-class9-watch-2026-06-12" \
  -d '{
    "name": "Watch class 9 filings (US/EU)",
    "watch_type": "class",
    "query": {
      "version": "v1",
      "filters": {
        "niceClasses": [9],
        "jurisdictions": ["US", "EU"]
      },
      "trigger_events": ["trademark.created", "trademark.status_changed"]
    },
    "delivery_mode": "always_per_alert"
  }'

{
  "id": "wat_01HK7M3QY8VVR0K1GH1A4N2D8B",
  "object": "watch",
  "name": "Watch class 9 filings (US/EU)",
  "watch_type": "class",
  "query": {
    "version": "v1",
    "filters": {
      "niceClasses": [9],
      "jurisdictions": ["US", "EU"]
    },
    "trigger_events": ["trademark.created", "trademark.status_changed"]
  },
  "delivery_mode": "always_per_alert",
  "status": "active",
  "alert_count_24h": null,
  "last_alerted_at": null,
  "metadata": {},
  "created_at": "2026-05-11T10:00:00.000Z",
  "updated_at": "2026-05-11T10:00:00.000Z",
  "request_id": "req_01ABC..."
}

Overview

Creates a saved monitor that runs on every ingestion sync. Five watch types (mark, portfolio, owner, class, similarity) share a single query shape — the watch_type selects which scoping field is required. Resource quota (per-plan watches.maxResources) is enforced before insert.

Required scope: portfolios:manage.

The monitoring API is live, in beta — see Known beta limitations. Historical replay at create time is on the roadmap. To produce alerts for past data on an existing watch, use POST /v1/watches/{id}/replay (forward-only in v1).

Body Parameters

name · string · required

Display name (1—255 chars).

watch_type · string · required

One of mark, portfolio, owner, class, similarity. Each type requires a specific field to be populated — see Watches guide for the table.

query · object · required

v1 watch query DSL.

Show WatchQuery

version · string · required

Always "v1".

q · string

Whitespace-separated keyword query (max 20 keywords, each ≥3 chars, no stop words). Required for watch_type: "similarity".

filters · object

Filter object. Keys are camelCase (trademarkIds, ownerId, niceClasses, jurisdictions, offices, statusPrimary, …) — unknown keys, including snake_case typos like nice_classes, are rejected with 400. See the canonical filter-key list.

trigger_events · string[]

Subset of trademark.created, trademark.updated, trademark.status_changed. Default: all three.

score_threshold · number

Similarity threshold (0..1). Only matches with _score >= score_threshold fire alerts. Valid for watch_type: "similarity".

delivery_mode · string

Currently only always_per_alert is supported. Digest modes land in v1.1.

metadata · object

Free-form metadata (max 8KB).

Response

Returns the created Watch with status 201.

id · string

Watch ID (wat_*).

object · string

Always "watch".

name · string

Display name.

watch_type · string

One of the five types.

query · object

Saved query DSL.

delivery_mode · string

Delivery cadence.

status · string

Initial status: active.

alert_count_24h · integer | null

Null on create.

last_alerted_at · string | null

Null on create.

metadata · object

Echoed back.

created_at · string

ISO timestamp.

updated_at · string

ISO timestamp.

request_id · string

Request identifier.

Errors

• 400 — invalid query (forbidden DSL keys, unknown filters keys, query.match in any form, stop words, too many keywords) or missing Idempotency-Key header.
• 400 — watch_type constraint violated (e.g., portfolio without filters.trademarkIds).
• 409 — per-plan resource quota exceeded.
• 413 — query payload exceeds 256 KB.

Example

cURL

curl -X POST "https://api.signa.so/v1/watches" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-class9-watch-2026-06-12" \
  -d '{
    "name": "Watch class 9 filings (US/EU)",
    "watch_type": "class",
    "query": {
      "version": "v1",
      "filters": {
        "niceClasses": [9],
        "jurisdictions": ["US", "EU"]
      },
      "trigger_events": ["trademark.created", "trademark.status_changed"]
    },
    "delivery_mode": "always_per_alert"
  }'

{
  "id": "wat_01HK7M3QY8VVR0K1GH1A4N2D8B",
  "object": "watch",
  "name": "Watch class 9 filings (US/EU)",
  "watch_type": "class",
  "query": {
    "version": "v1",
    "filters": {
      "niceClasses": [9],
      "jurisdictions": ["US", "EU"]
    },
    "trigger_events": ["trademark.created", "trademark.status_changed"]
  },
  "delivery_mode": "always_per_alert",
  "status": "active",
  "alert_count_24h": null,
  "last_alerted_at": null,
  "metadata": {},
  "created_at": "2026-05-11T10:00:00.000Z",
  "updated_at": "2026-05-11T10:00:00.000Z",
  "request_id": "req_01ABC..."
}