OrdinateDB

Documentation

product Pre-releaseunwritten sections are marked
POST/v1/episodes/query

Query episodes

operation ID: post_v1_episodes_query

Overview

Query episodes. Episodes represent bounded operational events and the genealogy links between related events.

When to use it

  • Use it when an application needs to query episodes.
  • Use it when an application tracks an incident, batch, excursion, or other event interval and its relationships.

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/episodes/query" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{}'

Expected output · 200

Filtered, keyset-paginated episodes

Example 200 output

{
  "episodes": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "template": {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "string",
        "version": 0
      },
      "name": "string",
      "state": "open",
      "start_ns": 0,
      "end_ns": 0,
      "parent": "00000000-0000-4000-8000-000000000001",
      "asset_refs": [
        {
          "asset_id": "00000000-0000-4000-8000-000000000001",
          "role": "string"
        }
      ],
      "attributes": {},
      "flags": [
        "string"
      ],
      "origin": "trigger",
      "void": {
        "reason": "string",
        "at_ns": 0,
        "by": "string"
      },
      "created_at_ns": 0,
      "version": 0
    }
  ],
  "next_cursor": "string"
}

The cURL request sends the smallest contract-derived body and asks OrdinateDB to query episodes. The documented 200 response is filtered, keyset-paginated episodes.

How it works

Templates define episode shape, episodes carry event state, and genealogy links connect parent, child, or otherwise related records.

Reference

Wire-format note. Voided episodes are hidden by default and are restored only when include_voided=true; direct GET by id still serves them.
Required capability
read
Authorization scope
handler-resolved target

Parameters

No parameters.

Request body

application/json

assetsobjectoptional
unknown fields rejected
downstream_ofobjectoptional
unknown fields rejected
asset_idstringrequired
format: uuid
depthone ofrequired

one of

option 1

integerminimum: 0

option 2

any JSON

constant: "*"

viaarrayoptional

array

string
unknown fields rejected
idsarrayoptional

array

stringformat: uuid
rolestringoptional
subtreeobjectoptional
unknown fields rejected
asset_idstringrequired
format: uuid
unknown fields rejected
upstream_ofobjectoptional
unknown fields rejected
asset_idstringrequired
format: uuid
depthone ofrequired

one of

option 1

integerminimum: 0

option 2

any JSON

constant: "*"

viaarrayoptional

array

string
unknown fields rejected
unknown fields rejected
cursorstringoptional
flagsarrayoptional

array

string
include_voidedbooleanoptional
limitintegeroptional
format: int64
overlapsobjectoptional
unknown fields rejected
end_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64
start_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64
unknown fields rejected
parentstringoptional
format: uuid
statearrayoptional

array

string

values: open · closed · voided

templatesarrayoptional

array

string
wherestringoptional
unknown fields rejected

Example request body

{}

Responses

200Filtered, keyset-paginated episodes

application/json

episodesarrayrequired

array

asset_refsarrayrequired

array

asset_idstringrequired
format: uuid
rolestringrequired
unknown fields rejected
attributesobjectrequired
childrenarrayoptional

array

stringformat: uuid
created_at_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64
end_nsany ofrequired

any of

option 1

integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

null
flagsarrayrequired

array

string
idstringrequired
format: uuid
linksany ofoptional

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
namestringrequired
originstringrequired
parentany ofrequired

any of

option 1

stringformat: uuid

option 2

null
start_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64
statestringrequired
templateobjectrequired
unknown fields rejected
idstringrequired
format: uuid
namestringrequired
versionintegerrequired
format: int64
unknown fields rejected
versionintegerrequired
format: int64
voidany ofrequired

any of

option 1

at_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64
bystringrequired
reasonstringrequired
unknown fields rejected

option 2

null
unknown fields rejected
next_cursorany ofrequired

any of

option 1

string

option 2

null
unknown fields rejected

Example 200 output

{
  "episodes": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "template": {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "string",
        "version": 0
      },
      "name": "string",
      "state": "open",
      "start_ns": 0,
      "end_ns": 0,
      "parent": "00000000-0000-4000-8000-000000000001",
      "asset_refs": [
        {
          "asset_id": "00000000-0000-4000-8000-000000000001",
          "role": "string"
        }
      ],
      "attributes": {},
      "flags": [
        "string"
      ],
      "origin": "trigger",
      "void": {
        "reason": "string",
        "at_ns": 0,
        "by": "string"
      },
      "created_at_ns": 0,
      "version": 0
    }
  ],
  "next_cursor": "string"
}
400Malformed cursor, template, filter, topology, or range

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 or unavailable

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/episodes/query`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({})
});

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

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

Related topics