Core Model
Trio exposes two interaction styles:- Synchronous check: one request, one immediate result
- Asynchronous jobs: create a job, then receive progress/results by polling, webhook, or SSE
Endpoints by Monitoring Mode
| Endpoint | Purpose | Typical output |
|---|---|---|
POST /check-once | One immediate yes/no check | JSON response |
POST /live-monitor | Detect when a condition becomes true | Job lifecycle + trigger result |
POST /live-digest | Generate summaries over time windows | Job lifecycle + summary results |
Delivery Patterns
1. Synchronous JSON
UsePOST /check-once when you need a direct answer in one call.
2. Polling
Create a monitor or digest job, then pollGET /jobs/{job_id} until terminal status.
3. Webhooks
Includewebhook_url in the request body to receive push callbacks.
4. SSE
SendAccept: text/event-stream for live event streaming during request handling.
Delivery Selection Rules
POST /live-monitor
webhook_urlpresent -> webhook modeAccept: text/event-streamand nowebhook_url-> SSE mode- otherwise -> polling mode
POST /live-digest
Accept: text/event-streamand nowebhook_url-> SSE modewebhook_urlpresent -> webhook mode- otherwise -> polling mode
Picking the Right Pattern
- Prefer
check-oncefor validation and quick decision points. - Prefer polling for simple backend jobs.
- Prefer webhooks for workflow automation.
- Prefer SSE for live progress in apps.
Next Steps
- Job states and transitions: Job Lifecycle
- Endpoint-level response behavior: Live Monitor
- Delivery with callbacks: Use Webhooks
- Delivery with polling: Use Polling
- Delivery with streams: Use SSE Streaming