POST/v1/read/episode-overlay

Normalize closed episodes onto a 0..1 comparison grid

operation ID: post_v1_read_episode_overlay

Overview

Normalize closed episodes onto a 0..1 comparison grid. 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 normalize closed episodes onto a 0..1 comparison grid.
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/episode-overlay" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "resolve": {
      "select": {
        "kind": "attributes_named",
        "content": {
          "name": "string"
        }
      },
      "scope": {}
    },
    "episodes": {},
    "points": 0,
    "mode": "u-grid"
  }'

Expected output · 200

Episode overlays; unresolved_lives is emitted when life-over-life selection cannot fill requested lives

Example 200 output

{
  "episodes": [
    {
      "episode": {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "string",
        "template": "string",
        "start_ns": 0,
        "end_ns": 0
      },
      "series": [
        {
          "attribute_id": "00000000-0000-4000-8000-000000000001",
          "points": [
            {
              "u": 0,
              "ts_ns": 0
            }
          ],
          "provenance": {}
        }
      ]
    }
  ]
}

The cURL request sends the smallest contract-derived body and asks OrdinateDB to normalize closed episodes onto a 0..1 comparison grid. The documented 200 response is episode overlays; unresolved_lives is emitted when life-over-life selection cannot fill requested lives.

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

episodesany ofrequired

Arbitrary JSON value

any of

option 1

object with arbitrary properties

option 2

array

any items

option 3

string

option 4

number

option 5

integer

option 6

boolean

option 7

null

modestringrequired

pointsintegerrequired

minimum: 0

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

Example request body

{
  "resolve": {
    "select": {
      "kind": "attributes_named",
      "content": {
        "name": "string"
      }
    },
    "scope": {}
  },
  "episodes": {},
  "points": 0,
  "mode": "u-grid"
}

Responses

200Episode overlays; unresolved_lives is emitted when life-over-life selection cannot fill requested lives

application/json

episodesarrayrequired

array

episodeobjectrequired

unknown fields rejected

end_nsintegerrequired: UTC Unix timestamp in nanoseconds
format: int64
idstringrequired: format: uuid
namestringrequired
start_nsintegerrequired: UTC Unix timestamp in nanoseconds
format: int64
templatestringrequired

unknown fields rejected

seriesarrayrequired

array

attribute_idstringrequired

format: uuid

pointsarrayrequired

array

interpolatedbooleanoptional

no_valuestringoptional

qualityintegeroptional

minimum: 0

ts_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64

unumberrequired

format: double

valueany ofoptional

any of

option 1

number

option 2

integerformat: int64

option 3

boolean

option 4

string

option 5

enum_setstringrequired
ordinalintegerrequired: format: int64

unknown fields rejected

provenanceProvenancerequired

Provenance

chunks_prunedintegeroptional

minimum: 0

clock_suspectbooleanoptional

compat_modestringoptional

computedstringoptional

contains_unknown_arrivalbooleanoptional

lineageLineageoptional

Lineage

rule_idstringrequired

format: uuid

rule_version_rangearrayrequired

min items: 2 · max items: 2

array · min 2 · max 2

integerformat: int64

windowsarrayrequired

array

end_nsintegerrequired: format: int64
evaluated_at_nsintegerrequired: format: int64
rule_versionintegerrequired: format: int64
start_nsintegerrequired: format: int64

unknown fields rejected

lossy_rangesarrayoptional

array

LossyRange

end_nsintegerrequired: format: int64
start_nsintegerrequired: format: int64
tagstringrequired

unknown fields rejected

model_as_of_nsintegeroptional

format: int64

percent_goodnumberoptional

percent_time_filterednumberoptional

provisional_windowsarrayoptional

array

RangeNs

end_nsintegerrequired: format: int64
start_nsintegerrequired: format: int64

unknown fields rejected

quarantined_rangesarrayoptional

array

RangeNs

end_nsintegerrequired: format: int64
start_nsintegerrequired: format: int64

unknown fields rejected

tiers_touchedarrayoptional

array

string

values: hot · warm · cold

window_resolvedRangeNsoptional

RangeNs

end_nsintegerrequired: format: int64
start_nsintegerrequired: format: int64

unknown fields rejected

unresolved_livesarrayoptional

array

asset_idstringrequired: format: uuid
reasonstringrequired

unknown fields rejected

Example 200 output

{
  "episodes": [
    {
      "episode": {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "string",
        "template": "string",
        "start_ns": 0,
        "end_ns": 0
      },
      "series": [
        {
          "attribute_id": "00000000-0000-4000-8000-000000000001",
          "points": [
            {
              "u": 0,
              "ts_ns": 0
            }
          ],
          "provenance": {}
        }
      ]
    }
  ]
}

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/episode-overlay`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "resolve": {
    "select": {
      "kind": "attributes_named",
      "content": {
        "name": "string"
      }
    },
    "scope": {}
  },
  "episodes": {},
  "points": 0,
  "mode": "u-grid"
})
});

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

const data = await response.json();
console.log(data);

Wire conventions — Understand the prerequisite concepts and transport behavior for this operation.
REST endpoint index — Find other operations in Reads.

Normalize closed episodes onto a 0..1 comparison grid

Overview

When to use it

Quick example

How it works

Reference

Parameters

Request body

Responses

Code examples

Related topics