Skip to main content
Open a WebSocket, send your questions once, then append text as it arrives: a call transcript, a chat, a document being written. Sage decides on everything said so far and sends a frame whenever an answer changes.

A live call

Each line moves the answers: The answers are what /decide/batch returns for the same questions. Any decision kind works.
A key sent from a browser can be read by anyone using that page. Use this pattern for your own tools; for public apps, open the stream from your server.

From a server

Send the key as a header. Append lines as they come, without waiting for a reply: with the default emit: "changes", no frame comes back when nothing changed.
Needs pip install websockets.

Frames you send

Text can only be appended. To change earlier text, open a new session. Appends that arrive while Sage is deciding are folded into the next decision.

Frames you receive

A decision frame, abridged:

Reconnecting

When the server restarts, it finishes the decision in progress, sends {"type": "error", "code": "draining", "fatal": true} and closes with code 1012. Reconnect and send start with the full text in content. Nothing is lost.

Usage

Each update is charged for the text that’s new since the last one (the whole text on the first), plus the questions. Output is the decision frame as sent. An update with no frame sent (emit: "changes" and nothing changed) has no output. ready, ping, pong, error and sig frames are free. Questions count on every update, so keep them short. Leave emit on changes.

Limits

  • Text plus questions: up to 16,384 tokens. An append past it is refused with code: "prompt_too_long", and the session stays open.
  • 600,000 characters and 32 questions per session.
  • A session with no frame from you for 300 seconds closes. Send ping to keep it open.

Verifying a stream

Every server frame is followed by a sig frame: an ECDSA P-256 signature chained over all frames so far, so a dropped, reordered or changed frame breaks the chain. The signing key is in GET /v1/attestation/report, and the exact scheme is in the OpenAPI spec under /v1/stream.