OrdinateDB

Documentation

product Pre-releaseunwritten sections are marked
POST/v1/read/subscribe

Subscribe to resolved live updates over SSE

operation ID: post_v1_read_subscribe

Overview

Subscribe to resolved live updates over SSE. Resolved reads turn model selectors into time-series results while preserving binding history, quality, gaps, and provenance.

When to use it

  • Use it when an application needs to subscribe to resolved live updates over SSE.
  • Use it when a chart, report, analysis, or live view needs model-aware values rather than direct storage rows.

Quick example

Set the base URL and replace generated identifiers or credentials with values from your installation.

cURL

curl --request POST \
  --url "$ORDINATE_URL/v1/read/subscribe" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "resolve": {
      "select": {
        "kind": "attributes_named",
        "content": {
          "name": "string"
        }
      },
      "scope": {}
    }
  }'

Expected output · 200

SSE events: resolved, frame, gap, and lagged

The response uses the documented non-JSON media type.

The cURL request sends the smallest contract-derived body and asks OrdinateDB to subscribe to resolved live updates over SSE. The documented 200 response is sSE events: resolved, frame, gap, and lagged.

How it works

The server resolves requested attributes through their time-bounded series bindings, reads the applicable data, then returns the requested representation.

Reference

Required capability
read
Authorization scope
each resolved result

Parameters

No parameters.

Request body

application/json

include_snapshotbooleanoptional
resolveobjectrequired
unknown fields rejected
as_of_nsany ofoptional

any of

option 1

integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

null
include_retiredbooleanoptional
rangeany ofoptional

any of

option 1

array · min 2 · max 2

item 1
integer

UTC Unix timestamp in nanoseconds

format: int64
item 2
integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

null
scopeobjectrequired
unknown fields rejected
downstream_ofany ofoptional

any of

option 1

assetstringrequired
format: uuid
depthintegeroptional
minimum: 0
viaarrayrequired

array

string
unknown fields rejected

option 2

null
templateany ofoptional

any of

option 1

one of

option 1

contentstringrequired
format: uuid
kindstringrequired
unknown fields rejected

option 2

contentstringrequired
kindstringrequired
unknown fields rejected

option 2

null
underany ofoptional

any of

option 1

one of

option 1

contentstringrequired
kindstringrequired
unknown fields rejected

option 2

contentstringrequired
format: uuid
kindstringrequired
unknown fields rejected

option 2

null
upstream_ofany ofoptional

any of

option 1

assetstringrequired
format: uuid
depthintegeroptional
minimum: 0
viaarrayrequired

array

string
unknown fields rejected

option 2

null
unknown fields rejected
selectone ofrequired

one of

option 1

contentobjectrequired
unknown fields rejected
namestringrequired
unknown fields rejected
kindstringrequired
unknown fields rejected

option 2

contentarrayrequired

array

stringformat: uuid
kindstringrequired
unknown fields rejected

option 3

kindstringrequired
unknown fields rejected
unknown fields rejected
timestamp_formatstringoptional
unknown fields rejected

Example request body

{
  "resolve": {
    "select": {
      "kind": "attributes_named",
      "content": {
        "name": "string"
      }
    },
    "scope": {}
  }
}

Responses

200SSE events: resolved, frame, gap, and lagged

text/event-stream

string
400Invalid read request

application/json

ErrorEnvelope
codestringrequired
correlation_idstringrequired
format: uuid
detailsobjectoptional
errorstringrequired

Example 400 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}
401Authentication required

application/json

ErrorEnvelope
codestringrequired
correlation_idstringrequired
format: uuid
detailsobjectoptional
errorstringrequired

Example 401 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}
403Read capability is not granted

application/json

ErrorEnvelope
codestringrequired
correlation_idstringrequired
format: uuid
detailsobjectoptional
errorstringrequired

Example 403 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}
503Model database is not configured, unavailable, or render capacity is exhausted

application/json

ErrorEnvelope
codestringrequired
correlation_idstringrequired
format: uuid
detailsobjectoptional
errorstringrequired

Example 503 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}

Code examples

These examples are generated from the source contract. Replace the base URL, credentials, identifiers, and minimal generated values for your instance.

JavaScript

const ordinateUrl = "http://localhost:8080";
const token = "<bearer-token>";

const response = await fetch(`${ordinateUrl}/v1/read/subscribe`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "resolve": {
    "select": {
      "kind": "attributes_named",
      "content": {
        "name": "string"
      }
    },
    "scope": {}
  }
})
});

if (!response.ok) {
  throw new Error(`OrdinateDB returned ${response.status}: ${await response.text()}`);
}

const stream = response.body;
if (!stream) throw new Error("Response has no event stream");
console.log(stream);

Related topics