Iceberg REST Catalog

The Iceberg REST Catalog API implements the Apache Iceberg REST Catalog specification, enabling query engines like Snowflake, DuckDB, Spark, and Trino to discover and read Planasonix-managed Iceberg tables. Base URL: https://api.planasonix.com
Auth: Authorization: Bearer plus your flx_ API key or a JWT obtained via the OAuth2 token exchange endpoint.

OAuth2 Token Exchange

`POST /v1/oauth/tokens`

Exchange an flx_ API key for a short-lived JWT. This endpoint is unauthenticated and follows the Iceberg REST spec’s OAuth2 flow.

string

required

Must be client_credentials.

string

required

Your flx_ API key.

Show Example request and response

curl -X POST https://api.planasonix.com/v1/oauth/tokens \
  -d "grant_type=client_credentials" \
  -d "client_id=flx_your_api_key_here"

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "catalog"
}

Configuration

`GET /v1/config`

Returns the catalog configuration, including the default warehouse identifier.

Show Example response

Response body

{
  "defaults": {},
  "overrides": {
    "warehouse": "planasonix"
  }
}

Namespaces

`GET /v1/namespaces`

List namespaces in the catalog.

string

Optional parent namespace for hierarchical namespace listing.

Show Example response

Response body

{
  "namespaces": [
    ["default"],
    ["analytics"],
    ["staging"]
  ]
}

`POST /v1/namespaces`

Create a new namespace.

string[]

required

Namespace identifier as an array of strings.

object

Key-value properties for the namespace.

Show Example request and response

curl -X POST https://api.planasonix.com/v1/namespaces \
  -H "Authorization: Bearer flx_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": ["analytics"],
    "properties": {
      "owner": "data-team"
    }
  }'

{
  "namespace": ["analytics"],
  "properties": {
    "owner": "data-team"
  }
}

`GET /v1/namespaces/{namespace}`

Get metadata for a namespace.

Show Example response

Response body

{
  "namespace": ["analytics"],
  "properties": {
    "owner": "data-team"
  }
}

`DELETE /v1/namespaces/{namespace}`

Drop a namespace. The namespace must be empty (no tables). Returns 204 No Content on success, 409 Conflict if the namespace contains tables.

`POST /v1/namespaces/{namespace}/properties`

Update namespace properties.

object

Properties to set or overwrite.

string[]

Property keys to remove.

Show Example request

Request body

{
  "updates": {
    "owner": "platform-team"
  },
  "removals": ["deprecated-key"]
}

Tables

`GET /v1/namespaces/{namespace}/tables`

List tables in a namespace.

Show Example response

Response body

{
  "identifiers": [
    {
      "namespace": ["analytics"],
      "name": "page_views"
    },
    {
      "namespace": ["analytics"],
      "name": "user_events"
    }
  ]
}

`POST /v1/namespaces/{namespace}/tables`

Create a new table.

string

required

Table name.

object

required

Iceberg schema definition.

object

Optional partition specification.

string

Optional custom storage location.

Show Example request

Request body

{
  "name": "page_views",
  "schema": {
    "type": "struct",
    "fields": [
      {"id": 1, "name": "event_id", "type": "string", "required": true},
      {"id": 2, "name": "user_id", "type": "long", "required": false},
      {"id": 3, "name": "page_url", "type": "string", "required": false},
      {"id": 4, "name": "timestamp", "type": "timestamptz", "required": true}
    ]
  },
  "partition-spec": {
    "fields": [
      {"source-id": 4, "transform": "day", "name": "day", "field-id": 1000}
    ]
  }
}

`GET /v1/namespaces/{namespace}/tables/{table}`

Load a table. Returns the full table metadata and temporary storage credentials for data file access.

Show Example response

Response body

{
  "metadata-location": "s3://my-bucket/analytics/page_views/metadata/v1.metadata.json",
  "metadata": {
    "format-version": 2,
    "table-uuid": "550e8400-e29b-41d4-a716-446655440000",
    "location": "s3://my-bucket/analytics/page_views",
    "last-sequence-number": 1,
    "schemas": [...],
    "current-schema-id": 0,
    "partition-specs": [...],
    "default-spec-id": 0,
    "snapshots": [...],
    "properties": {}
  },
  "config": {
    "s3.access-key-id": "ASIAIOSFODNN7EXAMPLE",
    "s3.secret-access-key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "s3.session-token": "FwoGZXIvYXdzEB...",
    "s3.region": "us-east-1"
  }
}

The config field contains temporary, read-only credentials scoped to the table’s storage location. These credentials are typically valid for 1 hour (AWS STS) or the duration of the SAS token (Azure).

`POST /v1/namespaces/{namespace}/tables/{table}`

Commit updates to a table. Uses optimistic concurrency — if another commit has occurred since your loadTable, the request returns 409 Conflict.

