OrdinateDB

Documentation

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

Traverse episode genealogy

operation ID: post_v1_episodes_traverse

Overview

Traverse episode genealogy. Episodes represent bounded operational events and the genealogy links between related events.

When to use it

  • Use it when an application needs to traverse episode genealogy.
  • 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/traverse" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "start": "00000000-0000-4000-8000-000000000001",
    "direction": "upstream",
    "depth": 0
  }'

Expected output · 200

Reachable readable episodes and non-dangling links

Example 200 output

{
  "episodes": [
    {}
  ],
  "links": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "from_episode": "00000000-0000-4000-8000-000000000001",
      "to_episode": "00000000-0000-4000-8000-000000000001",
      "link_type": "string",
      "attributes": {},
      "created_at_ns": 0
    }
  ],
  "warnings": [
    "cycle-detected"
  ]
}

The cURL request sends the smallest contract-derived body and asks OrdinateDB to traverse episode genealogy. The documented 200 response is reachable readable episodes and non-dangling links.

How it works

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

Reference

Required capability
read
Authorization scope
handler-resolved target

Parameters

No parameters.

Request body

application/json

depthone ofrequired

one of

option 1

integerminimum: 0

option 2

any JSON

constant: "*"

directionstringrequired
include_voidedbooleanoptional
startstringrequired
format: uuid
viaarrayoptional

array

string
unknown fields rejected

Example request body

{
  "start": "00000000-0000-4000-8000-000000000001",
  "direction": "upstream",
  "depth": 0
}

Responses

200Reachable readable episodes and non-dangling links

application/json

episodesarrayrequired

array

object with arbitrary properties

linksarrayrequired

array

attributesany 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
created_at_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64
directionstringoptional
from_episodestringrequired
format: uuid
idstringrequired
format: uuid
link_typestringrequired
to_episodestringrequired
format: uuid
unknown fields rejected
warningsarrayrequired

array

string

values: cycle-detected · result-cap-exceeded

unknown fields rejected

Example 200 output

{
  "episodes": [
    {}
  ],
  "links": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "from_episode": "00000000-0000-4000-8000-000000000001",
      "to_episode": "00000000-0000-4000-8000-000000000001",
      "link_type": "string",
      "attributes": {},
      "created_at_ns": 0
    }
  ],
  "warnings": [
    "cycle-detected"
  ]
}
400Malformed traversal, depth, or link type

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"
}
404Start episode not found

application/json

ErrorEnvelope
codestringrequired
correlation_idstringrequired
format: uuid
detailsobjectoptional
errorstringrequired

Example 404 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/traverse`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "start": "00000000-0000-4000-8000-000000000001",
  "direction": "upstream",
  "depth": 0
})
});

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

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

Related topics