The API reference

Every surface the Meridian server mounts, extracted from the router itself, with per-endpoint status from the repo's honest docs.

• Authentication and authorization are OFF by default (auth.mode = disabled): anyone who can reach the port owns the catalog, all operations audit as anonymous, and authorization is bypassed entirely. Dev posture only; oidc mode is deny-by-default RBAC.
• Pre-alpha, unannounced, no public releases yet; 'Meridian' is a working name and may change before the first public release.
• Status source of truth: docs/status.md (pillar-level) and docs/api-status.md (endpoint-level, wins over any other document on endpoint behavior); where the two disagree, the more conservative statement wins.
• The endpoint matrix tracks the upstream Iceberg OpenAPI definition on main as of July 2026, which includes endpoints newer than any released spec version (scan planning, functions, unregister, register-view).
• The IRC surface is mounted at both /iceberg/v1/... and bare /v1/...; the {prefix} is a warehouse name created through the non-IRC management API (POST /api/v2/warehouses).
• Error mapping diverges deliberately: 401 is NotAuthorizedException, 403 denials are ForbiddenException (divergence f).
• Scan planning can be disabled with planning.enabled = false; those endpoints then answer 406 and are not advertised in GET /v1/config.
• Credential vending and remote signing are automated-tested against MinIO only; the real-AWS path was run manually by the maintainer and is not yet in the automated suite.
• purgeRequested=true does not delete data files yet: the maintenance worker that consumes purge events does not exist, so only catalog entry and metadata files are removed.
• All /api/v2 management surfaces (warehouses, principals, RBAC, events, federation, governance, lineage, quality) require management access (admin role or any MANAGE_WAREHOUSE grant) in oidc mode; the workbench is the exception, open to any authenticated principal.
• GET /v1/config advertises the exact implemented endpoint set in its endpoints field, so spec-aware clients need not guess.

One server, port 8181 by default. Six mounts:

The full IRC surface, served identically at /v1 and /iceberg/v1. {prefix} is a warehouse name; warehouse@branch mounts a catalog branch. Per-endpoint status, straight from api-status.md:

All paths in the Iceberg REST groups are served at both /v1 and /iceberg/v1. {prefix} is a warehouse name; a warehouse@branch prefix addresses a branch. Static /v1/config wins over the {prefix} capture.

Signing follows ADR 005; planning follows docs/design/scan-planning.md. Governance enforcement applies on the scan-plan path.

Everything around the catalog: RBAC, governance, quality, lineage, semantics, agents, branching, federation, sharing, events, audit, workbench. Requires management access in oidc mode.

warehouses, principals, roles, grants

semantics: transpile, metrics, glossary, products

data sharing and marketplace management

events, webhooks, consumers

audit and search

maintenance and table health

federation: mirrors and sprawl

branches and catalog tags

Branch data access needs no extra routes: a branch is read and written through ordinary IRC table endpoints via the warehouse@branch prefix.

governance: classification tags, policies, analytics

lineage and impact

quality: contracts, monitors, incidents, status

sql workbench

No catalog-as-code routes exist anywhere in the router.

ai assets, training runs, models, deletion campaigns

per-area status notes

