POST/v1/displays

Save a new display document

operation ID: post_v1_displays

Overview

Save a new 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 save a new 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 POST \
  --url "$ORDINATE_URL/v1/displays?folder_id=00000000-0000-4000-8000-000000000001" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "kind": "display",
    "meta": {
      "layout": "structured",
      "name": "string"
    },
    "ordinate_display": "string"
  }'

Expected output · 201

Saved display and non-blocking lint rows

Example 201 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 sends the smallest contract-derived body and asks OrdinateDB to save a new display document. The documented 201 response is saved display and non-blocking lint rows.

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: display-author
Authorization scope: handler-resolved target

Parameters

Name	In	Required	Type and constraints
`folder_id`	query	yes	`string`format: uuid
`Idempotency-Key`	header	no	`string` Replays the first successful response for the same authenticated principal, route, key, and request body max length: 255

Request body

application/json

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.

Example request body

{
  "kind": "display",
  "meta": {
    "layout": "structured",
    "name": "string"
  },
  "ordinate_display": "string"
}

application/yaml

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

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.

xobjectoptional

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

text/yaml

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

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.

xobjectoptional

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

Responses

201Saved display and non-blocking lint rows

Response headers

X-Ordinate-Idempotent-ReplayPresent with the literal value `true` when this response was replayed

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

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.

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

400Invalid display document; Invalid or oversized Idempotency-Key

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

403display-author 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"
}

409Display name conflict; Idempotency-Key was already used with a different request body

application/json

ErrorEnvelope

codestringrequired
correlation_idstringrequired: format: uuid
detailsobjectoptional
errorstringrequired

Example 409 output

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

413Display document exceeds configured byte cap

application/json

ErrorEnvelope

codestringrequired
correlation_idstringrequired: format: uuid
detailsobjectoptional
errorstringrequired

Example 413 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?folder_id=00000000-0000-4000-8000-000000000001`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "kind": "display",
  "meta": {
    "layout": "structured",
    "name": "string"
  },
  "ordinate_display": "string"
})
});

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.

Save a new display document

Overview

When to use it

Quick example

How it works

Reference

Parameters

Request body

Responses

Code examples

Related topics