GET/v1/displays/{id}

Read a display document

operation ID: get_v1_displays_by_id

Overview

Read a display document. Display operations store, validate, resolve, export, and navigate visualization documents used by operator interfaces.

When to use it

Use it when an application needs to read a display document.
Use it when a user interface needs to organize, save, validate, or resolve an operational display.

Quick example

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

cURL

curl --request GET \
  --url "$ORDINATE_URL/v1/displays/00000000-0000-4000-8000-000000000001" \
  --header "Authorization: Bearer $ORDINATE_TOKEN"

Expected output · 200

Display document

Example 200 output

{
  "id": "00000000-0000-4000-8000-000000000001",
  "folder_id": "00000000-0000-4000-8000-000000000001",
  "name": "string",
  "kind": "string",
  "schema_version": "string",
  "tx_id": 0,
  "document": {
    "kind": "display",
    "meta": {
      "layout": "structured",
      "name": "string"
    },
    "ordinate_display": "string"
  },
  "lint": [
    {
      "widget_id": "string",
      "code": "string",
      "message": "string",
      "severity": "note"
    }
  ]
}

The cURL request supplies the documented path and query values and asks OrdinateDB to read a display document. The documented 200 response is display document.

How it works

Display documents are versioned independently from their folders, while resolve and time routes prepare a document for a specific asset and viewing window.

Reference

Required capability: read
Authorization scope: handler-resolved target

Parameters

Name	In	Required	Type and constraints
`id`	path	yes	`string`format: uuid
`as_of_ns`	query	no	`integer` UTC Unix timestamp in nanoseconds format: int64

Request body

This operation has no request body.

Responses

200Display document

application/json

documentDisplayDocumentrequired

DisplayDocument

The frozen envelope (overview §1). Unknown-but-versioned fields survive in `x`.

kindDocKindrequired

DocKind

string

values: display · playlist · session

layersarrayoptional

array

Layer

idstringrequired
namestringrequired
visibleany JSONoptional: visible: bool OR a binding object — kept as raw JSON (Spec 05 binding is W-later).

metaMetarequired

Meta

descriptionstring | nulloptional
form_factorsarrayoptional: array
string
layoutLayoutrequired: Layout
string
values: structured · free
namestringrequired
templatestring | nulloptional

ordinate_displaystringrequired

schema semver "MAJOR.MINOR".

priority_orderarrayoptional

array

string

scale_groupsarrayoptional

array

ScaleGroup

idstringrequired
maxnumber | nulloptional: format: double
minnumber | nulloptional: format: double
modeScaleModerequired: ScaleMode
string
values: template-range · autofit · explicit
xobjectoptional

timeall ofoptional

all of

option 1

DisplayTimeContext

endstringrequired

navigatorNavigatorSettingsrequired

NavigatorSettings

visiblebooleanrequired

startstringrequired

timezoneDisplayTimezonerequired

DisplayTimezone

one of

option 1

modestringrequired

unknown fields rejected

option 2

modestringrequired
timezonestringrequired

unknown fields rejected

widgetsarrayoptional

array

Widget

bindingsall ofoptional

all of

option 1

WidgetBindings

any of

option 1

TrendBindings

kindTrendBindingKindrequired

TrendBindingKind

string

values: trend

tracesarrayrequired

array

TrendTraceBinding

attributeAttributeSelectorrequired

AttributeSelector

one of

option 1

kindstringrequired
namestringrequired

option 2

attribute_idstringrequired: format: uuid
kindstringrequired

option 3

kindstringrequired
namestringrequired
reasonstringrequired

continuityContinuityClassrequired

ContinuityClass

string

values: continuous · stepped · event

labelstringrequired

limitsany JSONoptional

penTrendPenrequired

TrendPen

glyphPenGlyphrequired: PenGlyph
string
values: circle · square · triangle · diamond
tokenstringrequired

quantity_kind_idstring | nulloptional

format: uuid

scale_groupstringrequired

unit_idstring | nulloptional

format: uuid

option 2

any JSON

gridany JSONoptional

idstringrequired

layerstring | nulloptional

linkany JSONoptional

multistateany ofoptional

any of

option 1

Multistate

bandsarrayrequired: array
any JSON

option 2

null

rangeany ofoptional

Spec 04 §2.4 window object, verbatim (no parallel range grammar).

any of

option 1

Window

one of

option 1

endstringrequired
startstringrequired
typestringrequired

option 2

laststringrequired
typestringrequired

option 3

The authored anchor is NEVER erased/rewritten (honesty-render LAW): `resolved` carries the RESULT of resolving it (or an explicit unresolved reason) ALONGSIDE the original `anchor`, never in place of it. Populated by `crate::resolve::resolve_document_windows`; `None` before resolution runs (the as-authored, pre-resolve state — e.g. straight off `transcode::from_yaml`).

anchorany JSONrequired

resolvedany ofoptional

any of

option 1

AnchorResolution

one of

option 1

endstringrequired
startstringrequired
statestringrequired

option 2

reasonstringrequired
statestringrequired

option 2

null

typestringrequired

option 2

null

time_overrideany ofoptional

any of

option 1

TimeRangeExpression

endstringrequired
startstringrequired

option 2

null

typeWidgetKindrequired

WidgetKind

string

The FULL Spec 09 catalogue — schema-complete day-one. v1 renderers cover a subset; unrendered kinds render an honest placeholder tile (W3), never a schema break.

values: trend · bullet · sparkline · value-tile · table · state-indicator · episode-gantt · xy · dot-bubble · bar · box · strip · interval-summary · heatmap · treemap · multiline-text · picture · line · symbol

xobjectoptional

Reserved extension bag — round-trip-preserved, never interpreted.

folder_idstringrequired

format: uuid

idstringrequired

format: uuid

kindstringrequired

lintarrayrequired

array

codestringrequired
messagestringrequired
severitystringrequired
widget_idany ofrequired: any of
option 1
string
option 2
null

unknown fields rejected

namestringrequired

schema_versionstringrequired

tx_idintegerrequired

format: int64

unknown fields rejected

Example 200 output

{
  "id": "00000000-0000-4000-8000-000000000001",
  "folder_id": "00000000-0000-4000-8000-000000000001",
  "name": "string",
  "kind": "string",
  "schema_version": "string",
  "tx_id": 0,
  "document": {
    "kind": "display",
    "meta": {
      "layout": "structured",
      "name": "string"
    },
    "ordinate_display": "string"
  },
  "lint": [
    {
      "widget_id": "string",
      "code": "string",
      "message": "string",
      "severity": "note"
    }
  ]
}

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"
}

404Display 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/displays/00000000-0000-4000-8000-000000000001`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`
  }
});

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 Displays.

Read a display document

Overview

When to use it

Quick example

How it works

Reference

Parameters

Request body

Responses

Code examples

Related topics