# 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](/warpstream/agent-setup/deploy#region), and `$VIRTUAL_CLUSTER_ID` is found in the overview tab, in the top right section.

![](../../../assets/console/tableflow-overview.png)

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:

![](../../../assets/console/tableflow-agent-keys.png)

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](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

```bash wrap
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
```