Skip to main content
POST
/
v1
/
watches
curl -X POST "https://api.signa.so/v1/watches" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -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..."
}

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.

​
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.

​
Query Parameters

​
from_saved_search
string
Hydrate query from an existing saved search (ssr_...). When set, the request body’s query may be omitted.
​
backfill_days
integer
Backfill alerts for the last N days against existing data (0—365).

​
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
v1 watch query DSL. Required unless ?from_saved_search= is set.
​
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, stop words, too many keywords, query.match as object).
  • 400 — watch_type constraint violated (e.g., portfolio without filters.trademarkIds).
  • 404 — from_saved_search references a missing or cross-org saved search.
  • 409 — per-plan resource quota exceeded.
  • 413 — query payload exceeds 256 KB.

​
Example

curl -X POST "https://api.signa.so/v1/watches" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -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..."
}