object[]

required

Pre-conditions that must be satisfied (e.g., assert-table-uuid, assert-current-schema-id).

object[]

required

Table update actions (e.g., add-schema, add-snapshot, set-current-schema, set-properties).

Show Supported update actions

add-schema — Add a new schema
set-current-schema — Set the current schema ID
add-partition-spec — Add a partition spec
set-default-spec — Set the default partition spec
add-sort-order — Add a sort order
set-default-sort-order — Set the default sort order
add-snapshot — Add a new snapshot
set-snapshot-ref — Set a snapshot reference (e.g., main)
set-properties — Set table properties
remove-properties — Remove table properties
set-location — Update table location
remove-snapshots — Remove snapshots by ID
remove-snapshot-ref — Remove a snapshot reference

`DELETE /v1/namespaces/{namespace}/tables/{table}`

Drop a table and remove it from the catalog. Returns 204 No Content on success.

`POST /v1/tables/rename`

Rename a table within or across namespaces.

object

required

Source table identifier (namespace and name).

object

required

Destination table identifier (namespace and name).

`POST /v1/namespaces/{namespace}/tables/{table}/metrics`

Report table scan metrics. Accepts the request and returns 204 No Content.

Error Responses

All error responses follow the Iceberg REST spec format:

{
  "error": {
    "message": "Table not found: analytics.page_views",
    "type": "NoSuchTableException",
    "code": 404
  }
}

Code	Type	Description
`400`	`BadRequestException`	Invalid request body or parameters
`401`	`NotAuthorizedException`	Missing or invalid authentication
`403`	`ForbiddenException`	Feature not available for your tier
`404`	`NoSuchNamespaceException`	Namespace not found
`404`	`NoSuchTableException`	Table not found
`409`	`AlreadyExistsException`	Namespace or table already exists
`409`	`CommitFailedException`	Optimistic concurrency conflict
`429`	`TooManyRequestsException`	Rate limit exceeded

Rate Limits

Catalog API requests are rate-limited per organization by tier:

Tier	Requests/Day
Professional	10,000
Premium	100,000
Enterprise	Unlimited

When the limit is exceeded, the API returns 429 Too Many Requests.

Overview

Data platform

Orchestration

Integration

Governance

Iceberg Catalog

Platform

Iceberg REST Catalog

OAuth2 Token Exchange

`POST /v1/oauth/tokens`

Configuration

`GET /v1/config`

Namespaces

`GET /v1/namespaces`

`POST /v1/namespaces`

`GET /v1/namespaces/{namespace}`

`DELETE /v1/namespaces/{namespace}`

`POST /v1/namespaces/{namespace}/properties`

Tables

`GET /v1/namespaces/{namespace}/tables`

`POST /v1/namespaces/{namespace}/tables`

`GET /v1/namespaces/{namespace}/tables/{table}`

`POST /v1/namespaces/{namespace}/tables/{table}`

`DELETE /v1/namespaces/{namespace}/tables/{table}`

`POST /v1/tables/rename`

`POST /v1/namespaces/{namespace}/tables/{table}/metrics`

Error Responses

Rate Limits

​OAuth2 Token Exchange

​POST /v1/oauth/tokens

​Configuration

​GET /v1/config

​Namespaces

​GET /v1/namespaces

​POST /v1/namespaces

​GET /v1/namespaces/{namespace}

​DELETE /v1/namespaces/{namespace}

​POST /v1/namespaces/{namespace}/properties

​Tables

​GET /v1/namespaces/{namespace}/tables

​POST /v1/namespaces/{namespace}/tables

​GET /v1/namespaces/{namespace}/tables/{table}

​POST /v1/namespaces/{namespace}/tables/{table}

​DELETE /v1/namespaces/{namespace}/tables/{table}

​POST /v1/tables/rename

​POST /v1/namespaces/{namespace}/tables/{table}/metrics

​Error Responses

​Rate Limits

OAuth2 Token Exchange

`POST /v1/oauth/tokens`

Configuration

`GET /v1/config`

Namespaces

`GET /v1/namespaces`

`POST /v1/namespaces`

`GET /v1/namespaces/{namespace}`

`DELETE /v1/namespaces/{namespace}`

`POST /v1/namespaces/{namespace}/properties`

Tables

`GET /v1/namespaces/{namespace}/tables`

`POST /v1/namespaces/{namespace}/tables`

`GET /v1/namespaces/{namespace}/tables/{table}`

`POST /v1/namespaces/{namespace}/tables/{table}`

`DELETE /v1/namespaces/{namespace}/tables/{table}`

`POST /v1/tables/rename`

`POST /v1/namespaces/{namespace}/tables/{table}/metrics`

Error Responses

Rate Limits