Skip to content
DecisionNodeDecisionNdedocs
  • Guides
  • API reference
  • Examples
  • Playground

start here

  • QuickstartGet startedGet an API key, send one request with three questions, and branch your code on the typed answers. Plain HTTPS, nothing to install.
  • POST /v1/decideAPI referenceAnswer typed questions about a state, optional images and video frames. One request, one buffered JSON response, one answer per question.
  • QuestionsConceptsQuestions say what to decide. Each one has a type that fixes the shape of its answer: a choice from your options, a score on your scale, a…
  • ConfidenceConceptsProbabilities are calibrated per question type, so a threshold means what it says on the data we measure.
  • ImagesConceptsSend up to 16 images and text in the same request. The model reads printed and handwritten text, amounts, dates, objects and layout, and…
  • Batch jobsPatternsSend up to 10,000 requests in one file and collect the answers later, at a lower price than live calls.
  • Pricing and billingEvery workspace runs on a plan: Starter, Pro, Business or Dedicated.
↑↓ moveopen7 suggestions
Get API keyGet API key
DecisionNodeDecisionNde

Get started

  • Introduction
  • Quickstart
  • CLI
  • Playground
  • Console and keys
  • With coding agents
  • MCP server
  • Examples

Concepts

  • State
  • Questions
  • Choice
  • Score
  • Truth
  • Number
  • Points and boxes
  • Images
  • Video
  • Boosters
  • Collections
  • Confidence
  • Determinism
  • API keys

Knowledge

  • Overview
  • Documents
  • In a decision
  • Pricing and your data
  • When a rule does not appear

Models

  • DecisionNode
  • DecisionNode Flash
  • DecisionNode Edge
  • Limits
  • Versions
  • Dedicated capacity

Fine-tuning

  • Overview
  • Prepare your dataset
  • Upload and validation
  • Start a training run
  • Watch a run
  • The quality gate
  • Use your model
  • Limits and pricing

Patterns

  • Confidence-gated routing
  • Form router
  • Fan-out
  • Guardrails
  • Control loops
  • Batch jobs
  • Keys on devices
  • Bill your customers per device
  • Publishable keys

Integrations

  • Home Assistant
  • MQTT bridge
  • ROS 2

API reference

  • Overview
  • POST/v1/decide
  • POST/v1/systemone
  • GET/v1/models
  • POST/v1/uploads
  • /v1/keys
  • GET/v1/keys/{key_id}/usage
  • GET/v1/usage
  • POST/v1/credit
  • Errors
  • Safety check
  • Rate limits

Sessions API

  • Sessions overview
  • POSTOpen a session
  • WSStream frames
  • DELEnd a session

Collections API

  • Overview
  • POSTCreate a collection
  • GETList collections
  • GETRetrieve a collection
  • DELDelete a collection
  • POSTEnroll a face
  • GETList items
  • PATCHUpdate an item
  • DELDelete an item
  • POSTAdd a document
  • PUTReplace a document
  • GETRetrieve an item
  • GETList passages
  • DELDelete failed documents
  • POSTSearch a knowledge base

Batch API

  • The batch object
  • POSTCreate a batch
  • POSTAdd requests
  • POSTFinalize a batch
  • GETRetrieve a batch
  • GETGet batch results
  • POSTCancel a batch
  • GETList batches

Pricing and billing

  • Pricing and billing
  • Refer & earn

Policies

  • Responsible use
  • Data and privacy
  • Benchmarks
  • Pricing
  • Playground
Get API key
  • Guides
  • API reference
  • Examples
  • Playground

Get started

  • Introduction
  • Quickstart
  • CLI
  • Playground
  • Console and keys
  • With coding agents
  • MCP server
  • Examples

Concepts

  • State
  • Questions
  • Choice
  • Score
  • Truth
  • Number
  • Points and boxes
  • Images
  • Video
  • Boosters
  • Collections
  • Confidence
  • Determinism
  • API keys

Knowledge

  • Overview
  • Documents
  • In a decision
  • Pricing and your data
  • When a rule does not appear

