OrdinateDB

Documentation

product Pre-releaseunwritten sections are marked
POST/v1/annotations

Create an annotation

operation ID: post_v1_annotations

Overview

Create an annotation. Annotations attach human context and evidence to operational data without changing the recorded series values.

When to use it

  • Use it when an application needs to create an annotation.
  • Use it when an operator needs to add, find, revise, or preserve context around an event or time range.

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/annotations" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "target": {
      "urn": "string"
    },
    "author": {
      "kind": "human",
      "principal": "string"
    }
  }'

Expected output · 201

Created annotation identity

Example 201 output

{
  "id": "00000000-0000-4000-8000-000000000001",
  "version": 0
}

The cURL request sends the smallest contract-derived body and asks OrdinateDB to create an annotation. The documented 201 response is created annotation identity.

How it works

Annotations are versioned records. Content can be revised or redacted while the API retains the documented history and attachment relationships.

Reference

Required capability
annotate
Authorization scope
handler-resolved target

Parameters

No parameters.

Request body

application/json

attachmentsarrayoptional

array

stringformat: uuid
authorobjectrequired
unknown fields rejected
kindstringrequired
principalstringrequired
unknown fields rejected
bodyany ofoptional

any of

option 1

string

option 2

null
geometryany ofoptional

any of

option 1

one of

option 1

kindstringrequired
namestringoptional
sourceone ofrequired

one of

option 1

kindstringrequired
unitstringrequired
valuenumberrequired
unknown fields rejected

option 2

kindstringrequired
traitstringrequired
unknown fields rejected

option 3

attribute_idstringrequired
format: uuid
kindstringrequired
unknown fields rejected
unknown fields rejected

option 2

kindstringrequired
unknown fields rejected

option 3

kindstringrequired
timeany ofoptional

any of

option 1

end_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64
start_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64
unknown fields rejected

option 2

null
valueany ofoptional

any of

option 1

maxnumberrequired
minnumberrequired
unitstringrequired
unknown fields rejected

option 2

null
unknown fields rejected

option 2

null
reasonstringoptional
reply_toany ofoptional

any of

option 1

stringformat: uuid

option 2

null
tagsarrayoptional

array

string
targetobjectrequired
unknown fields rejected
urnstringrequired
unknown fields rejected
unknown fields rejected

Example request body

{
  "target": {
    "urn": "string"
  },
  "author": {
    "kind": "human",
    "principal": "string"
  }
}

Responses

201Created annotation identity

application/json

idstringrequired
format: uuid
versionintegerrequired
format: int64
unknown fields rejected

Example 201 output

{
  "id": "00000000-0000-4000-8000-000000000001",
  "version": 0
}
400Malformed annotation, target, tag, or geometry

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"
}
403annotate 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"
}
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/annotations`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "target": {
    "urn": "string"
  },
  "author": {
    "kind": "human",
    "principal": "string"
  }
})
});

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

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

Related topics