Create a monitor

curl "https://herculeradar.com/api/v1/monitors" \
  --request POST \
  --header "Authorization: Bearer hr_live_…" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{"name":"Acme"}'

Tool name create_monitor. It takes the same input and returns the same { data, meta } envelope as REST, because both call the same function.

Start watching a brand, product or competitor. Include every spelling people actually use — the domain and the @handle as well as the name — because matching is literal. Optional query_mode (any/all/phrase), watch_accounts, feed_urls and review_urls.

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 80
    },
    "keywords": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string"
      }
    },
    "exclude_keywords": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string"
      }
    },
    "query_mode": {
      "type": "string",
      "enum": [
        "any",
        "all",
        "phrase"
      ]
    },
    "watch_accounts": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "feed_urls": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "review_urls": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "x",
          "reddit",
          "youtube",
          "linkedin",
          "threads",
          "hn",
          "news",
          "reviews"
        ]
      }
    },
    "backfill_hours": {
      "type": "integer",
      "enum": [
        24,
        72,
        168,
        720,
        1440,
        2160,
        4320
      ]
    },
    "group_name": {
      "type": "string",
      "enum": [
        "my_brand",
        "competitors",
        "custom"
      ]
    },
    "group_id": {
      "type": "string",
      "format": "uuid"
    }
  }
}

{
  "data": {
    "id": "2c1a9f77-1b31-4d6a-9d2e-0f6a2b3c4d5e",
    "name": "Acme",
    "keywords": [
      "Acme",
      "acme.dev",
      "@acmehq"
    ],
    "exclude_keywords": [
      "acme corp cartoon"
    ],
    "query_mode": "any",
    "watch_accounts": [],
    "feed_urls": [],
    "review_urls": [],
    "sources": [
      "x",
      "reddit",
      "youtube"
    ],
    "group_name": "my_brand",
    "active": true,
    "scan_interval_minutes": 15,
    "last_scanned_at": "2026-09-01T09:20:00.000Z",
    "backfill_hours": 168
  },
  "meta": {
    "capability": "create_monitor",
    "requestId": "req_9f2b4a8c1d0e",
    "idempotencyReplayed": false,
    "docs": "https://herculeradar.com/docs/reference/create_monitor"
  }
}

Requires the monitors:write scope. A credential without it gets 403 FORBIDDEN. Resources in projects the credential cannot reach answer 404 NOT_FOUND rather than 403, so ids cannot be probed across tenants.

Send an Idempotency-Key header. A completed response is replayed for 24 hours, so a retry after a timeout cannot create a duplicate.