Iceberg REST Catalog

This page describes how to connect with Tableflow's read-only REST catalog.

WarpStream implements a read-only Iceberg REST catalog API that provides access to Tableflow tables stored in your clusters.

Important Details

Read-Only Access: This catalog is read-only and designed for integrating with query engines like Snowflake, Databricks, and AWS Glue. All write operations return 403 Forbidden.

Authentication: Bearer token authentication using WarpStream Agent Keys. Other authentication methods are not currently supported.

Namespaces: Only a single namespace default is supported.

Storage Credentials: The catalog does not vend storage credentials. Clients must configure their own storage credentials to access table data.

Construct the Base URL

The base URL for connecting to the catalog is formed by $METADATA_URL/catalogs/iceberg/$VIRTUAL_CLUSTER_ID.

Where $METADATA_URL can be found at Region, and $VIRTUAL_CLUSTER_ID is found in the overview tab, in the top right section.

So for example if your metadata URL was: https://metadata.default.us-east-1.warpstream.com and your virtual cluster ID was vci_dl_04ace9b5_5e41_1915_85ff_a20ea5601e48 then your base URL would be: https://metadata.default.us-east-1.warpstream.com/catalogs/iceberg/vci_dl_04ace9b5_5e41_1915_85ff_a20ea5601e48

Authenticate

Currently, only Bearer token authentication is supported. You must include your Agent Key in the Authorization header:

Authorization: Bearer $AGENT_KEY

The Agent key can be found (or created) at the Agent Keys tab in the UI:

You can also manage your Agent Keys using WarpStream's Terraform provider at https://registry.terraform.io/providers/warpstreamlabs/warpstream/latest/docs/resources/agent_key.

Supported Endpoints

Configuration

• GET /v1/config - Catalog configuration

Namespaces

• GET /v1/namespaces - List namespaces
• GET /v1/namespaces/{namespace} - Get namespace details
• HEAD /v1/namespaces/{namespace} - Check namespace exists

Tables

• GET /v1/namespaces/{namespace}/tables - List tables
• GET /v1/namespaces/{namespace}/tables/{table} - Load table metadata
• HEAD /v1/namespaces/{namespace}/tables/{table} - Check table exists
• GET /v1/namespaces/{namespace}/tables/{table}/credentials - Get credentials (returns empty)

Views

• GET /v1/views - List views (returns empty)
• GET /v1/views/{view} - Returns 404
• HEAD /v1/views/{view} - Returns 404

Unsupported Operations

All namespace/table/view write operations (POST, DELETE, updates) return 403 Forbidden.

Example

curl -H "Authorization: Bearer aks_..."
https://metadata.default.us-east-1.warpstream.com/catalogs/iceberg/vci_dl_04ace9b5_5e41_1915_85ff_a20ea5601e48/v1/namespaces/default/tables/my_table