• How the API is mounted IRC served at both /iceberg/v1 and bare /v1; the prefix is a warehouse name created via POST /api/v2/warehouses; config advertises the implemented endpoint set.
• Documented divergences Seven lettered deliberate deviations: pageSize-only pagination, slashes allowed in names, live-UUID adoption refused, purge defers data deletion, auth off by default, shared table/view name space; (d) resolved.
• Storage config passthrough Table and view loads forward non-secret warehouse storage options; credentials never forwarded (tested denylist); endpoint.external overrides the advertised endpoint for containerized engines.
• Credential vending Per-table RBAC-scoped credentials via loadCredentials or the delegation header; warehouse opt-in (sts or static); GCS and Azure honest stubs; every vend audited; real AWS not in automated suite.
• Remote signing Catalog signs client-built S3 requests with warehouse keys that never leave the server; vending opt-in plus static keys required; path and RBAC checked per request; allows and denies audited.
• Idempotency keys Only updateTable and commitTransaction honor Idempotency-Key; SHA-256 fingerprint, same key with different fingerprint yields 422; only successes recorded, 24-hour retention; any 1-255 char ASCII key accepted.
• ETags Strong ETags on createTable, registerTable, loadTable, and commits; If-None-Match yields 304; refs and all snapshot representations carry distinct tags; tags are opaque, do not parse them.
• Authentication OIDC-native: validates external IdP bearer tokens, never issues tokens; default mode is disabled (everything open, anonymous); JWKS refreshed on key rotation; bootstrap_admin seeds the first administrator.
• Authorization (RBAC) Deny-by-default in oidc mode; grants on warehouse, namespace, table, view with hierarchy inheritance; built-in admin and catalog_reader roles; gaps: grants survive securable drops, decisions uncached.
• Authorization: Management API and CLI Roles, bindings, grants, and effective-permissions endpoints under /api/v2; all require management access (admin binding or any MANAGE_WAREHOUSE grant); every mutation audited; first admin bootstrapped from config.
• Outside the IRC spec (warehouse management) Warehouse CRUD, principal listing, RBAC, and federation APIs under /api/v2; behind the same authentication middleware; all require management access in oidc mode.
• Events (/api/v2/events, /api/v2/webhooks) CloudEvents 1.0 over a transactional outbox: keyset-paginated feed, durable consumers with at-least-once delivery, HMAC-SHA256-signed webhooks with retries and dead-letter visibility; management access required.
• Search (GET /api/v2/search) Postgres full-text search over tables, views, namespaces including column names and docs; results filtered to caller visibility inside the query; view columns not indexed yet; no semantic search.
• Federation: mirrors + sprawl (/api/v2/mirrors, /api/v2/federation/sprawl) Register external Iceberg REST or Glue catalogs as read-only mirrors with incremental sync; writes to foreign tables rejected 409; sprawl summary reports duplicates, staleness, ownership gaps; management-gated.
• Governance: tags, policies, enforcement (/api/v2/governance/...) Classification tags including column-level, versioned Cedar-validated policies (row_filter, column_mask, abac), bindings to tags or securables, dry-run, effective-policy, drift, evidence pack; every mutation audited; management-gated.
• Lineage & impact (/api/v2/lineage, /api/v2/lineage/openlineage) Table-level lineage with a no-fabrication guarantee: commit-declared inputs and OpenLineage events only; graph and impact APIs with downstream blast radius; CI gate CLI; management-gated.
• Quality: contracts & the circuit breaker (/api/v2/quality/...) Versioned table or namespace contracts enforced by a synchronous pre-commit hook: warn, quarantine (audit branch), or block; eval errors fail closed for block/quarantine; SQL assertion execution not yet.
• Quality: zero-scan monitors, incidents & trust score (/api/v2/quality/...) Metadata-only monitors (freshness, volume, schema change, file size, snapshot debt, commit failure) open deduplicated incidents with blast radius; per-table traffic light and 0-100 trust score; management-gated.
• Agent gateway: governed query tools (/mcp) MCP query tools run on the built-in DataFusion executor with RBAC and ABAC; masked columns dropped; cost budget checked before I/O; every call audited on a tamper-evident chain.
• Workbench (/api/v2/workbench) Governed SELECT endpoint for humans on the shared executor; masks are value-preserving; history, saved queries, notebook snippets without embedded secrets; small scans only; any authenticated principal.
• AI Asset Governance (/api/v2/assets, /api/v2/training-runs, /api/v2/models, /api/v2/deletion-campaigns) Filesets, models, vector datasets as grant securables with credential vending; immutable training-run snapshot pinning; EU AI Act summary drafts; GDPR deletion campaigns; model-to-agent leg not modelled.
• Sharing & marketplace (/api/v2/shares, /api/v2/marketplace, /share/{token}) Read-only cross-org shares on token-authenticated per-share IRC endpoints with vended credentials; masking prevented, row filters surfaced not prevented; internal certified-product marketplace with access-request flow.
• Branching & Data CI/CD (/api/v2/branches, /api/v2/tags, warehouse@branch) Catalog-level branches mountable as warehouse@branch IRC catalogs, zero-copy until divergence; merge has table-level conflict detection and a contract gate; immutable tags; circuit breaker skips branch commits.

