GET/v1/annotations/{id}

Read an annotation

operation ID: get_v1_annotations_by_id

Overview

Read 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 read 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 GET \
  --url "$ORDINATE_URL/v1/annotations/00000000-0000-4000-8000-000000000001" \
  --header "Authorization: Bearer $ORDINATE_TOKEN"

Expected output · 200

Current annotation version

Example 200 output

{
  "id": "00000000-0000-4000-8000-000000000001",
  "target": {
    "urn": "string"
  },
  "author": {
    "kind": "human",
    "principal": "string"
  },
  "created_at_ns": 0,
  "version": 0,
  "kind": "create",
  "body": "string",
  "tags": [
    "string"
  ],
  "attachments": [
    {
      "attachment_id": "00000000-0000-4000-8000-000000000001",
      "name": "string",
      "mime": "string",
      "size_bytes": 0,
      "content_hash": "string",
      "redacted": false
    }
  ],
  "reply_to": "00000000-0000-4000-8000-000000000001",
  "geometry": {
    "kind": "value-line",
    "source": {
      "kind": "constant",
      "value": 0,
      "unit": "string"
    }
  },
  "event_time": {
    "start_ns": 0,
    "end_ns": 0
  },
  "redacted": false,
  "edited_at_ns": 0
}

The cURL request supplies the documented path and query values and asks OrdinateDB to read an annotation. The documented 200 response is current 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: read
Authorization scope: handler-resolved target

Parameters

Name	In	Required	Type and constraints
`id`	path	yes	`string`format: uuid
`include_replies`	query	no	`boolean`

Request body

This operation has no request body.

Responses

200Current annotation version

application/json

attachmentsarrayrequired

array

attachment_idstringrequired: format: uuid
content_hashstringrequired
mimestringrequired
namestringrequired
redactedbooleanrequired
size_bytesintegerrequired: format: int64

unknown fields rejected

authorobjectrequired

unknown fields rejected

kindstringrequired
principalstringrequired

unknown fields rejected

bodyany ofrequired

any of

option 1

string

option 2

null

created_at_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64

edited_at_nsany ofrequired

any of

option 1

integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

null

event_timeany ofrequired

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

geometryany ofrequired

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

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

idstringrequired

format: uuid

kindstringrequired

redactedbooleanrequired

repliesarrayoptional

array

attachmentsarrayrequired

array

attachment_idstringrequired: format: uuid
content_hashstringrequired
mimestringrequired
namestringrequired
redactedbooleanrequired
size_bytesintegerrequired: format: int64

unknown fields rejected

authorobjectrequired

unknown fields rejected

kindstringrequired
principalstringrequired

unknown fields rejected

bodyany ofrequired

any of

option 1

string

option 2

null

created_at_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64

edited_at_nsany ofrequired

any of

option 1

integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

null

event_timeany ofrequired

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

geometryany ofrequired

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

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

idstringrequired

format: uuid

kindstringrequired

redactedbooleanrequired

reply_toany ofrequired

any of

option 1

stringformat: uuid

option 2

null

tagsarrayrequired

array

string

targetobjectrequired

unknown fields rejected

urnstringrequired

unknown fields rejected

versionintegerrequired

format: int64

unknown fields rejected

reply_toany ofrequired

any of

option 1

stringformat: uuid

option 2

null

tagsarrayrequired

array

string

targetobjectrequired

unknown fields rejected

urnstringrequired

unknown fields rejected

versionintegerrequired

format: int64

unknown fields rejected

Example 200 output

{
  "id": "00000000-0000-4000-8000-000000000001",
  "target": {
    "urn": "string"
  },
  "author": {
    "kind": "human",
    "principal": "string"
  },
  "created_at_ns": 0,
  "version": 0,
  "kind": "create",
  "body": "string",
  "tags": [
    "string"
  ],
  "attachments": [
    {
      "attachment_id": "00000000-0000-4000-8000-000000000001",
      "name": "string",
      "mime": "string",
      "size_bytes": 0,
      "content_hash": "string",
      "redacted": false
    }
  ],
  "reply_to": "00000000-0000-4000-8000-000000000001",
  "geometry": {
    "kind": "value-line",
    "source": {
      "kind": "constant",
      "value": 0,
      "unit": "string"
    }
  },
  "event_time": {
    "start_ns": 0,
    "end_ns": 0
  },
  "redacted": false,
  "edited_at_ns": 0
}

400Invalid annotation id

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

403read 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: "GET",
  headers: {
    Authorization: `Bearer ${token}`
  }
});

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 Annotations.

Read an annotation

Overview

When to use it

Quick example

How it works

Reference

Parameters

Request body

Responses

Code examples

Related topics