OrdinateDB

Documentation

product Pre-releaseunwritten sections are marked
POST/v1/display-folders

Create a display folder

operation ID: post_v1_display_folders

Overview

Create a display folder. 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 create a display folder.
  • 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/display-folders" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "string"
  }'

Expected output · 201

Created folder

Example 201 output

{
  "folder_id": "00000000-0000-4000-8000-000000000001",
  "parent_id": "00000000-0000-4000-8000-000000000001",
  "name": "string",
  "tx_id": 0
}

The cURL request sends the smallest contract-derived body and asks OrdinateDB to create a display folder. The documented 201 response is created folder.

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

NameInRequiredType and constraints
Idempotency-Keyheaderno
string

Replays the first successful response for the same authenticated principal, route, key, and request body

max length: 255

Request body

application/json

namestringrequired
parent_idstringoptional
format: uuid
unknown fields rejected

Example request body

{
  "name": "string"
}

Responses

201Created folder

Response headers

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

application/json

folder_idstringrequired
format: uuid
namestringrequired
parent_idany ofrequired

any of

option 1

stringformat: uuid

option 2

null
tx_idintegerrequired
format: int64
unknown fields rejected

Example 201 output

{
  "folder_id": "00000000-0000-4000-8000-000000000001",
  "parent_id": "00000000-0000-4000-8000-000000000001",
  "name": "string",
  "tx_id": 0
}
400Invalid folder; 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"
}
409Folder 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"
}
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/display-folders`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "name": "string"
})
});

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

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

Related topics