API Reference

Oak Chain has three HTTP layers that must not be conflated. Validator-native source routes (jackrabbit-oak) carry consensus truth and segment-level provenance. Edge-owned upstream routes (oak-chain-edge-worker) compose those into the canonical product contract. Local UI and diagnostic routes on the validator are allowed but are not product-contract authority. They are for operators reasoning about a specific validator, not for clients.

If you publish a client against the wrong layer, you'll build something brittle: pointed at local diagnostics that change without notice, or pointed at upstream contracts that don't yet exist. Start with Live Inventory below, then use the taxonomy before wiring any browser, CLI, or automation client.

Contract Boundary

jackrabbit-oak owns the validator-native runtime surface.

oak-chain-edge-worker owns the canonical upstream /ops/v1/* contract.

Local UI, browser, and diagnostic routes on the validator are allowed, but they are not product-contract authority.

Live Inventory

Each validator lists its own routes at GET /v1/index. On jackrabbit-oak trunk 91d5f889fc it lists 81 classified routes, each with its category, surface class, contract version, and upstream replacement where one exists. The segment-transfer files (/journal.log, /manifest, /gc.log, /segments/*), /api/cid/gateway/*, and POST /v1/gc/vote are served but not listed. When the validator sets a token, /v1/index needs it too.

curl -s -H "Authorization: ${OAK_VALIDATOR_AUTH_TOKEN}" http://127.0.0.1:8090/v1/index | jq .

The governed source routes are also published as an OpenAPI contract: openapi-validator-source.yaml. Trust the live /v1/index of the validator you are calling over any copied route list, including the ones below.

Authentication

Validator token auth and edge auth are separate controls.

On the validator, /health* and /v1/ops/snapshots/{health,runtime,storage} bypass token auth so monitors and edge adapters can stay alive during boot and failure.

When OAK_VALIDATOR_AUTH_TOKEN is set, all other validator routes require the token itself, sent without a Bearer prefix, as the Authorization header: -H "Authorization: ${OAK_VALIDATOR_AUTH_TOKEN}". A Bearer prefix gets a 401. With no token set, validator auth is off.

On the edge adapter, /ops/v1/* accepts a bearer token when OPS_API_AUTH_TOKEN is configured, and /ops/v1/runtime/* can require the stricter runtime token when OPS_RUNTIME_AUTH_TOKEN is configured.

Rate Limits

Validators rate-limit requests by default and answer 429 (rate_limit_exceeded) when a limit is hit. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Data Table

Limit

Default

Per client

100 requests per second, burst 200. The client is the first X-Forwarded-For address, else X-Real-IP, else the remote address.

Whole validator

1,000 requests per second

Writes per wallet

10 per second, burst 20, for POST, PUT, and DELETE requests that name the wallet in an X-Wallet-Address header or a wallet parameter

/health*, /v1/ops/snapshots/{health,runtime,storage}, and the segment-transfer files (/journal.log, /manifest, /gc.log, /segments/*) are not rate-limited.

Validator Taxonomy

`source`

These are the governed validator-native routes that runtime code emits with stable contractVersion markers and that upstream composition may consume.

/v1/consensus/leader
/v1/consensus/status
/v1/ops/snapshots/health
/v1/ops/snapshots/runtime
/v1/ops/snapshots/storage
/v1/ops/snapshots/cluster
/v1/ops/snapshots/replication
/v1/ops/snapshots/queue
/v1/proposals/queue/stats
/v1/proposals/release-flow
/v1/settlement/proposals/{proposalId}
/v1/settlement/transactions/{transactionHash}
/v1/explorer/summary
/v1/explorer/release-flow
/v1/explorer/proposals/{proposalId}
/v1/explorer/wallets/{walletAddress}
/v1/explorer/content/nav
/v1/explorer/content/clusters/{clusterId}/tree
/v1/explorer/content/clusters/{clusterId}/node
/v1/explorer/content/clusters/{clusterId}/provenance
/v1/config/osgi
/v1/config/osgi/schema
/v1/config/osgi/sources
/v1/config/osgi/coverage
/v1/config/osgi/delta
/v1/events/recent
/v1/events/stats
/v1/blockchain/config
/v1/gc/status
/v1/gc/estimate
/v1/compaction/proposals
/v1/fragmentation/metrics
/v1/fragmentation/metrics/{walletAddress}
/v1/fragmentation/top

This list matches the source entries that /v1/index reports on jackrabbit-oak trunk 91d5f889fc (2026-10-30).

`local-ui`

These routes are validator-local browser surfaces for on-box operators.

/
/dashboard
/api-browser
/explorer
/console/configMgr

`local-diagnostic`

These routes expose useful local detail, but they are not canonical upstream product contracts.

/v1/index
/health
/health/local
/health/deep
/health/cluster
/metrics
/api/metrics
/journal.log
/manifest
/gc.log
/segments/*
/api/explore
/api/segments/recent
/api/segments/tars
/api/blob/{blobId}
/api/cid/{oakBlobId}
/api/cid/reverse/{cid}
/api/cid/stats
/api/cid/gateway/{oakBlobId}
/v1/aeron/cluster-state
/v1/aeron/validator-identities
/v1/aeron/raft-metrics
/v1/aeron/node-status
/v1/aeron/leadership-history
/v1/aeron/replication-lag
/v1/events/stream
/v1/ops/events/stream

`internal`

These routes are mutation, registration, and on-box query surfaces.

/v1/propose-write
/v1/propose-delete
/v1/proposals/pending/count
/v1/proposals/{proposalId}/status
/v1/binary/declare-intent
/v1/binary/check-intent/{token}
/v1/binary/complete-upload
/v1/wallets/stats
/v1/wallets/content
/v1/register-client
/v1/peers
/v1/head
/v1/ops/operations/{operationId}
/v1/propose-gc
/v1/gc/execute
/v1/gc/vote
/v1/gc/trigger
/v1/gc/account/{walletAddress}
/v1/gc/account/{walletAddress}/pay
/v1/gc/account/{walletAddress}/set-limit
/v1/gc/account/{walletAddress}/execute-pending

Canonical Upstream `/ops/v1/*`

The edge worker source defines the following upstream contract. No public deployment is connected to a validator today. Run the worker locally on port 8787; the oak-chain-infra cluster scripts start it when they find an oak-chain-edge-worker checkout next to them. Settlement routes (/v1/settlement/*) are not yet published upstream.

/ops/v1/overview
/ops/v1/header
/ops/v1/network
/ops/v1/cluster
/ops/v1/raft
/ops/v1/replication
/ops/v1/queue
/ops/v1/signals
/ops/v1/durability
/ops/v1/health
/ops/v1/proposals
/ops/v1/proposals/queue/stats
/ops/v1/proposals/release-flow
/ops/v1/explorer/summary
/ops/v1/explorer/release-flow
/ops/v1/explorer/proposal/{proposalId}
/ops/v1/explorer/wallets/{walletAddress}
/ops/v1/explorer/content/nav
/ops/v1/explorer/content/clusters/{clusterId}/tree
/ops/v1/explorer/content/clusters/{clusterId}/node
/ops/v1/explorer/content/clusters/{clusterId}/provenance
/ops/v1/runtime/aeron
/ops/v1/runtime/media-driver
/ops/v1/runtime/storage
/ops/v1/runtime/blobstore
/ops/v1/runtime/metrics
/ops/v1/config/osgi
/ops/v1/config/osgi/schema
/ops/v1/config/osgi/sources
/ops/v1/config/osgi/coverage
/ops/v1/config/osgi/delta
/ops/v1/events/recent
/ops/v1/events/stats
/ops/v1/transactions/summary
/ops/v1/transactions/{transactionId}
/ops/v1/finality
/ops/v1/tarmk
/ops/v1/tar-chain
/ops/v1/blockchain/config
/ops/v1/gc/status
/ops/v1/gc/estimate
/ops/v1/compaction/proposals
/ops/v1/fragmentation/metrics/{walletAddress}
/ops/v1/fragmentation/metrics
/ops/v1/fragmentation/top

The edge adapter wraps every successful upstream response in a top-level envelope with version, generatedAt, clusterId, and data. Errors carry error instead of data.

Raw validator-local routes such as /v1/aeron/*, /health/deep, /api/*, /metrics, /journal.log, /manifest, /segments/*, /dashboard, /api-browser, /explorer, /console/configMgr, and /v1/index are not canonical upstream product contracts.

Recommended Query Order

Start at /ops/v1/* for every non-local client, browser, or product-facing integration.
Drop to validator source routes only when you control the validator directly or you are implementing the edge adapter itself.
Use local-diagnostic and internal routes only for on-box investigation, signed mutation flows, or runtime compatibility work.

Validator Source Query Set

# Canonical source truth
# If the validator sets a token, add: -H "Authorization: ${OAK_VALIDATOR_AUTH_TOKEN}"
curl -s http://127.0.0.1:8090/v1/consensus/leader | jq .
curl -s http://127.0.0.1:8090/v1/consensus/status | jq .
curl -s http://127.0.0.1:8090/v1/ops/snapshots/cluster | jq .
curl -s http://127.0.0.1:8090/v1/ops/snapshots/queue | jq .
curl -s http://127.0.0.1:8090/v1/ops/snapshots/replication | jq .
curl -s http://127.0.0.1:8090/v1/ops/snapshots/runtime | jq .
curl -s http://127.0.0.1:8090/v1/ops/snapshots/storage | jq .

Upstream Query Set

# Canonical remote contract
curl -s http://127.0.0.1:8787/ops/v1/cluster | jq .
curl -s http://127.0.0.1:8787/ops/v1/queue | jq .
curl -s http://127.0.0.1:8787/ops/v1/replication | jq .
curl -s http://127.0.0.1:8787/ops/v1/durability | jq .
curl -s http://127.0.0.1:8787/ops/v1/finality | jq .

For signal interpretation guidance, see Write Pipeline.