03 · http api · 32 endpoints

HTTP API reference.

One base URL per tenant instance. TLS 1.3 only. Bearer auth on every /v1/... path; mutating routes additionally honour Idempotency-Key. Request bodies cap at 8 MiB (the NDJSON batch route lifts that cap and applies its own per-line + total-buffer accounting).

auth & headers

Header	Required	Notes
Authorization: Bearer <token>	Every /v1/* route	Tenant-scoped. /health, /ready, /metrics are public.
Idempotency-Key: <ulid\|uuid>	Optional, mutating routes	Same key + same body = cached response. Different body with same key = 409.
Content-Type	POST / PUT	`application/json` by default; `text/plain` for schemas; `application/x-ndjson` on the streaming batch route.
Accept: text/event-stream	/v1/tenants/:t/watch	SSE stream. Server pushes one event per change burst.
X-OC-Query-Id	Response only	ULID for the query. Pass it to `POST /v1/queries/:id/cancel`.
X-OC-Replication: degraded	Response only	Write succeeded here, but the required follower acks did not arrive within the sync window. Nothing guarantees a replica holds the write, so a failover can lose it. Surface as a warning.
Retry-After: <seconds>	Response only (429)	Honour it. Clients should back off, not hammer.

errors

Every non-2xx response is a JSON document of the form { "error": "code", "message": "...", "request_id": "..." }. Quote request_id in support tickets.

Status	Code	Meaning
400	validation_failed	Body or query parameters malformed.
401	unauthorized	Bearer missing, invalid, or not scoped to this tenant.
402	quota_exceeded	Authed and under RPS, but credit is exhausted.
403	forbidden	Token cannot reach this resource.
404	not_found	Schema / row / migration not registered.
409	conflict	Idempotency replay-mismatch, lease busy, or migration wrong-state.
413	body_too_large	Body over 8 MiB (or NDJSON line over 1 MiB).
429	rate_limited	Per-bearer token bucket drained. Honour `Retry-After`.
499	cancelled	Query cancelled via `POST /v1/queries/:id/cancel`.
500/503	server_error / fenced	5xx; retry with backoff if idempotent. 503 means this node is refusing writes - it no longer holds the writer lease, or its store is fenced and needs an operator. Re-read the lease to find the current holder.

Schemas

TOML manifests describe a table - its primary key, columns, indexes, and relations. The engine indexes everything off the manifest, so registering one is the prerequisite to any row write.

POST /v1/tenants/:tenant/schemas - Register or update a TOML manifest. Body is the raw TOML; Content-Type: text/plain.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/schemas" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary @orders.toml

namespace   = "trading"
table       = "orders"
primary_key = ["order_id"]

[[columns]]
name = "order_id"
ty   = "str"
required = true

[[columns]]
name = "symbol"
ty   = "str"

[[columns]]
name = "qty"
ty   = "i64"

# Indexes are their own blocks - there is no "indexed = true" on columns.
[[indexes]]
name    = "by_symbol"
columns = ["symbol"]

response

200 OK

{ "id": "trading.orders", "version": 1 }

GET /v1/tenants/:tenant/schemas - List every schema id registered for the tenant.

request

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/schemas" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK

["trading.orders", "trading.trades", "trading.users"]

GET /v1/tenants/:tenant/schemas/:id - Fetch the raw TOML for a schema id. Response is text/plain, not JSON.

request

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/schemas/trading.orders" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK · 404 if unknown

# text/plain
namespace   = "trading"
table       = "orders"
primary_key = ["order_id"]
...

Rows (typed CRUD)

Insert, batch, and read against a registered schema. Single-row writes are atomic; the batch endpoint accepts a JSON array (atomic in one commit) or NDJSON via `application/x-ndjson` (streamed in flushable chunks).

POST /v1/tenants/:tenant/rows/:schema - Upsert a single row. `?expect=insert` skips the prior-state read for pure-insert bulk loads. Send `Idempotency-Key` to make retries safe.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/rows/trading.orders" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "order_id": "o-0001",
    "symbol":   "AAPL",
    "qty":      100
  }'

{
  "order_id": "o-0001",
  "symbol":   "AAPL",
  "qty":      100
}

response

200 OK · 400 validation · 409 idempotency replay-mismatch

{ "ok": true, "lsn": { "segment": 4, "offset": 8421007 } }

POST /v1/tenants/:tenant/rows/:schema/_batch - Atomic batch (one durable commit). JSON body: a row array. NDJSON body (Content-Type: application/x-ndjson): streamed; flushes every `?chunk=N` rows (default 1000, max 10000). 8 MiB body cap is disabled on this route.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/rows/trading.orders/_batch" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bulk-2026-05-01-batch-1" \
  -d '[
    { "order_id": "o-1", "symbol": "AAPL", "qty": 100 },
    { "order_id": "o-2", "symbol": "MSFT", "qty": 250 }
  ]'

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/rows/trading.orders/_batch?chunk=2000" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @orders.ndjson

# orders.ndjson
{"order_id":"o-1","symbol":"AAPL","qty":100}
{"order_id":"o-2","symbol":"MSFT","qty":250}

response

200 OK

{ "inserted": 2, "lsn": { "segment": 4, "offset": 8425112 } }

GET /v1/tenants/:tenant/rows/:schema/:pk - Read a row by its single-column primary key. Composite PKs must use POST /query with a ColumnScan plan.

request

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/rows/trading.orders/o-0001" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK · 404 not found

{
  "order_id": "o-0001",
  "symbol":   "AAPL",
  "qty":      100,
  "_oc_row_version": 1
}

Query - Plan tree (JSON)

The engine's native execution surface. POST a JSON Plan tree and get rows back. `?explain=true` returns the executed plan annotated with stats (EXPLAIN ANALYZE). Cancel an in-flight plan with the ULID handed back in `X-OC-Query-Id`.

POST /v1/tenants/:tenant/query - Execute a Plan tree. Bare response is `Vec<row>`; with `?explain=true` it's `{rows, explain}`.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/query" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Limit": {
      "n": 10,
      "child": {
        "Filter": {
          "predicate": { "Eq": ["status", "pending"] },
          "child":     { "Scan": { "schema": "trading.orders" } }
        }
      }
    }
  }'

response

200 OK · 400 plan parse · 499 cancelled

[
  { "order_id": "o-0001", "symbol": "AAPL", "status": "pending", ... },
  ...
]

POST /v1/tenants/:tenant/query?explain=true - EXPLAIN ANALYZE: executes the plan and returns it annotated with per-node row counts and µs timings.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/query?explain=true" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "Scan": { "schema": "trading.orders" } }'

response

200 OK

{
  "rows": [ ... ],
  "explain": {
    "op":       "Scan",
    "schema":   "trading.orders",
    "rows_out": 412,
    "elapsed_us": 1340,
    "children": []
  }
}

POST /v1/queries/:id/cancel - Flip the cancellation token for an in-flight plan. The id is the ULID returned in `X-OC-Query-Id` on the original request.

request

curl -X POST "$OC_BASE_URL/v1/queries/01HW7G5...JZ/cancel" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK (always; cancelled=false if already finished)

{ "cancelled": true }

GET /v1/tenants/:tenant/watch - Server-Sent Events stream. The connection holds open; the server pushes one event per change burst against the subscribed schemas. Ctrl-C / client close ends the subscription.

request

curl -N "$OC_BASE_URL/v1/tenants/$OC_TENANT/watch?schemas=trading.orders" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Accept: text/event-stream"

response

200 OK (text/event-stream)

event: snapshot
data: { "rows": [ ... ] }

event: snapshot
data: { "rows": [ ... ] }

SQL

A SQL surface over the same engine. SELECT, INSERT (+ RETURNING) and UPDATE execute; DELETE via /sql translates only (returns the pk, doesn't remove the row yet). BEGIN/COMMIT transactions and CREATE TABLE are supported too. Aggregates, OUTER JOINs, and chained 3+ table joins (up to 32) are supported.

POST /v1/tenants/:tenant/sql - POST `{"sql": "..."}`. Response shape varies by `kind`: `select` -> `{kind, rows}`; `insert` -> `{kind, schema, rows}`; `delete` -> `{kind, schema, pk}`.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/sql" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "sql": "SELECT order_id, symbol, qty FROM trading.orders WHERE status = '"'"'pending'"'"' LIMIT 10" }'

{
  "sql": "SELECT symbol, SUM(qty) AS shares FROM trading.orders GROUP BY symbol HAVING SUM(qty) > 1000"
}

{
  "sql": "SELECT u.email, o.order_id FROM trading.orders o INNER JOIN trading.users u ON o.user_id = u.user_id WHERE o.status = 'pending'"
}

{
  "sql": "SELECT u.email, t.exchange, o.symbol FROM trading.orders o INNER JOIN trading.users u ON o.user_id = u.user_id INNER JOIN trading.trades t ON o.order_id = t.order_id"
}

{
  "sql": "SELECT u.email, o.order_id FROM trading.users u LEFT OUTER JOIN trading.orders o ON o.user_id = u.user_id"
}

response

200 OK · 400 parse / unsupported

// SELECT
{ "kind": "select", "rows": [{"order_id":"o-1","symbol":"AAPL","qty":100}, ...] }

// INSERT (re-issue against /rows/:schema with the returned rows)
{ "kind": "insert", "schema": "trading.orders", "rows": [...] }

// DELETE (re-issue against /rows/:schema/:pk)
{ "kind": "delete", "schema": "trading.orders", "pk": "o-1" }

Vector search

HNSW ANN with cosine / dot / L2 metrics and tunable speed/recall. Default high_recall mode hits recall@10 = 0.96 at 100k vectors with p99 109 ms; fast mode runs p99 37 ms at recall 0.69. The IVF-PQ index compresses each vector for large corpora; no measured result is published at 100M scale. Optional metadata is stored alongside each vector and queryable as an equality filter on topk. Brute-force fallback for small N.

POST /v1/tenants/:tenant/vector/:table/put - Upsert one vector. Optional `metadata` object is indexed for filtered topk.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/vector/embeddings/put" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id":        "doc-001",
    "embedding": [0.012, -0.443, ...],
    "dim":       384,
    "metric":    "cosine",
    "metadata":  { "lang": "en", "tier": "premium" }
  }'

response

201 Created

// 201 Created (no body)

POST /v1/tenants/:tenant/vector/:table/topk - k-nearest neighbour search. `mode=hnsw` (default) or `mode=bruteforce`. Non-empty `filter` triggers HNSW + post-filter on metadata equality.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/vector/embeddings/topk" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query":  [0.011, -0.439, ...],
    "k":      10,
    "dim":    384,
    "metric": "cosine",
    "mode":   "hnsw",
    "filter": { "lang": "en" }
  }'

response

200 OK

[
  { "id": "doc-001", "score": 0.973 },
  { "id": "doc-127", "score": 0.952 },
  ...
]

Full-text search

Per-field, per-tenant inverted index. Tokenizer is UAX #29 (Latin / Cyrillic / CJK / Arabic / Hindi). Modes: `boolean` (AND), `bm25` (ranked, default Lucene k1=1.2 b=0.75), and `phrase` (exact contiguous tokens).

POST /v1/tenants/:tenant/fts/:table/:field - Index a document under (table, field). Re-indexing the same `doc_id` cleans stale postings.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/fts/articles/body" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "doc_id": "art-001", "text": "OriginChain ships managed AI-native storage." }'

response

201 Created

// 201 Created (no body)

GET /v1/tenants/:tenant/fts/:table/:field?q=&mode=&k= - Search. `mode=boolean|bm25|phrase` (default boolean). `k` caps results in `mode=bm25` (default 10).

request

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/fts/articles/body?q=substrate%20managed&mode=boolean" \
  -H "Authorization: Bearer $OC_TOKEN"

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/fts/articles/body?q=managed%20storage&mode=bm25&k=20" \
  -H "Authorization: Bearer $OC_TOKEN"

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/fts/articles/body?q=key-value%20storage&mode=phrase" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK

// boolean / phrase
["art-001", "art-007"]

// bm25
[ { "doc_id": "art-001", "score": 7.42 }, { "doc_id": "art-007", "score": 5.18 } ]

Elasticsearch API

Point the official @elastic client - or any Elasticsearch 7.x REST client - at /v1/tenants/:tenant/es/. The cluster reports version 7.14.2. Documents commit with the row, so a write is searchable immediately, and row-level security and column masking apply to the query itself. Search also answers the filters aggregation and the term suggester, and a _bulk action may carry if_seq_no so a write lands only if nobody changed the document first. New here? Start with Connect an Elasticsearch client.

PUT/v1/tenants/:tenant/es/:index- Create an index and its mapping. Field types are the Elasticsearch types your client already sends.

request

curl -X PUT "$OC_BASE_URL/v1/tenants/$OC_TENANT/es/shop.products" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @mapping.json

{
  "mappings": {
    "properties": {
      "name":  { "type": "text" },
      "brand": { "type": "keyword" },
      "price": { "type": "integer" }
    }
  }
}

response

200 OK

{ "acknowledged": true, "shards_acknowledged": true, "index": "shop.products" }

PUT/v1/tenants/:tenant/es/:index/_doc/:id- Index (create or replace) a document by _id. Searchable the instant the call returns - no refresh to wait on.

request

curl -X PUT "$OC_BASE_URL/v1/tenants/$OC_TENANT/es/shop.products/_doc/sku-8842" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @doc.json

{ "name": "Carbon Marathon", "brand": "Aero", "price": 149 }

response

201 Created

{ "_index": "shop.products", "_id": "sku-8842", "result": "created", "_version": 1 }

POST/v1/tenants/:tenant/es/_bulk- Bulk index / update / delete. NDJSON: an action line, then (for index/update) a source line. The fast path for ingest.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/es/_bulk" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @ops.ndjson

{"index":{"_index":"shop.products","_id":"sku-1207"}}
{"name":"Trail 24","brand":"Aero","price":89}
{"update":{"_index":"shop.products","_id":"sku-8842"}}
{"doc":{"price":139}}

response

200 OK

{
  "errors": false,
  "items": [
    { "index":  { "_id": "sku-1207", "status": 201 } },
    { "update": { "_id": "sku-8842", "status": 200 } }
  ]
}

POST/v1/tenants/:tenant/es/:index/_update/:id- Partial update. The fields in doc are merged in; every other field on the document is preserved.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/es/shop.products/_update/sku-8842" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @patch.json

{ "doc": { "price": 139 } }

response

200 OK

{ "_index": "shop.products", "_id": "sku-8842", "result": "updated", "_version": 2 }

POST/v1/tenants/:tenant/es/:index/_search- Search with the Query DSL, with aggregations in the same request. RLS and column masking apply to the query itself.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/es/shop.products/_search" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @query.json

{
  "query": {
    "bool": {
      "must":   [ { "match": { "name": "marathon" } } ],
      "filter": [ { "term":  { "brand": "Aero" } } ]
    }
  },
  "aggs": { "by_brand": { "terms": { "field": "brand" } } }
}

response

200 OK

{
  "took": 6,
  "hits": {
    "total": { "value": 1, "relation": "eq" },
    "hits": [ { "_id": "sku-8842", "_score": 7.41,
              "_source": { "name": "Carbon Marathon", "brand": "Aero", "price": 149 } } ]
  },
  "aggregations": { "by_brand": { "buckets": [ { "key": "Aero", "doc_count": 1 } ] } }
}

POST/v1/tenants/:tenant/es/:index/_count- Count the documents matching a query.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/es/shop.products/_count" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @query.json

{ "query": { "match": { "name": "marathon" } } }

response

200 OK

{ "count": 1 }

GET/v1/tenants/:tenant/es/:index/_doc/:id- Read one document by id. HEAD on the same path answers existence only, and /_source/:id returns the document with no envelope.

request

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/es/shop.products/_doc/sku-8842" \
  -H "Authorization: Bearer $OC_API_KEY"

# bare document, one field
curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/es/shop.products/_source/sku-8842?_source_includes=price" \
  -H "Authorization: Bearer $OC_API_KEY"

response

{
  "_index": "shop.products", "_id": "sku-8842",
  "_version": 2, "found": true,
  "_source": { "name": "Carbon Marathon", "brand": "Aero", "price": 139 }
}

GET/v1/tenants/:tenant/es/:index/_field_caps- What each field is, read from the stored mapping. This is the call dashboards make on connect.

request

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/es/shop.products/_field_caps?fields=*" \
  -H "Authorization: Bearer $OC_API_KEY"

response

{
  "indices": ["shop.products"],
  "fields": {
    "name":  { "text":    { "type": "text", "searchable": true, "aggregatable": false } },
    "brand": { "keyword": { "type": "keyword", "searchable": true, "aggregatable": true } },
    "price": { "long":    { "type": "long", "searchable": true, "aggregatable": true } }
  }
}

POST/v1/tenants/:tenant/es/:index/_delete_by_query- Delete matching documents. Honors max_docs; an unbounded whole-table delete is refused rather than run.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/es/shop.products/_delete_by_query" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @query.json

{ "query": { "term": { "brand": "Aero" } }, "max_docs": 100 }

response

200 OK

{ "total": 3, "deleted": 3, "failures": [] }

Graph traversal

Reads relations declared on a manifest. PKs are passed as path-encoded strings (single-column, string-typed).

GET /v1/tenants/:tenant/graph/:schema/neighbors?rel=&pk= - Forward one-hop. Returns the destination PKs along `rel` from `pk`.

request

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/graph/social.users/neighbors?rel=follows&pk=alice" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK

["bob", "carol", "dave"]

GET /v1/tenants/:tenant/graph/:schema/reverse?rel=&pk= - Inbound one-hop: who points AT `pk` along `rel`. Works only when `from_table != to_table` (see oc-graph STATUS for the self-relation caveat).

request

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/graph/social.users/reverse?rel=follows&pk=bob" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK

["alice", "frank"]

GET /v1/tenants/:tenant/graph/:schema/bfs?rel=&pk=&max_depth= - Breadth-first search up to `max_depth` (default 3). Returns reachable nodes with depth.

request

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/graph/social.users/bfs?rel=follows&pk=alice&max_depth=2" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK

[
  { "pk": "bob",   "depth": 1 },
  { "pk": "carol", "depth": 1 },
  { "pk": "ed",    "depth": 2 }
]

GET /v1/tenants/:tenant/graph/:schema/path?rel=&src=&dst=&max_depth= - Reachability check: is there an `rel`-path from `src` to `dst` within `max_depth` hops?

request

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/graph/social.users/path?rel=follows&src=alice&dst=ed&max_depth=3" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK

{ "reachable": true }

GET /v1/tenants/:tenant/graph/:schema/dijkstra?rel=&src=&dst=&weights_json= - Weighted shortest-path. `weights_json` is a JSON object mapping `"<from>|<to>"` -> f64. A manifest weight-column variant is available - contact support.

request

curl --get "$OC_BASE_URL/v1/tenants/$OC_TENANT/graph/road.cities/dijkstra" \
  -H "Authorization: Bearer $OC_TOKEN" \
  --data-urlencode "rel=connects" \
  --data-urlencode "src=NYC" \
  --data-urlencode "dst=SFO" \
  --data-urlencode 'weights_json={"NYC|CHI":2.0,"CHI|DEN":1.5,"DEN|SFO":1.2}'

response

200 OK

{ "cost": 4.7 }

Online schema migrations

Submit a diff, watch backfill progress, then cut over atomically. Aborts are allowed pre-cutover only. Every state transition is durably journaled.

POST /v1/tenants/:tenant/migrations - Submit a migration. Body: `{schema, diff}` where `diff` is a `Vec<oc_migrate::DiffOp>`.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/migrations" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "trading.orders",
    "diff":   [ { "AddColumn": { "name": "venue", "type": "str", "default": "NYSE" } } ]
  }'

response

200 OK

{
  "id":      "0192ab...",
  "tenant":  "01HW...ZZ",
  "schema":  "trading.orders",
  "state":   "Backfilling",
  "diff":    [ ... ],
  "progress": { "rows_seen": 0, "rows_total": null }
}

GET /v1/tenants/:tenant/migrations - List every migration the tenant has submitted (active + terminal).

request

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/migrations" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK

[ { "id": "...", "schema": "trading.orders", "state": "Backfilling", ... }, ... ]

GET /v1/tenants/:tenant/migrations/:id - Read one migration. Poll for backfill progress.

request

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/migrations/0192ab..." \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK · 404 unknown

{ "id": "...", "state": "ReadyToCutover", "progress": { "rows_seen": 1240000, ... } }

POST /v1/tenants/:tenant/migrations/:id/cutover - Atomic cutover. Only legal in `ReadyToCutover` state.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/migrations/0192ab.../cutover" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK · 409 wrong state

{ "id": "...", "state": "Completed", ... }

POST /v1/tenants/:tenant/migrations/:id/abort - Abort. Only legal pre-cutover. Once the migration is `Completed`, abort returns 409.

request

curl -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/migrations/0192ab.../abort" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK · 409 already cut over

{ "id": "...", "state": "Aborted", ... }

GET /v1/tenants/:tenant/migrations/_audit - Append-only audit log of every state transition (submit / cutover / abort / auto-cutover) with actor + UNIX timestamp.

request

curl "$OC_BASE_URL/v1/tenants/$OC_TENANT/migrations/_audit" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK

[
  { "id": "...", "schema": "trading.orders", "state": "Backfilling", "at_secs": 1714512000, "actor": "...", "event": "submit" },
  { "id": "...", "schema": "trading.orders", "state": "Completed",   "at_secs": 1714512042, "actor": "...", "event": "cutover" }
]

Replication (admin)

Lease-driven active-passive coordination. The lease holder is the sole writer; followers tail frames from the leader. These endpoints are operational, not application-facing - most tenants never call them.

GET /v1/replication/lease - Read the current lease (or null if vacant).

request

curl "$OC_BASE_URL/v1/replication/lease" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK

{ "epoch": 4, "holder": "writer-a", "expires_at_secs": 1714512030, "etag": "..." }

POST /v1/replication/lease - Try-acquire the lease. `ttl_secs` defaults to 30. Returns 409 if held by another writer.

request

curl -X POST "$OC_BASE_URL/v1/replication/lease" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "holder": "writer-a", "ttl_secs": 30 }'

response

200 OK · 409 busy

{ "epoch": 5, "holder": "writer-a", "expires_at_secs": 1714512060, "etag": "..." }

GET /v1/replication/frames?since_segment=&epoch= - Export the log from `since_segment` onwards as hex-encoded entries. Management-plane convenience; production followers stream raw bytes via the dedicated transport.

request

curl "$OC_BASE_URL/v1/replication/frames?since_segment=4&epoch=5" \
  -H "Authorization: Bearer $OC_TOKEN"

response

200 OK

["7b226c736e223a..."]

Health & observability

All three are public (no auth) so load balancers and Prometheus scrapers can probe without a credential.

GET /health - Liveness - process is up and the log is mounted.

request

curl "$OC_BASE_URL/health"

response

200 OK

{ "status": "ok" }

GET /ready - Readiness - the bare call reports storage health and answers 200 even when `status` is degraded. Use `?require=write` (or `?require=read`) for the strict probe; `pressure` carries the reason. Follower lag is not part of the check.

request

curl "$OC_BASE_URL/ready"

response

200 OK · 503 not ready

{ "write_ready": true, "status": "ready" }

GET /metrics - Prometheus exposition - request latencies, cache hits, log bytes, replication counts.

request

curl "$OC_BASE_URL/metrics"

response

200 OK (text/plain)

# HELP oc_query_latency_ms /v1/query end-to-end latency.
# TYPE oc_query_latency_ms histogram
oc_query_latency_ms_bucket{le="10"}  9218
oc_replication_frames_total          41702
oc_plan_cache_hits_total             41190
...

SQL - scope today

NATURAL JOIN and ? bind-param syntax are not in scope today. UNION/INTERSECT/EXCEPT, CTEs (WITH / WITH RECURSIVE), ALTER TABLE and $1 positional binding all ship. Correlated subqueries do ship: WHERE EXISTS / NOT EXISTS, col IN (SELECT ...) and correlated scalar comparisons all run. (SELECT/INSERT/UPDATE, CREATE TABLE, and BEGIN/COMMIT execute; DELETE via /sql translates only.) Use explicit JOIN ... ON for multi-table reads.