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

<figure><img src="https://77315434-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjB7FxO8ty4EXO4HsQP4E%2Fuploads%2FgLe33oEXQNpPtUVKYJMf%2FScreenshot%202025-12-03%20at%2008.54.12.png?alt=media&#x26;token=c42bc4a2-34e3-4ea5-8047-17c23f4ca078" alt=""><figcaption></figcaption></figure>

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:

<figure><img src="https://77315434-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjB7FxO8ty4EXO4HsQP4E%2Fuploads%2FhlB03u32rU1w9YpPDXz5%2FScreenshot%202025-12-03%20at%2008.53.44.png?alt=media&#x26;token=7c11dd57-1a28-4cb8-99d4-1a065786991c" alt=""><figcaption></figcaption></figure>

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

{% code overflow="wrap" %}

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

{% endcode %}