API guide

Wire conventions

Overview

These rules apply across the shipped /v1 HTTP surface. Endpoint pages remain authoritative for route-specific exceptions and expose them as wire-format notes.

Read this page when you are building a reusable client, handling exact timestamps, retrying writes, paging through results, or interpreting data quality. Following the shared rules avoids route-by-route assumptions.

Quick example

JavaScript cannot exactly represent every signed 64-bit nanosecond value. Request decimal strings when exact sample identity matters.

Exact timestamp request fragment

{
  "start_ns": "1721476800000000000",
  "end_ns": "1721476860000000000",
  "timestamp_format": "decimal-string"
}

Reference

Versioning

The major version is in the path. Within /v1, successful response fields and request meanings are not silently removed or retyped. Additive fields and routes may appear. Clients should ignore unknown response fields, but must not infer behavior from an unknown enum or capability token.

Normal deprecation notice is at least 24 months. A deprecated response carries Deprecation: true, a Sunset HTTP date, and a migration Link. Matching metadata appears in OpenAPI. The source contract currently marks no route deprecated.

Time and ranges

Time is UTC. Most low-level fields use Unix nanoseconds (int64); newer browser-sensitive fields may be exact decimal strings. Ranges use the half-open convention [start, end): the start is included and the end is excluded.

Read and streaming routes that expose timestamp_formataccept "decimal-string". In that mode, fields ending in _ns are canonical base-10 strings, preserving signed 64-bit values in JavaScript. Floating-point t_ms values are display coordinates and must not be used as durable sample identity.

Errors

JSON failures use a structured envelope. The human-readable error text is diagnostic; branch on the stable machine code. Send or log the correlation_id when asking an operator to trace the failure. details contains bounded route-specific data.

Error envelope

{
  "error": "invalid read request",
  "code": "invalid-request",
  "correlation_id": "00000000-0000-4000-8000-000000000001",
  "details": {}
}

A client may send an X-Correlation-ID request header. The response echoes or supplies the correlation identifier. Authentication and authorization failures normally use 401 and 403; some permission-filtered resource lookups deliberately return 404 to avoid revealing another principal’s object.

Capabilities and scope

Each operation declares a required capability and how its resource scope is resolved. Both appear on every endpoint page as Required capability and Authorization scope. Holding a capability somewhere does not necessarily grant it on the target asset, series, or handler-resolved resource.

Pagination

Paginated endpoints use opaque cursors. Send the returned next_cursor unchanged as the next request’s cursor. Do not decode it or build one yourself. Route schemas declare their allowed limit range. Cursor ordering remains stable under concurrent writes where the endpoint documents keyset pagination.

Idempotent mutations

Operations that declare an Idempotency-Key header use it to make retries safe. Generate a fresh opaque value for a logical operation and reuse it only when retrying that exact request. A replay of the matching request can return the stored result and identify it with Idempotency-Replayed. Reusing the key with a different body or target returns a conflict.

Idempotent mutation

curl --request POST \
  --url "$ORDINATE_URL/v1/admin/change-sets" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Idempotency-Key: 52e48d08-8ca3-4cf4-9d34-9cf908ac5d20" \
  --header "Content-Type: application/json" \
  --data @change-set.json

Content types

Most requests and responses are application/json. Attachment and export endpoints declare their binary or multipart media types explicitly. POST /v1/read/subscribe accepts a JSON request and returns text/event-stream. GET /v1/stream upgrades to WebSocket.

Provenance and quality

A successful data response can still report provisional, lossy, quarantined, filtered, clock-suspect, or human-originated input. These states travel in provenance rather than becoming HTTP errors. Clients must preserve and display the provenance attached to a value or aggregate instead of treating transport success as “good data.”