Skip to main content

​
Endpoint Selection

If you need…Use
A fast yes/no answer right nowPOST /check-once
Condition detection over timePOST /live-monitor
Periodic narrative summariesPOST /live-digest

​
Delivery Mode Selection

Delivery modeBest forHow to use
Synchronous JSONImmediate answersPOST /check-once
PollingBackend workers and scriptsCreate job, then GET /jobs/{job_id}
WebhookEvent-driven automationSend webhook_url in request body
SSEReal-time client updatesSend Accept: text/event-stream

​
Practical Recommendations

  1. Start with check-once to validate condition wording.
  2. Move to live-monitor when you need trigger detection over time.
  3. Use live-digest when you need summaries, not binary triggers.
  4. Choose polling first for simple backend workflows.
  5. Add webhooks or SSE when you need push delivery.

​
Delivery Behavior by Endpoint

​
POST /check-once

  • Returns one JSON result.
  • No job lifecycle to track.

​
POST /live-monitor

  • webhook_url present: webhook mode.
  • Accept: text/event-stream and no webhook_url: SSE mode.
  • Otherwise: polling mode (job_id + GET /jobs/{job_id}).

​
POST /live-digest

  • Accept: text/event-stream and no webhook_url: SSE mode.
  • webhook_url present: webhook mode.
  • Otherwise: polling mode.

​
Next Steps