Skip to main content
POST
/
v1
/
watches
Create Watch
curl --request POST \
  --url https://api.example.com/v1/watches \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "watch_type": "<string>",
  "criteria": {},
  "triggers": [
    "<string>"
  ],
  "scope_filters": {},
  "delivery_channels": [
    "<string>"
  ]
}
'
{
  "id": "wat_Nk3pR8sT",
  "object": "watch",
    "name": "AURORA brand watch",
    "watch_type": "keyword",
    "criteria": {
      "query": "AURORA",
      "match": "phonetic"
    },
    "triggers": ["new_filing", "status_change"],
    "scope_filters": {
      "office_code": ["uspto", "euipo", "ukipo"],
      "nice_classes": [9, 35, 42]
    },
    "delivery_channels": ["api"],
    "status": "active",
    "alert_count": 0,
  "created_at": "2026-03-24T15:00:00Z",
  "livemode": true,
  "request_id": "req_kD0uV6wX"
}

​
Overview

Creates a watch that monitors trademark offices for changes matching your criteria. When a matching event occurs, Signa generates an alert that you can retrieve via the List Alerts endpoint. Watches support five types of monitoring, flexible criteria, and configurable triggers. Each organization can have up to 100 active watches.

​
Request Body

​
name
string
required
Watch name for your reference (e.g., “AURORA brand watch”)
​
watch_type
string
required
Type of watch: status, competitor, class, keyword, portfolio
​
criteria
object
required
Flexible JSONB criteria object. Structure varies by watch_type. See examples below.
​
triggers
string[]
required
Events that generate alerts: new_filing, status_change, any_change
​
scope_filters
object
Additional JSONB filters to scope the watch (e.g., jurisdictions, Nice classes).
​
delivery_channels
string[]
default:"[\"api\"]"
How to deliver alerts. Currently supported: api. Defaults to ["api"].

​
Watch Types and Criteria

Watch TypePurposeExample Criteria
keywordMonitor for new filings matching a text query{"query": "AURORA", "match": "phonetic"}
statusTrack status changes on specific marks{"trademark_ids": ["tm_abc123"]}
competitorMonitor a competitor’s filing activity{"owner_name": "Acme Corp"}
classMonitor new filings in specific Nice classes{"nice_classes": [9, 42]}
portfolioMonitor all marks in a portfolio{"portfolio_id": "ptf_n1o2p3"}

​
Response

​
response
object
{
  "id": "wat_Nk3pR8sT",
  "object": "watch",
    "name": "AURORA brand watch",
    "watch_type": "keyword",
    "criteria": {
      "query": "AURORA",
      "match": "phonetic"
    },
    "triggers": ["new_filing", "status_change"],
    "scope_filters": {
      "office_code": ["uspto", "euipo", "ukipo"],
      "nice_classes": [9, 35, 42]
    },
    "delivery_channels": ["api"],
    "status": "active",
    "alert_count": 0,
  "created_at": "2026-03-24T15:00:00Z",
  "livemode": true,
  "request_id": "req_kD0uV6wX"
}

​
Code Examples

curl -X POST https://api.signa.so/v1/watches \
  -H "Authorization: Bearer sig_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AURORA brand watch",
    "watch_type": "keyword",
    "criteria": {
      "query": "AURORA",
      "match": "phonetic"
    },
    "triggers": ["new_filing", "status_change"],
    "scope_filters": {
      "office_code": ["uspto", "euipo", "ukipo"],
      "nice_classes": [9, 35, 42]
    },
    "delivery_channels": ["api"]
  }'

​
Errors

StatusTypeDescription
400validation_errorMissing required fields or invalid values
401unauthorizedMissing or invalid API key
409conflictA watch with the same name already exists
422unprocessable_entityInvalid criteria for the given watch_type
429rate_limitedToo many requests