PUT/v1/displays/{id}

Save a new version of a display document

operation ID: put_v1_displays_by_id

Overview

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

Expected output · 200

Updated display and lint rows

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 sends the smallest contract-derived body and asks OrdinateDB to save a new version of a display document. The documented 200 response is updated display and 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
`id`	path	yes	`string`format: uuid
`expected_tx`	query	yes	`integer`format: int64
`folder_id`	query	no	`string`format: uuid

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

200Updated display and lint rows

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

400expected_tx is required or document is invalid

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

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

409Transaction or name conflict

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/00000000-0000-4000-8000-000000000001?expected_tx=0`, {
  method: "PUT",
  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 version of a display document

Overview

When to use it

Quick example

How it works

Reference

Parameters

Request body

Responses

Code examples

Related topics