API Reference
Complete API documentation for Harbour. Harbour implements the Iceberg REST Catalog specification with 94 endpoints across 15 controllers, plus extensions for context intelligence, AI recommendations, security, and maintenance.
Connect Engines
Harbour implements the full Iceberg REST Catalog specification. Any Iceberg-compatible engine connects natively—just point it to your Harbour endpoint. No custom code, no format converters, no glue logic.
Apache Spark
Full read/write support with schema evolution, time travel, and partition transforms. Configure Spark's REST catalog type and point it to your Harbour instance.
Trino
Cross-engine reads, JOINs, and partition transforms. Use the Iceberg connector with REST catalog type for seamless integration.
PyIceberg
Native Python data access with filters and projections. Load the catalog with REST type for direct notebook and pipeline integration.
Databricks
Native REST catalog connectivity with Runtime 14+. Unity Catalog compatible. Works with Databricks notebooks, jobs, and workflows.
Connect AI Agents
Harbour exposes rich semantic REST endpoints that give AI agents full context about your data landscape. Any HTTP client can connect. Your agents get table importance scores, relationships, PII classifications, actionable recommendations, and lineage—all from one central control plane.
Context Graph
Query the living knowledge graph of your entire data landscape. Search by keyword, traverse relationships, compute PageRank importance, and get full table context including columns, PII, and lineage.
AI Recommendations
Get proactive, table-level recommendations covering snapshot management, partition optimization, schema improvements, and join patterns. Catalog-wide insights surface systemic issues across your entire lakehouse.
Discovery
Discover related tables through context graph traversal. Agents can explore your data landscape semantically—finding tables by domain, relationship, or usage pattern without knowing the exact schema.
Semantic Enrichment
Tag tables with business domains, mark columns as PII with classification types, and define business metrics. All enrichments flow through the context graph to every connected agent and application.
REST API Reference
Complete reference for all 94 endpoints. Harbour implements the Iceberg REST Catalog specification plus extensions for context graph, AI, admin, and maintenance.
Configuration
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/config | Get catalog configuration (defaults, overrides, warehouse) |
Namespaces (6 endpoints)
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/namespaces | List all namespaces with pagination |
| POST | /v1/namespaces | Create a new namespace |
| GET | /v1/namespaces/{namespace} | Get namespace details and properties |
| DELETE | /v1/namespaces/{namespace} | Delete a namespace |
| HEAD | /v1/namespaces/{namespace} | Check if namespace exists |
| POST | /v1/namespaces/{namespace}/properties | Update namespace properties |
Tables (9 endpoints)
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/namespaces/{ns}/tables | List tables in namespace with pagination |
| POST | /v1/namespaces/{ns}/tables | Create a new table |
| GET | /v1/namespaces/{ns}/tables/{table} | Load table metadata with credential vending |
| POST | /v1/namespaces/{ns}/tables/{table} | Commit table changes (schema, partition, snapshot) |
| DELETE | /v1/namespaces/{ns}/tables/{table} | Delete a table |
| HEAD | /v1/namespaces/{ns}/tables/{table} | Check if table exists |
| POST | /v1/namespaces/{ns}/register | Register an existing table from metadata location |
| GET | /v1/namespaces/{ns}/tables/{table}/credentials | Vend temporary scoped credentials |
| POST | /v1/tables/rename | Rename a table (can move across namespaces) |
Views (7 endpoints)
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/namespaces/{ns}/views | List views in namespace |
| POST | /v1/namespaces/{ns}/views | Create a new view |
| GET | /v1/namespaces/{ns}/views/{view} | Load view metadata |
| POST | /v1/namespaces/{ns}/views/{view} | Replace or update a view |
| DELETE | /v1/namespaces/{ns}/views/{view} | Drop a view |
| HEAD | /v1/namespaces/{ns}/views/{view} | Check if view exists |
| POST | /v1/views/rename | Rename a view |
Context Graph (8 endpoints)
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/graph/search?query={q} | Search the context graph by keyword |
| GET | /v1/graph/tables/{tableUuid}/context | Get full context for a table (relationships, columns, PII) |
| GET | /v1/graph/impact | Find impact/lineage paths between tables |
| GET | /v1/graph/importance | Compute PageRank importance scores for all tables |
| GET | /v1/graph/stats | Get graph statistics (node and edge counts) |
| POST | /v1/graph/semantic/domain | Set semantic domain metadata on a table |
| POST | /v1/graph/semantic/pii | Mark a column as PII with classification type |
| POST | /v1/graph/semantic/metric | Define a business metric on a column |
AI Engine (5 endpoints)
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/ai/recommendations/{ns}/{table} | Get AI recommendations for a specific table |
| GET | /v1/ai/insights | Get catalog-wide AI insights and analytics |
| GET | /v1/ai/discover/{ns}/{table} | Discover related tables via context graph traversal |
| POST | /v1/ai/graph/persist | Persist in-memory context graph to database |
| POST | /v1/ai/graph/load | Load persisted context graph from database |
Admin & Security (15 endpoints)
| Method | Endpoint | Description |
|---|---|---|
| POST | /v1/oauth/tokens | OAuth2 token endpoint |
| POST | /v1/admin/api-keys | Create a new API key |
| DELETE | /v1/admin/api-keys | Revoke an API key |
| POST | /v1/admin/roles | Assign a role to a user/principal |
| GET | /v1/admin/roles/{userId} | Get role for a user |
| POST | /v1/admin/oauth-clients | Register a new OAuth client |
| DELETE | /v1/admin/oauth-clients/{clientId} | Disable an OAuth client |
| POST | /v1/admin/oauth-clients/{id}/rotate-secret | Rotate OAuth client secret |
| GET | /v1/admin/oauth-clients | List all registered OAuth clients |
| GET | /v1/admin/stats | Get comprehensive catalog statistics |
| GET | /v1/admin/audit | Get recent audit events with pagination |
| GET | /v1/admin/audit/denied | Get denied access audit events |
| POST | /v1/admin/namespace-grants | Grant namespace-level access to user |
| DELETE | /v1/admin/namespace-grants | Revoke namespace-level access |
| PUT | /v1/admin/storage | Create or update storage configuration |
Maintenance Policies (10 endpoints)
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/admin/maintenance/policies | List all maintenance policies |
| GET | /v1/admin/maintenance/policies/{id} | Get specific policy by ID |
| POST | /v1/admin/maintenance/policies | Create new maintenance policy |
| PUT | /v1/admin/maintenance/policies/{id} | Update existing policy |
| DELETE | /v1/admin/maintenance/policies/{id} | Delete maintenance policy |
| GET | /v1/admin/maintenance/applicable | Get effective policies for a specific table |
| GET | /v1/admin/maintenance/evaluate/snapshot-expiry | Evaluate snapshot expiry for table |
| GET | /v1/admin/maintenance/evaluate/data-compaction | Evaluate data compaction for table |
| GET | /v1/admin/maintenance/evaluate/all | Evaluate all tables needing maintenance |
| POST | /v1/admin/maintenance/execute/snapshot-expiry | Execute snapshot expiry for table |
Metrics & Observability (7 endpoints)
| Method | Endpoint | Description |
|---|---|---|
| POST | /v1/namespaces/{ns}/tables/{table}/metrics | Report metrics from engine operations |
| GET | /v1/metrics/summary | Get comprehensive catalog metrics summary |
| GET | /v1/catalogue/stats | Get catalog statistics |
| GET | /v1/catalogue/tables/{ns}/{table}/health | Get table health metrics |
| GET | /v1/catalogue/tables/{ns}/{table}/workload | Get table workload summary |
| POST | /v1/catalogue/telemetry | Report telemetry/workload events |
| GET | /v1/catalogue/cache/stats | Get cache statistics (hit rate, size) |