Models

  • DecisionNode
  • DecisionNode Flash
  • DecisionNode Edge
  • Limits
  • Versions
  • Dedicated capacity

Fine-tuning

  • Overview
  • Prepare your dataset
  • Upload and validation
  • Start a training run
  • Watch a run
  • The quality gate
  • Use your model
  • Limits and pricing

Patterns

  • Confidence-gated routing
  • Form router
  • Fan-out
  • Guardrails
  • Control loops
  • Batch jobs
  • Keys on devices
  • Bill your customers per device
  • Publishable keys

Integrations

  • Home Assistant
  • MQTT bridge
  • ROS 2

API reference

  • Overview
  • POST/v1/decide
  • POST/v1/systemone
  • GET/v1/models
  • POST/v1/uploads
  • /v1/keys
  • GET/v1/keys/{key_id}/usage
  • GET/v1/usage
  • POST/v1/credit
  • Errors
  • Safety check
  • Rate limits

Sessions API

  • Sessions overview
  • POSTOpen a session
  • WSStream frames
  • DELEnd a session

Collections API

  • Overview
  • POSTCreate a collection
  • GETList collections
  • GETRetrieve a collection
  • DELDelete a collection
  • POSTEnroll a face
  • GETList items
  • PATCHUpdate an item
  • DELDelete an item
  • POSTAdd a document
  • PUTReplace a document
  • GETRetrieve an item
  • GETList passages
  • DELDelete failed documents
  • POSTSearch a knowledge base

Batch API

  • The batch object
  • POSTCreate a batch
  • POSTAdd requests
  • POSTFinalize a batch
  • GETRetrieve a batch
  • GETGet batch results
  • POSTCancel a batch
  • GETList batches

Pricing and billing

  • Pricing and billing
  • Refer & earn

Policies

  • Responsible use
  • Data and privacy
  1. docs
  2. /
  3. Sessions API

Sessions

Streaming decisions. Open a session once with the fixed part of your request, then stream frames over a WebSocket and get a typed decision for each one. More than 10 decisions a second? Use a session.

on this page7 sections
  1. Endpoints
  2. How a session runs
  3. How a session behaves
  4. Limits
  5. Billing
  6. Clients
  7. What to watch out for

A call to /v1/decide sends everything every time: the instructions, the context and the questions. A session sends that fixed part once. The model keeps your context loaded for the life of the session, so each frame you stream costs only its own tokens, and each reply carries the same typed, calibrated answers as a normal call. Control loops covers when to use one.

POST /v1/sessionsinstructions, state, questions, window 8

sent once, billed once

frames, each only what changedseq

  1. 7
  2. 8
  3. 9
  4. 10
  5. 11
  6. 12
  7. 13
  8. 14
  9. 15
  10. 16
  11. 17
  12. 18
  13. 19
window, last 8

