Monitors API

01Quickstart

One request to POST /v1/monitors/create. Set $STELQ_KEY in your environment and run this as-is — it is generated from the live contract, not transcribed.

# 0) (Optional, free) See the plan and the price before paying.
curl -X POST https://api.stelq.com/v1/monitors/plan \
  -H "Authorization: Bearer $STELQ_KEY" -H "Content-Type: application/json" \
  -d '{"query":"Anything about Regulation E: rule changes, CFPB guidance, enforcement","interval":"6h"}'

# 1) Create the monitor — charged $0.05 per block of 12 queries on 201.
curl -X POST https://api.stelq.com/v1/monitors/create \
  -H "Authorization: Bearer $STELQ_KEY" -H "Content-Type: application/json" \
  -d '{"query":"Anything about Regulation E: rule changes, CFPB guidance, enforcement","interval":"6h","notify_threshold":"notable"}'

# 2) Read what changed (the first event, within ~5 min, is the baseline).
curl https://api.stelq.com/v1/monitors/$MONITOR_ID/events?limit=10 \
  -H "Authorization: Bearer $STELQ_KEY"

02Authentication

Every request carries a bearer token in the Authorization header. Copied agent payloads reference the $STELQ_KEY environment variable, so set it in your agent's environment rather than pasting a live secret into a prompt or a chat log.

Authorization: Bearer $STELQ_KEY

03Parameters

{
  "query": "Anything about Regulation E (electronic fund transfers): rule changes, CFPB guidance, enforcement actions",
  "interval": "6h",
  "notify_threshold": "notable",
  "webhook": "https://example.com/hooks/stelq"
}

04Endpoints

05How it runs

How a monitor runs: create (or plan → create) compiles the watch plan and returns the monitor with pricing and next_check_at. Within 5 minutes the first check runs and writes the BASELINE (the state of affairs; readable as baseline_md on the detail call). Every later check on your cadence retrieves the plan's queries and direct sources, diffs against everything the monitor has already seen, gates off-topic pages, and — when something is new — writes one event with significance (none / minor / notable / major, scored against the baseline using the compiled rubric), a one-line headline, a summary_md and the new_items. Quiet checks are recorded too (significance: "none"). Each completed check bills pricing.per_check_usd; failed checks are never billed. If the balance can't cover a check it is skipped and the schedule pushed; three consecutive skips auto-pause the monitor (paused_reason: "insufficient_balance") — top up and resume. Read events back with the events routes, or take a webhook for the ones that clear your notify_threshold.

06Webhooks

Pass a webhook (https URL) on create — or set one later with PATCH — and STELQ POSTs a signed event for the first check (monitor.baseline, always, so you can verify the integration) and for every later check whose significance clears your notify_threshold (monitor.change). Quiet checks never notify. The event is a claim-check with a routing hint: data.significance and data.headline let you route without a fetch; data.result_url returns the full check (summary, items) over the authenticated API. Same envelope, headers, secret and retries as Research webhooks — one receiver handles both.

{
  "id": "evt_01JX9A4M2KQ7",
  "type": "monitor.change",
  "api_version": "2026-06-01",
  "occurred_at": "2026-08-28T14:07:12Z",
  "attempt": 1,
  "data": {
    "monitor_id": "a01aede0-ffb0-41a8-ae64-b92190596f59",
    "monitor_name": "Regulation E watch",
    "event_id": "5c1b7e2a-0d4f-4c8e-9a3b-2f6d8e1c4b7a",
    "significance": "notable",
    "headline": "CFPB issues proposed rule expanding Reg E error-resolution to P2P fraud",
    "new_count": 3,
    "result_url": "https://api.stelq.com/v1/monitors/a01aede0-ffb0-41a8-ae64-b92190596f59/events/5c1b7e2a-0d4f-4c8e-9a3b-2f6d8e1c4b7a"
  }
}

Signature headers: webhook-id · webhook-timestamp · webhook-signature

Verify before you trust the body: recompute HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{rawBody} with your account signing secret (whsec_…, revealed any time under API Keys in the console — the SAME secret that signs Research webhooks), then constant-time compare it against the webhook-signature header (format v1,<base64>). Reject timestamps older than ~5 minutes, and always verify against the raw request bytes.

• At-least-once delivery — dedupe on data.event_id (+ type). One check can never produce two different events.
• Acknowledge fast: return a 2xx within 10 seconds, then do any slow work asynchronously — otherwise we time out and retry.
• On any non-2xx or timeout we retry with exponential backoff, up to 8 attempts over ~24h, then dead-letter. GET …/events/{event_id} shows the delivery state for that check.
• Webhook down? Nothing is lost — every check is recorded; read the events feed.
• monitor.baseline fires once (the first check). monitor.change fires only for checks at or above notify_threshold; a check with significance: "none" never notifies.
• The secret is snapshotted onto the monitor when the webhook is set. Rotating your account secret never breaks a running monitor; re-set the webhook (PATCH) to pick up a new secret.

07Response

A successful call returns JSON with the result inline.

{
  "monitor": {
    "id": "a01aede0-ffb0-41a8-ae64-b92190596f59",
    "name": "Regulation E watch",
    "status": "active",
    "interval_minutes": 360,
    "notify_threshold": "notable",
    "webhook_url": "https://example.com/hooks/stelq",
    "pricing": {
      "size_blocks": 1,
      "queries": 8,
      "create_usd": 0.05,
      "per_check_usd": 0.01,
      "checks_per_day": 4,
      "est_daily_usd": 0.04
    },
    "next_check_at": "2026-08-28T14:05:00Z",
    "watch_plan": {
      "queries": [
        "Regulation E amendments 2026",
        "CFPB Regulation E guidance",
        "…"
      ],
      "preferred_domains": [
        "consumerfinance.gov",
        "federalregister.gov"
      ],
      "freshness_days": 7,
      "significance_rubric": "major: a final rule or enforcement action; notable: proposed rule, official guidance; minor: commentary…",
      "sources": [
        {
          "type": "feed",
          "url": "https://www.consumerfinance.gov/about-us/newsroom/feed/",
          "healthy": true
        }
      ]
    }
  },
  "webhook": {
    "url": "https://example.com/hooks/stelq",
    "signed_with": "account_signing_secret",
    "events": [
      "monitor.baseline",
      "monitor.change"
    ]
  },
  "first_check": "within 5 minutes; the first check establishes the baseline your updates are measured against"
}

08Errors

09Rate limits

plan and create each compile a watch plan (one model call + live source verification), so they share a limit of 10 per minute per account; a 429 carries a Retry-After header. Reads, edits, pause/resume and delete are unmetered. Checks themselves run on our schedule and never count against your limit.