API reference · contract

OpenAPI 3.1

Overview

OrdinateDB generates its public HTTP contract from the executable route inventory. This website’s reference was built from the committed artifact at revision 996452a, not from a running server.

Use this document to inspect exact request and response shapes, validate integrations, or generate a client you maintain. Use the human-readable endpoint pages when you need workflow guidance.

Quick example

The exact source document used for these pages is published at /api/openapi-v1.json. It contains 142 operations and can be downloaded without an OrdinateDB instance.

Download

curl --fail --output openapi-v1.json \
  "https://ordinatedb.com/api/openapi-v1.json"

How it works

The website snapshot is pinned to the displayed source revision. A running installation exposes its own contract so tooling can follow the exact server it will call.

Read the contract from an installation

A running server exposes GET /v1/openapi.json. In enforced mode it requires authentication and read capability held anywhere. It remains available when the model database is not configured because the contract itself does not consult model truth.

Installed server

curl --fail \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  "$ORDINATE_URL/v1/openapi.json" \
  --output openapi-v1.json

Reference

Inspect operations

jq -r '
  .paths
  | to_entries[]
  | .key as $path
  | .value
  | to_entries[]
  | select(.key | IN("get","post","put","patch","delete"))
  | [.key | ascii_upcase, $path, .value.operationId, .value.summary]
  | @tsv
' openapi-v1.json

OrdinateDB-specific authorization metadata is carried on each operation as x-ordinate-capability and x-ordinate-scope. Wire exceptions appear as x-honest-oddity. Deprecation metadata uses standard deprecated plus x-deprecated-since, x-sunset, and x-deprecation-link.

Common patterns

Generate your own client

Client generators can consume the document directly. Generated libraries are not shipped as part of the source revision documented here, so pin your generator and review its representation of OpenAPI 3.1 unions, exact int64 values, binary bodies, and SSE or WebSocket upgrades.

Example generator invocation

docker run --rm \
  -v "$PWD:/local" \
  openapitools/openapi-generator-cli generate \
  -i /local/openapi-v1.json \
  -g typescript-fetch \
  -o /local/generated-client

This command is an example of consuming the standard document, not a promise that a particular generator release is supported or that its output is an OrdinateDB-maintained SDK.

Contract guarantees

In the OrdinateDB repository, CI checks that executable and documented routes match in both directions, the committed artifact matches generated output, and the served document matches that artifact. This site adds its own coverage gate: every operation ID in the downloaded contract maps to exactly one reference page.