replies, newest wins

    your controller

    mode

    continuereturn

    Takes the mode when the answer clears your threshold. It flies the vehicle, keeps its own limits and runs its own failsafe.

    A session opened once with instructions, state, questions and a window of 8 frames. Frames 15 to 19 stream in; each is answered on the fixed part plus the last 8 frames. Frames 17 and 18 arrive while 16 is being answered, so 18, the newest, is answered and the reply reports 17 as dropped. The reply to frame 19 says mode return with confidence 0.79 and abort 0.07, and your controller takes that mode.

    Endpoints#

    • POST /v1/sessions

      What it does
      Opens a session with the fixed part: model, instructions, state, questions, window
    • WS /v1/sessions/{id}/stream

      What it does
      Takes frames and sends one typed reply per answered frame
    • DELETE /v1/sessions/{id}

      What it does
      Ends the session and frees its context
    Session endpoints
    EndpointWhat it does
    POST /v1/sessionsOpens a session with the fixed part: model, instructions, state, questions, window
    WS /v1/sessions/{id}/streamTakes frames and sends one typed reply per answered frame
    DELETE /v1/sessions/{id}Ends the session and frees its context

    How a session runs#

    1. 1.POST /v1/sessions with the fixed part. You get a session_id, the stream_url and expires_at. See Open a session.
    2. 2.Connect to stream_url over a WebSocket, with your key in the Authorization header. See Stream frames.
    3. 3.Send one frame per message, each with its own seq. Read one reply per answered frame.
    4. 4.End it with DELETE /v1/sessions/{id} or by closing the socket. It also ends at expires_at. See End a session.
    5. 5.When the socket closes and you did not close it, open a new session with the same body and carry on, unless the code says a new session would meet the same fault: 4401, 4402, 4403, 1008 or 1009. A 4409 when you connect again to the same session, holding no other socket for it, means your dropped connection still holds it: connect once more after about 60 seconds, and open a new session on the 4404 that follows. See Close codes.

    How a session behaves#

    • Rolling window. Each frame is answered on the fixed part plus the last window frames, itself included (8 by default, 1 to 64), so the model sees what just happened. Older frames leave the context, and when the recent frames pass the session's window_tokens the oldest leave first. Send "reset": true to start the window over.
    • Latest wins. If frames arrive faster than they are answered, the newest frame is answered and the frames passed over are listed in its reply's dropped. A client that falls behind gets the newest answer, never a backlog. If you need every frame answered, send the next one after its reply.
    • Order. Replies come in the order frames are answered, one per answered frame. A reply's answers are for its frame only; nothing is answered twice.
    • A failed frame changes nothing. A frame that gets an error leaves the window as it was, so you can send it again: a frame retried after overloaded_error joins the window once.
    • Lifetime. A session ends at expires_at (ttl_seconds after it opens: 300 by default, at most 3,600), after 120 seconds with no frame on its socket, when the socket closes, or when you end it. The server pings an open socket to keep it open through proxies.
    • Reconnecting. A session cannot be rejoined: its context goes when the socket closes. Open a new session with the same body, connect to its stream_url, and carry on streaming. The supervisor under Clients does this.
    • One socket per session. Run several sessions on several sockets, within the sessions your key may hold open.
    • Refused frames. The safety check runs on every frame. A frame it refuses gets a frame error with refusal_error, never joins the window, and the socket stays open for the next frame. The model read it, so its tokens are billed.
    • Your controller decides without us. When no fresh reply has arrived by your deadline, your controller keeps its mode or runs its own failsafe.

    Limits#

    • Frame

      Value
      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
      Over the limit
      A frame error, api_usage_error; the socket stays open
    • Image in a frame

      Value
      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
      Over the limit
      A frame error, api_usage_error; close code 1009 for a message over the size
    • Recent frames

      Value
      Together at most window_tokens tokens, in the open response's limits
      Over the limit
      The oldest frames leave the window first
    • Window

      Value
      1 to 64 frames, 8 by default, the frame being answered included
      Over the limit
      422 when opening
    • Fixed part

      Value
      Small enough to leave room for the window and the longest question
      Over the limit
      400 max_tokens_exceeded when opening
    • Lifetime

      Value
      300 seconds by default, 1 to 3,600
      Over the limit
      422 when opening; close code 4410 when reached
    • Idle

      Value
      120 seconds with no frame on an open socket
      Over the limit
      Close code 4408
    • Sockets

      Value
      One per session
      Over the limit
      Close code 4409 on a second connect
    • Open sessions per key

      Value
      4, unless we set yours otherwise
      Over the limit
      429 session_limit_exceeded when opening
    • Token rate

      Value
      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
      Over the limit
      A frame error, rate_limit_error, with retry_after_ms; the socket stays open
    Session limits
    LimitValueOver the limit
    FrameText 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 imageA frame error, api_usage_error; the socket stays open
    Image in a frameOne, 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_idA frame error, api_usage_error; close code 1009 for a message over the size
    Recent framesTogether at most window_tokens tokens, in the open response's limitsThe oldest frames leave the window first
    Window1 to 64 frames, 8 by default, the frame being answered included422 when opening
    Fixed partSmall enough to leave room for the window and the longest question400 max_tokens_exceeded when opening
    Lifetime300 seconds by default, 1 to 3,600422 when opening; close code 4410 when reached
    Idle120 seconds with no frame on an open socketClose code 4408
    SocketsOne per sessionClose code 4409 on a second connect
    Open sessions per key4, unless we set yours otherwise429 session_limit_exceeded when opening
    Token rateEach frame's usage.input_tokens counts against your workspace's input-token rate (and a key's own lower limit), not its request rateA frame error, rate_limit_error, with retry_after_ms; the socket stays open

    Billing#

    session = opening tokens × price

    + sum(frame tokens × price)

    opening tokens
    the instructions, the state and the questions, billed once when the session opens: the open response's usage
    frame tokens
    each answered frame's own tokens, its image if it has one, plus the questions it asks: the reply's usage
    price
    the price per input token of the session's model in force when the session opened, for the open and every frame, whatever changes later ($0.042 per million on DecisionNode and $0.035 on DecisionNode Flash today)

    Output stays free. The context is never billed again per frame, which is what makes a long session cheap. Dropped frames and frames that got an error are not billed, except a frame the safety check refused: the model read it, so its tokens are billed. See Pricing and billing.

    Clients#

    A complete supervisor for a survey drone, in Python and TypeScript. It opens a session, streams the newest telemetry at your sensor's rate, hands each typed answer to your own controller, and keeps the session alive: when the socket closes with 1001, 1006, 1011, 4404, 4408, 4409 or 4410 it opens a new session with the same body, after a capped backoff with jitter (at once after 4410, and after 4408 when your feed sends its next reading). Opening waits out a network fault, 408, 429, 529 and any 5xx. Your controller keeps flying throughout.

    import asyncio, json, os, random
    import requests
    import websockets  # pip install "websockets>=14"
    
    API = "https://api.decisionnode.com/v1"
    AUTH = {"Authorization": f"Bearer {os.environ['DECISIONNODE_API_KEY']}"}
    MODE_AT, ABORT_AT = 0.7, 0.9   # your thresholds, in config
    REOPEN = {1001, 1006, 1011, 4404, 4408, 4409, 4410}  # a new session carries on after these
    RETRY = {408, 429, 529}         # open again after a wait (and any 5xx)
    MAX_BACKOFF = 30                # seconds
    
    
    async def open_session(body):
        """POST /v1/sessions. Waits out a network fault, 408, 429, 529 and 5xx;
        raises on the rest."""
        backoff = 1.0
        while True:
            wait = 0.0
            try:
                r = await asyncio.to_thread(
                    requests.post, f"{API}/sessions", headers=AUTH, json=body, timeout=10
                )
            except (requests.ConnectionError, requests.Timeout):
                r = None  # the network is down or slow: retried like a 5xx
            if r is not None:
                if r.ok:
                    return r.json()
                if r.status_code not in RETRY and r.status_code < 500:
                    r.raise_for_status()  # 400, 401, 402, 403, 422: retrying will not help
                wait = float(r.headers.get("Retry-After", 0))
            await asyncio.sleep(max(wait, backoff * random.uniform(0.5, 1)))
            backoff = min(backoff * 2, MAX_BACKOFF)
    
    
    async def feed(telemetry, latest):
        """Reads your sensor feed for the whole run and keeps only the newest reading.
    
        It runs outside the session loop on purpose: cancelling a task that iterates
        an async generator closes the generator for good, so a sender that read the
        feed directly would end it at the first reconnect.
        """
        async for reading in telemetry:
            if latest.full():
                latest.get_nowait()  # latest wins on your side too
            latest.put_nowait(reading)
    
    
    async def run_session(session, latest, autopilot):
        """Streams frames until the socket closes. Returns (close code, replies read)."""
        try:
            ws = await websockets.connect(session["stream_url"], additional_headers=AUTH)
        except websockets.InvalidStatus as refused:
            if refused.response.status_code == 401:
                raise  # a bad key: reopening will not help
            return 1006, 0  # the session ended before the socket opened
        except OSError:
            return 1006, 0  # the network is down: reopen after a backoff
    
        replies = 0
        async with ws:
    
            async def send_frames():
                seq = 0
                while True:
                    reading = await latest.get()
                    seq += 1
                    await ws.send(json.dumps({"seq": seq, "frame": reading}))
    
            async def read_replies():
                nonlocal replies
                async for message in ws:
                    reply = json.loads(message)
                    if "error" in reply:  # this frame was not answered; the socket stays open
                        print("frame", reply.get("seq"), reply["error"]["error_type"])
                        continue
                    replies += 1
                    # latest wins: reply["dropped"] lists frames passed over;
                    # the newest answer is the one that counts
                    mode = reply["answers"]["mode"]
                    abort = reply["answers"]["abort"]
                    # the autopilot flies; the session only proposes a mode
                    if abort["truth"] >= ABORT_AT:
                        autopilot.request_mode("return", seq=reply["seq"])
                    elif mode["confidence"] >= MODE_AT:
                        autopilot.request_mode(mode["choice"], seq=reply["seq"])
                    # below both bars the autopilot keeps its current mode
    
            sender = asyncio.create_task(send_frames())
            try:
                await read_replies()
            except websockets.ConnectionClosed:
                pass
            finally:
                sender.cancel()  # safe: it reads the queue, never your feed
                # collect its end (a cancel, or a send on a closed socket) so it is never left unread
                await asyncio.gather(sender, return_exceptions=True)
        return ws.close_code or 1006, replies
    
    
    async def supervise(body, telemetry, autopilot):
        """Keeps a session open for as long as your loop runs. Returns the close code
        that ended it for good (1000 or 4401)."""
        latest = asyncio.Queue(maxsize=1)
        feeder = asyncio.create_task(feed(telemetry, latest))
        backoff = 1.0
        try:
            while True:
                session = await open_session(body)
                code, replies = await run_session(session, latest, autopilot)
                while code == 1013:  # busy: the session is still open, so connect to it again
                    await asyncio.sleep(backoff * random.uniform(0.5, 1))
                    backoff = min(backoff * 2, MAX_BACKOFF)
                    code, replies = await run_session(session, latest, autopilot)
                if code not in REOPEN:
                    return code
                if replies:
                    backoff = 1.0  # that session worked: start the backoff over
                if code == 4408:
                    # your feed went quiet: reopen when its next reading arrives
                    latest.put_nowait(await latest.get())
                elif code != 4410:  # an expired session reopens at once
                    await asyncio.sleep(backoff * random.uniform(0.5, 1))
                    backoff = min(backoff * 2, MAX_BACKOFF)
                # the autopilot keeps its mode while a new session opens with the same body
        finally:
            feeder.cancel()

    What to watch out for#

    • Plan for 1006. A dropped network or a proxy that resets connections closes the socket without a close frame. It is the most common way a long-lived socket on a moving vehicle ends: treat it like 1011 and reopen. The server's pings keep a quiet socket open through most proxies; keep your library's automatic pong on.
    • Keep the sensor feed outside the session. Read it in one long-lived task and hand each socket the newest reading, as the supervisor does. A feed tied to one socket ends with it.
    • Cap the backoff. Reopen at once after 4410; after 1001, 1006, 1011 and 4404 wait a growing delay with jitter, at most 30 seconds, and start over once a session has answered frames.
    • Keep keys on your server. Browsers cannot set the Authorization header on a WebSocket, so connect from your backend or your vehicle's companion computer.
    • Never the sole means of control. A session feeds your controller. See Control loops.
    previousRate limitsnextOpen a session

    DecisionNode is built and run by Bynn Intelligence, Inc.

    • Home
    • Playground
    • Examples
    • Console
    • Responsible use
    • Terms
    • Acceptable use
    • Privacy
    • Data processing
    • Defence addendum
    • Cookies
    • Affiliate program

    on this page

    1. Endpoints
    2. How a session runs
    3. How a session behaves
    4. Limits
    5. Billing
    6. Clients
    7. What to watch out for