Opsis API / v1
Stream results
Receive findings as they arrive and resume interrupted streams.
Open a stream
Receive results as modules finish over Server-Sent Events (SSE). Submit with stream: true, or attach to an existing run. Use a server-side client that supports authorization headers and streaming responses.
curl -N -X POST https://api.useopsis.com/v1/searches \
-H "Authorization: Bearer $OPSIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"username","query":"jasondraper01","stream":true}'/v1/searches/{run_id}/streamThe GET stream attaches without starting or charging for a new search. A terminal run replays its results followed by done.
Handle the events
| Event | Meaning |
|---|---|
| run | First frame: run_id, type, query, and status. Save the ID. |
| result | One normalized result object. Findings may replay when reconnecting. |
| progress | Module counters, coverage, results_so_far, and named module_status. |
| done | Terminal status, total_results, coverage, results_available, error, and module counters. Check status; done is not always success. |
| reconnect | The transport deadline expired. Resume the same run after retry_after; this is not completion. |
| error | The stream was interrupted. Recover by reading or streaming the same run ID. |
event: run
data: {"run_id":"00000000-0000-4000-8000-000000000001","type":"username","query":"jasondraper01","status":"running"}
event: result
data: {"id":1,"type":"account","entity_type":"account","platform":"Example platform","value":"jasondraper01","confidence":1,"source":"example_module","metadata":{"username":"jasondraper01","name":"Jason Draper","profile_url":"https://example.com/jasondraper01"},"created_at":"2026-10-01T12:00:00Z"}
event: reconnect
data: {"run_id":"00000000-0000-4000-8000-000000000001","status":"running","reason":"stream_timeout","retry_after":1}Reconnect without duplicate searches
A stream has a transport deadline, reported as limits.stream_timeout_seconds by capabilities. On reconnect or an unexpected disconnect, use the saved run ID with GET. Never treat end-of-stream alone as successful completion.
curl -N https://api.useopsis.com/v1/searches/00000000-0000-4000-8000-000000000001/stream \
-H "Authorization: Bearer $OPSIS_API_KEY"Reattachment replays results from the beginning; deduplicate using the run ID and result ID when present, or replace your local list from a snapshot. There is no event-cursor resume contract. Ignore SSE comment lines beginning with :.