OrdinateDB

Documentation

product Pre-releaseunwritten sections are marked
PUT/v1/annotations/{id}

Edit an annotation

operation ID: put_v1_annotations_by_id

Overview

Edit 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 edit 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 PUT \
  --url "$ORDINATE_URL/v1/annotations/00000000-0000-4000-8000-000000000001" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "author": {
      "kind": "human",
      "principal": "string"
    }
  }'

Expected output · 200

New annotation version

Example 200 output

{
  "version": 0
}

The cURL request sends the smallest contract-derived body and asks OrdinateDB to edit an annotation. The documented 200 response is new annotation version.

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

NameInRequiredType and constraints
idpathyes
stringformat: uuid

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
tagsarrayoptional

array

string
unknown fields rejected

Example request body

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

Responses

200New annotation version

application/json

versionintegerrequired
format: int64
unknown fields rejected

Example 200 output

{
  "version": 0
}
400Malformed edit or attempted immutable target/reply change

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"
}
404Annotation 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/annotations/00000000-0000-4000-8000-000000000001`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "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