# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.warpstream.com/warpstream/tableflow/iceberg-catalog.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.