wss://api.decisionnode.com /v1/sessions/{id}/stream# npm install -g wscat
WSS=wss://api.decisionnode.com/v1
SESSION=ses_3f9a1c07b2e84d5f6a0c9e12 # from the open response
wscat -c "$WSS/sessions/$SESSION/stream" \
-H "Authorization: Bearer $DECISIONNODE_API_KEY"
# then type one frame per line:
> {"seq": 1, "frame": {"battery": 0.31, "obstacle": "none"}}Each text message you send is one JSON frame. Each message you receive is the reply to one frame, or an error about one frame. Frames are answered on the session's fixed part plus its recent frames.
Authentication#
AuthorizationheaderrequiredBearer dn_live_...on the WebSocket handshake, the key that opened the session. Browsers cannot set this header on a WebSocket, so connect from your server.
Path parameters#
idstringrequired- The
session_idthat Open a session returned, for exampleses_3f9a1c07b2e84d5f6a0c9e12.
Refused connections#
A connection the server cannot take opens and closes at once, before any frame, with a close code rather than an HTTP status:
4401: the key is missing or unknown. Check theAuthorizationheader.4404: no open session with this id for your key: it ended, expired, never existed or belongs to another key. Open a new session.4409: another socket holds this session, yours or one whose connection dropped. Use the socket you have; holding none, connect once more after about 60 seconds, and open a new session on the4404that follows.1013: the server is busy, your rate is reached (a connect counts as one request) or our key store is busy. The session is untouched: connect again to the samestream_urlafter a backoff.1008: a Decisions-only key ("this key may only make decisions"). The session is untouched; connect with a Full access key.1001: the server is draining. The session is untouched; connect again.1011: a fault on our side: the session is untouched when our registry could not be read, and has ended when its model's server is gone.
A plain GET without the WebSocket upgrade gets 426 with {"detail": {"error_type": "api_usage_error", "message": "This path takes a WebSocket."}}. Your workspace's balance and standing are checked at once after a connection opens: an empty balance closes it 4402, a suspended workspace 4403, and the session ends.
Frames#
{
"seq": 17,
"frame": {
"battery": 0.31,
"wind_mps": 11.4,
"distance_home_m": 820,
"obstacle": "none"
}
}Frame
seqintegerdefaultthe previous valid frame's plus one- Your number for the frame, 0 to 9007199254740991; left out, the previous valid frame's
seqplus one (0 for the first), whether or not that frame was answered. The reply carries it back, anddroppednames passed-over frames by it. framestring | object | array- What changed: a non-empty string, an object or an array, at most the session's
max_frame_tokens. Required unless the frame carries animage; beside an image it is an optional short note, held to the same limit, that joins the window like any frame. imageobject- One image, which makes this an image frame, held to the image limits of
/v1/decide(up to 10 MB and 40 megapixels). The image is seen with this frame only; it does not join the window. It has noid, since a frame holds one image. Either{media_type, data}, its base64 fitting in one 1 MiB message, or{upload_id}with an optionalmedia_type, an upload of your workspace; anything else (aurlincluded) is the frame error "image: must be {media_type, data} or {upload_id}."media_typestringimage/jpeg,image/pngorimage/webp. Required withdata; withupload_id, it must match the upload.datastring- Base64 bytes, no
data:prefix. upload_idstring- An upload's id, in place of
data.
questionsstring[]defaultall- The keys of the questions to answer this time, a non-empty list; a key named twice is answered and billed once, in the session's question order. Each frame is billed for the questions it asks.
resetbooleandefaultfalsetruedrops the recent frames from context before this one is answered.
Replies#
{
"seq": 17,
"answers": {
"mode": {
"type": "choice",
"choice": "return",
"confidence": 0.79,
"probabilities": {
"continue": 0.09,
"hold": 0.05,
"land": 0.02,
"return": 0.84
}
},
"abort": { "type": "truth", "truth": 0.07 }
},
"usage": {
"input_tokens": 91,
"output_tokens": 0,
"cost": {
"usd": 0.000003822,
"model_usd": 0.000003822,
"boosters_usd": 0,
"free_tier": false
}
},
"safety": {
"checked": true,
"harm": 0.0021,
"self_harm": 0.0008,
"flagged": []
}
}Reply
seqinteger- The sequence number of the frame this answers.
answersobject- One answer per question asked, exactly as
/v1/decideshapes it, with the same calibration. droppedinteger[]- Only when frames were passed over: the
seqof each frame that arrived while an earlier one was being answered and was superseded by this one. A dropped frame is not answered, does not join the window and is not billed. usageobject- What this frame billed:
input_tokens(the frame, its image if it has one, and the questions it asked),output_tokens, always 0, andcost, what the frame booked, as on /v1/decide. latency_msnumber- Time spent on our side for this frame, in milliseconds. On every reply; the samples here leave it out.
safetyobject- What the safety check found for this frame, as on every call:
checked, the probability of each category (harm,self_harm) andflagged, the categories above your key's thresholds. When the check did not run,checkedisfalsewith areason.
# npm install -g wscatWSS=wss://api.decisionnode.com/v1SESSION=ses_3f9a1c07b2e84d5f6a0c9e12 # from the open responsewscat -c "$WSS/sessions/$SESSION/stream" \ -H "Authorization: Bearer $DECISIONNODE_API_KEY"# then type one frame per line:> {"seq": 1, "frame": {"battery": 0.31, "obstacle": "none"}}Frame errors#
A frame the API cannot answer gets a message with its seq and an error object, error_type and message, and the socket stays open for the next frame. A refused frame's error also names the category, and the message carries safety with blocked and its usage, what it billed. A rate_limit_error or overloaded_error carries retry_after_ms, the wait before you send the frame again. A frame that got an error leaves the window as it was and is not billed, except a refused frame: the model read it, so its tokens are billed.
{
"seq": 21,
"error": {
"error_type": "api_usage_error",
"message": "The frame is 5210 tokens, the limit is 1535."
}
}| Type | When | What to do |
|---|---|---|
api_usage_error | The message is not a JSON object; a field a frame does not take; seq that is not an integer of 0 or more; no frame and no image; a frame that is an empty string; an image that is neither {media_type, data} nor {upload_id}, cannot be read or is over the image limits; questions that is not a non-empty list of the session's question keys; reset that is not true or false; text or JSON over the session's max_frame_tokens | Fix the frame; seq is null when the message could not be read as a frame. For a long frame, send only what changed and move constant detail into the session's state |
upload_not_found, upload_expired, upload_consumed, upload_media_type_mismatch | The frame's upload_id cannot be used, as on a decision | Upload the picture again; these count toward the invalid frames of a second |
rate_limit_error | Your workspace's input-token rate (or your key's own lower limit) is used up for now: frames count against it | Wait retry_after_ms, then send the frame again |
overloaded_error | No capacity for this frame right now | Wait retry_after_ms when it is set, then send the frame again: it joins the window once |
api_error | A fault on our side | Send the frame again |
refusal_error | The safety check refused this frame; error.category names harm or self_harm | Change what the frame asks. The session carries on; the refused frame never joins the window, and its tokens are billed |
Close codes#
The close code says why the socket closed, and whether to open a new session with the same body. 4401, 4404, 4409, 1013, 1008 for a Decisions-only key and 1001 can come as soon as a connection opens, and leave an open session as it was; so can 1011 when our registry could not be read. Any other close ends the session. Branch on the code: the reason text beside it is for your logs and may change.
| Code | When | What to do |
|---|---|---|
1000 | The session ended on purpose: you closed the socket, or it was ended with DELETE /v1/sessions/{id} | Open a new session when you need one |
1001 | The server holding the session is going away. During a session it has then ended; sent as soon as a connection opens (the server is draining), the session is untouched | Open a new session with the same body; it opens on a server that is up |
1006 | The connection dropped without a close frame: a network fault or a proxy reset. Your WebSocket library reports this code; the server never sends it. The session has ended | Open a new session with the same body, after a capped backoff with jitter |
1008 | A Decisions-only key, sent as soon as the connection opens ("this key may only make decisions"; the session is untouched). Or your client broke a rule of the stream: it stopped reading replies until 256 messages or 16 MiB piled up, sent more than 100 messages in one second that were not valid frames, had 64 frames that name uploads waiting for answers, or sent more than 64 messages or 8 MiB before the session was ready for them. The session has ended | Fix the client: read every reply, send valid frames, and wait for replies before sending more images |
1009 | A message over 1 MiB. The session has ended | Send the frame's image by upload_id |
1011 | Something failed on our side. The session has ended, unless it came as the connection opened while our registry could not be read | Open a new session with the same body, after a capped backoff with jitter |
1013 | Sent as soon as the connection opens: the server is busy, your workspace's or key's request rate is reached (a connect counts as one request), or our key store is busy. The session is still open | Connect again to the same stream_url after a capped backoff with jitter |
4401 | The key is missing or unknown, sent as soon as the connection opens; or the key was revoked during the session (it is checked every second), which has then ended | Check the Authorization header; opening again with the same key will not help |
4402 | Your workspace's prepaid balance is empty: checked at once after the connection opens, then during the session. The session has ended | Add credit; opening a session gets 402 until then |
4403 | Your workspace is suspended: checked at once after the connection opens, then during the session. The session has ended | Contact us; opening a session gets 403 |
4404 | No open session with this id for your key where the connection landed: it ended, expired, never existed or belongs to another key. Sent as soon as the connection opens | Open a new session with the same body |
4408 | No frame arrived for idle_timeout_seconds (120 seconds). Pings do not count. The session has ended | Open a new session with the same body when your next frame is ready |
4409 | Another socket holds this session: one is already connected, or an earlier connection of yours still holds it after that connection dropped. Sent as soon as the connection opens; the session is untouched and the socket holding it keeps it. An earlier connection's hold lapses within 60 seconds of the drop, and the session is then gone: a connect after that gets 4404 | Use the socket you have. Holding no other socket for this session, connect once more after about 60 seconds, and open a new session on the 4404 that follows |
4410 | The session reached expires_at. The session has ended | Open a new session with the same body at once; set ttl_seconds up to 3,600 for longer runs |
Limits#
| Limit | Value | Over the limit |
|---|---|---|
| Frame | Text or JSON of at most max_frame_tokens tokens (never more than 4,096; the open response's limits gives this session's value), or one image | A frame error, api_usage_error; the socket stays open |
| Image in a frame | One, of up to 10 MB and 40 megapixels, as on /v1/decide. Inline, its base64 must fit in one 1 MiB message; a larger one goes by upload_id | A frame error, api_usage_error; close code 1009 for a message over the size |
| Recent frames | Together at most window_tokens tokens, in the open response's limits | The oldest frames leave the window first |
| Window | 1 to 64 frames, 8 by default, the frame being answered included | 422 when opening |
| Lifetime | 300 seconds by default, 1 to 3,600 | 422 when opening; close code 4410 when reached |
| Idle | 120 seconds with no frame on an open socket | Close code 4408 |
| Sockets | One per session | Close code 4409 on a second connect |
| Token rate | Each frame's usage.input_tokens counts against your workspace's input-token rate (and a key's own lower limit), not its request rate | A frame error, rate_limit_error, with retry_after_ms; the socket stays open |
Notes#
- Send one frame per message, as a JSON object in a text message.
seqis yours: an integer from 0 to 9007199254740991, carried back in the reply. Rising numbers keepdroppedeasy to read; gaps are fine, so a client may skip readings.- Latest wins: if frames arrive faster than they are answered, the newest is answered and the ones passed over are listed in its reply's
dropped. To have every frame answered, send the next one after its reply. - A frame error never closes the socket. Only the close codes above end a session.
- Keepalive. The server sends WebSocket pings on an open socket, so proxies and load balancers see traffic on a quiet socket. Your library answers them with a pong on its own (both
websocketsandwsdo); the server pings every 20 seconds, and a socket with no traffic of any kind (pong, ping or message) for 45 seconds is dropped without a close frame: your side sees1006, and the session ends. Pings and pongs are not frames: they are not billed and do not reset the idle timer. - Idle sockets. A socket that carries no frame for
idle_timeout_seconds(120 seconds) closes with4408and the session ends. A loop that may pause longer, such as a drone parked on its pad, either sends its current reading inside that time, withquestionsnaming one question so the frame bills little, or lets the session close and opens a new one when it resumes. The supervisor under Clients does the second. - Send at once. You may send frames as soon as the connection opens. Up to 64 messages, 8 MiB in all, are held until the session is ready for them, then passed on in order under the same latest-wins rule as every frame. One more, or a byte past 8 MiB, before then closes the socket with
1008, and a socket that closes before the session is ready ends the session, unless it was refused with4409. - For a client that stays up, see the complete supervisor: it opens a new session after every close it did not ask for, except those that would end the same way:
4401,4402,4403,1008and1009.