Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ivory.finance/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication

Authorization: Bearer <access_token>
All endpoints require a JWT Bearer token.

​
Overview

Each tenant requires an active lakehouse catalog before ETL connectors can be registered. The catalog defines the IOMETE Iceberg endpoint and S3-compatible storage credentials. IOMETE namespaces are isolated per tenant: ivory_tenant_{slug}. 
Provision catalog  →  Register connectors  →  Data flows to Iceberg

​
Provision a catalog

POST /v1/admin/tenants/{tenant_id}/catalog
Creates or updates an Iceberg catalog entry for a tenant. Uses ON CONFLICT upsert — safe to call repeatedly to rotate credentials or update the warehouse path.

​
Request body

FieldRequiredDefaultDescription
catalog_nameNoivory-lakehouseCatalog identifier — referenced by destination_catalog on connectors
catalog_typeNorestCatalog protocol: rest (Iceberg REST), hive, glue
catalog_uriYes—IOMETE REST catalog endpoint
warehouseYes—S3/object-store warehouse path (e.g. s3://ivory-iceberg/)
storage_prefixYes—Tenant-specific prefix within the warehouse
s3_endpointNonullCustom S3 endpoint (MinIO, Cloudflare R2, etc.)
s3_access_key_idNonullS3 access key
s3_secret_key_encNonullS3 secret key (encrypted at rest)
metadataNo{}Arbitrary key-value metadata
curl -X POST https://api.ivory.finance/v1/admin/tenants/tenant-uuid.../catalog \
  -H "Authorization: Bearer $IVORY_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "catalog_uri": "https://iomete.internal/api/v1/catalog",
    "warehouse": "s3://ivory-iceberg/",
    "storage_prefix": "tenants/acme/",
    "s3_endpoint": "https://s3.us-east-1.amazonaws.com"
  }'

​
Response 201 Created

{
  "id": "cat-uuid-...",
  "tenant_id": "tenant-uuid-...",
  "tenant_slug": "acme",
  "catalog_name": "ivory-lakehouse",
  "catalog_type": "rest",
  "catalog_uri": "https://iomete.internal/api/v1/catalog",
  "warehouse": "s3://ivory-iceberg/",
  "storage_prefix": "tenants/acme/",
  "is_active": true,
  "provisioned_at": "2026-03-28T10:00:00Z"
}

​
Get tenant catalog

GET /v1/admin/tenants/{tenant_id}/catalog
Returns the active catalog for a tenant. Returns 404 if no active catalog has been provisioned.

​
Response 200 OK

{
  "id": "cat-uuid-...",
  "tenant_id": "tenant-uuid-...",
  "tenant_slug": "acme",
  "catalog_name": "ivory-lakehouse",
  "is_active": true,
  "provisioned_at": "2026-03-28T10:00:00Z"
}

​
List all catalogs

GET /v1/admin/lakehouse/catalogs
Returns all provisioned tenant catalogs across the platform, ordered by provisioned_at DESC. Admin access.

​
Response 200 OK

[
  {
    "id": "cat-uuid-...",
    "tenant_id": "tenant-uuid-...",
    "tenant_slug": "acme",
    "catalog_name": "ivory-lakehouse",
    "catalog_type": "rest",
    "is_active": true,
    "provisioned_at": "2026-03-28T10:00:00Z"
  }
]

​
IOMETE cluster health

GET /v1/admin/lakehouse/health
Pings the IOMETE gateway health endpoint. No authentication required — safe to use as a readiness probe.

​
Response 200 OK

{ "status": "ok" }
On IOMETE unavailability: 
{ "status": "unavailable", "error": "connection timeout" }

​
Register a sync target

POST /v1/admin/lakehouse/sync-targets
Registers a Postgres table → Iceberg table sync target. Used for direct Postgres-to-Iceberg replication (distinct from the Meltano connector pipeline).

​
Request body

FieldRequiredDefaultDescription
tenant_idYes—Target tenant UUID
source_schemaYes—Postgres source schema
source_tableYes—Postgres source table
iceberg_namespaceYes—Target IOMETE namespace
iceberg_tableYes—Target Iceberg table name
sync_modeNoincrementalincremental | full_refresh
primary_key_colsNo[]Primary key columns for upsert
cursor_colNonullWatermark column for incremental sync
fivetran_connector_idNonullFivetran connector reference (if applicable)
metadataNo{}Arbitrary metadata
curl -X POST https://api.ivory.finance/v1/admin/lakehouse/sync-targets \
  -H "Authorization: Bearer $IVORY_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "tenant-uuid-...",
    "source_schema": "public",
    "source_table": "companies",
    "iceberg_namespace": "ivory_tenant_acme",
    "iceberg_table": "companies_snapshot",
    "sync_mode": "incremental",
    "primary_key_cols": ["id"],
    "cursor_col": "updated_at"
  }'

​
Response 201 Created

Returns the created sync target record.

​
List sync targets

GET /v1/admin/lakehouse/sync-targets?tenant_id={uuid}
Lists sync targets, optionally filtered by tenant.
Query paramRequiredDescription
tenant_idNoFilter to a specific tenant

​
Response 200 OK

[
  {
    "id": "st-uuid-...",
    "catalog_name": "ivory-lakehouse",
    "tenant_slug": "acme",
    "source_schema": "public",
    "source_table": "companies",
    "iceberg_namespace": "ivory_tenant_acme",
    "iceberg_table": "companies_snapshot",
    "sync_mode": "incremental",
    "cursor_col": "updated_at",
    "created_at": "2026-03-28T10:00:00Z"
  }
]