Read-only IRC per share, addressed by opaque token, exempt from OIDC. Routed write verbs return 403; unrouted write paths fall to 404 or 405.

POST /mcp

MCP agent gateway, single Streamable-HTTP endpoint. POST carries JSON-RPC; GET and DELETE answer 405 (stateless sessions, no server stream).

Tool-level behavior (governed context, governed SQL, budgets, kill switch, audit) is specified in docs/design/agent-gateway.md.

core

• docs/status.md the honest per-feature matrix (implemented / partial / not yet)
• docs/api-status.md endpoint-level IRC surface, statuses and caveats
• docs/dev.md running from source, console, engines, S3/MinIO setup
• conformance/ the engine matrix and e2e suites
• docs/benchmarks/ catalog-plane latency vs Polaris and Lakekeeper

design documents

• agent-gateway.md MCP agent firewall: governed context and query tools, budgets, kill switch, audit chain.
• ai-assets.md Pillar I: AI supply-chain governance, training provenance, EU AI Act, GDPR deletion evidence.
• branching.md Catalog-level branches and tags, branch-as-catalog projection, merge gates, Data CI/CD.
• commit-protocol.md The correctness-critical table-commit path: invariants, failure handling, property-test suite.
• compaction.md Bin-pack small-file compaction executor producing uncommitted Iceberg replace commits.
• contracts-circuit-breaker.md Data contracts and the pre-commit circuit breaker: warn, quarantine, block modes.
• enforcement-matrix.md Honesty doc: per-engine access-governance enforcement guarantees, implemented versus future layers.
• events.md Outbox event delivery: queryable feed, durable consumers, signed webhooks.
• lineage.md Table-level lineage model, OpenLineage in and out, impact API, no fabricated edges.
• quality-monitors.md Zero-scan quality monitors, incidents, and the composite trust score.
• scan-planning.md Server-side scan planning: pushdown, delete attachment, sync and async execution.
• semantics.md Semantics layer: universal views, metrics, glossary, certified data products.
• sharing.md Cross-org read-only shares and internal marketplace, the neutral Delta Sharing alternative.
• small-scan-executor.md The meridian-query built-in DataFusion engine for governed small SELECTs.
• transpilation.md Python SQLGlot sidecar contract: dialect translation, SQL parsing, metric compilation.
• vending.md Credential vending: per-table scoped S3 credentials, STS or static; GCS/Azure stubs.
• workbench.md Governed in-console SQL workbench: history, saved queries, notebook handoff.

architecture decision records

• 001-m0-foundation.md 001. M0 foundation: workspace layout, storage conventions, audit chain
• 002-rust-axum-postgres-stack.md 002. Rust/axum/Postgres stack; Postgres as the only required dependency
• 003-metadata-forward-indexing.md 003. Metadata-forward indexing: spec-compliant files, write-through index in Postgres
• 004-opendal-storage-io.md 004. Object-storage IO through Apache OpenDAL
• 005-remote-signing.md 005. Remote signing lives in `meridian-vending`
• 006-catalog-as-code-bundles.md 006. Catalog-as-code bundles (`meridian plan` / `meridian apply`)
• 007-compaction-executor-arrow-parquet.md 007. Build the compaction executor on arrow + parquet directly, not DataFusion
• 008-federation-inbound-mirrors.md 008. Inbound catalog mirrors: foreign assets reuse the native asset tables
• 009-cedar-abac.md 009. Cedar as the ABAC policy engine, in a standalone `meridian-authz` crate
• 010-datafusion-small-scan-executor.md 010. Build the small-scan query executor on DataFusion, with governed views for enforcement
• README.md Architecture Decision Records