Monitors API Reference

Overview

Same endpoint and auth as every SeaWeb tool: POST https://api.seaweb.tech/mcp with Authorization: Bearer sw_… and Accept: application/json, text/event-stream. Monitors need an authenticated, paid key.

Two delivery styles: poll (list_disruption_events with since= your last poll time) or push (register_disruption_webhook, HMAC-signed POSTs).

Minimal working example

# 1. Find the geo_id
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
  "name":"resolve_geo","arguments":{"text":"Kyoto"}}}

# 2. Register the standing query
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
  "name":"register_standing_query","arguments":{
    "geo_ids":["geo:kyoto"],
    "disruption_types":["strike","weather","closure"]}}}
# → echoes the containment-EXPANDED query with its query_id

# 3. Poll for events since your last check
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
  "name":"list_disruption_events","arguments":{
    "since":"2026-08-06T00:00:00Z","geo_id":"geo:kyoto"}}}

Tools

Tool	Arguments	Notes
register_standing_query	geo_ids, disruption_types, lang_scope, min_severity (1–5), corroboration_policy, expires_at, tenant_id	Types: strike, weather, closure, unrest, health, infrastructure, safety. geo_ids expand through the containment hierarchy (a country matches its regions and cities); the response echoes the expanded query and its query_id.
list_standing_queries	tenant_id	Your queries only. tenant_id is a sub-label in your own namespace, not a filter — pass the same value you registered with.
delete_standing_query	query_id, tenant_id	Idempotent; only your own queries.
list_disruption_events	since, geo_id, disruption_type, limit (default 100, max 1000)	Structured events: severity 1–5, confidence 0–1, span-grounded sources frozen at emission. truncated=true when more matched.
get_disruption_event	event_id	One event with its frozen evidence.
register_disruption_webhook	url (https), secret, tenant_id	Events POSTed as the same JSON list_disruption_events returns, signed X-SeaWeb-Signature: sha256=<hex> (HMAC-SHA256 over the raw body with your secret). The secret is never echoed back.
list_disruption_webhooks	tenant_id	Your subscriptions: id + url. Secrets never echoed.
delete_disruption_webhook	subscription_id, tenant_id	Idempotent; only your own subscriptions. An account holds one webhook URL, so delete the old one before registering a different URL.

Browser-created monitors

Browser-created monitors add a required stop_at end date and derive the tenant from the authenticated account. The account webhook is shared across its standing queries. Browser setup returns its generated signing secret once; list responses never include it. Creating needs active Growth; listing and stopping remain available after billing loss.

Common mistakes

• Forgetting the browser-generated signing secret — browser setup shows it once; save it before leaving the page.
• Skipping signature verification — recompute HMAC-SHA256 over the raw body and compare to X-SeaWeb-Signature.
• Polling without since — you'll re-read old events; pass your last poll time.
• Passing a different tenant_id on list/delete than on register — sub-labels are separate namespaces, not filters.
• Treating an empty event list as "all clear" — coverage is partial; empty can mean not covered.
• Expecting a monitor to act — alerts inform, never execute. Acting is your agent's job.