POST/v1/annotations/query

Query annotations

operation ID: post_v1_annotations_query

Overview

Query annotations. 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 query annotations.
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/query" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{}'

Expected output · 200

Filtered annotations, counts, or clusters

Example 200 output

{
  "annotations": [
    {
      "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
    }
  ],
  "clusters": [
    {}
  ],
  "counts": [
    {}
  ],
  "next_cursor": "string"
}

The cURL request sends the smallest contract-derived body and asks OrdinateDB to query annotations. The documented 200 response is filtered annotations, counts, or clusters.

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

No parameters.

Request body

application/json

authorsarrayoptional

array

kindstringrequired
principalstringrequired

unknown fields rejected

clusterobjectoptional

unknown fields rejected

rangeobjectrequired

unknown fields rejected

end_nsintegerrequired: UTC Unix timestamp in nanoseconds
format: int64
start_nsintegerrequired: UTC Unix timestamp in nanoseconds
format: int64

unknown fields rejected

width_pxintegerrequired

format: int64

unknown fields rejected

cursorstringoptional

event_timeobjectoptional

unknown fields rejected

end_nsintegerrequired: UTC Unix timestamp in nanoseconds
format: int64
start_nsintegerrequired: UTC Unix timestamp in nanoseconds
format: int64

unknown fields rejected

include_repliesbooleanoptional

limitintegeroptional

format: int64

record_timeobjectoptional

unknown fields rejected

end_nsintegerrequired: UTC Unix timestamp in nanoseconds
format: int64
start_nsintegerrequired: UTC Unix timestamp in nanoseconds
format: int64

unknown fields rejected

returnstringoptional

subtreeobjectoptional

unknown fields rejected

asset_idstringrequired: format: uuid

unknown fields rejected

tagsarrayoptional

array

string

target_typesarrayoptional

array

string

targetsarrayoptional

array

string

textstringoptional

unknown fields rejected

Example request body

{}

Responses

200Filtered annotations, counts, or clusters

application/json

annotationsarrayrequired

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

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

clustersany ofrequired

any of

option 1

array

object with arbitrary properties

option 2

null

countsany ofrequired

any of

option 1

array

object with arbitrary properties

option 2

null

next_cursorany ofrequired

any of

option 1

string

option 2

null

unknown fields rejected

Example 200 output

{
  "annotations": [
    {
      "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
    }
  ],
  "clusters": [
    {}
  ],
  "counts": [
    {}
  ],
  "next_cursor": "string"
}

400Malformed query, selector, target, or cursor

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

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/query`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({})
});

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.

Query annotations

Overview

When to use it

Quick example

How it works

Reference

Parameters

Request body

Responses

Code examples

Related topics