REST API Reference

Gnok Catalog implements the Apache Iceberg REST Catalog specification. All endpoints are served under the /v1 base path; {catalog} is the REST prefix a client obtains from /v1/config?warehouse=<name> (see the connection model). Every endpoint except /v1/config and /v1/oauth/tokens requires an Authorization: Bearer <token> header (see Authentication).

Configuration & auth

Method	Path	Purpose
GET	/v1/config	Catalog configuration. Pass ?warehouse=<name> to select a catalog; the response defaults.prefix is the value to use in subsequent paths. Also returns advertised endpoints and capabilities.
POST	/v1/oauth/tokens	OAuth2 token endpoint (client_credentials, refresh_token, token-exchange).

Namespaces

Method	Path	Purpose
GET	/v1/{catalog}/namespaces	List namespaces.
POST	/v1/{catalog}/namespaces	Create a namespace.
GET	/v1/{catalog}/namespaces/{namespace}	Load namespace metadata.
HEAD	/v1/{catalog}/namespaces/{namespace}	Check a namespace exists.
DELETE	/v1/{catalog}/namespaces/{namespace}	Drop a namespace.
POST	/v1/{catalog}/namespaces/{namespace}/properties	Update namespace properties.

Multi-level namespaces are URL-encoded with the unit-separator (\x1f, %1F) between levels, per the Iceberg REST spec.

Tables

Method	Path	Purpose
GET	/v1/{catalog}/namespaces/{namespace}/tables	List tables.
POST	/v1/{catalog}/namespaces/{namespace}/tables	Create a table.
GET	/v1/{catalog}/namespaces/{namespace}/tables/{table}	Load a table. Send X-Iceberg-Access-Delegation: vended-credentials to receive scoped storage credentials.
HEAD	/v1/{catalog}/namespaces/{namespace}/tables/{table}	Check a table exists.
POST	/v1/{catalog}/namespaces/{namespace}/tables/{table}	Commit table changes (metadata update).
DELETE	/v1/{catalog}/namespaces/{namespace}/tables/{table}	Drop a table.
POST	/v1/{catalog}/tables/rename	Rename a table (across namespaces).
POST	/v1/{catalog}/namespaces/{namespace}/register	Register an existing metadata file as a table.
POST	/v1/{catalog}/namespaces/{namespace}/tables/{table}/metrics	Report client-side scan metrics.

Credentials & signing

Method	Path	Purpose
GET / POST	/v1/{catalog}/namespaces/{namespace}/tables/{table}/credentials	Vend scoped storage credentials for one table.
POST	/v1/{catalog}/tables/credentials/batch	Vend credentials for many tables in one request.
POST	/v1/{catalog}/namespaces/{namespace}/tables/{table}/sign	Remote-sign object-storage requests; returns presigned URLs.

See credential vending for the response shape and property names.

Views

Method	Path	Purpose
GET	/v1/{catalog}/namespaces/{namespace}/views	List views.
POST	/v1/{catalog}/namespaces/{namespace}/views	Create a view.
GET	/v1/{catalog}/namespaces/{namespace}/views/{view}	Load a view.
HEAD	/v1/{catalog}/namespaces/{namespace}/views/{view}	Check a view exists.
POST	/v1/{catalog}/namespaces/{namespace}/views/{view}	Replace a view.
DELETE	/v1/{catalog}/namespaces/{namespace}/views/{view}	Drop a view.
POST	/v1/{catalog}/views/rename	Rename a view.

Transactions

Method	Path	Purpose
POST	/v1/transactions/commit	Atomic multi-table commit.

Catalogs

Method	Path	Purpose
GET	/v1/catalogs	List catalogs.
POST	/v1/catalogs	Create a catalog.
GET	/v1/catalogs/{catalog}	Load a catalog.
DELETE	/v1/catalogs/{catalog}	Drop a catalog.

Operational endpoints

Method	Path	Purpose
GET	/health	Liveness — returns 200 OK.
GET	/health/ready	Readiness — 200 when the metadata store is reachable, else 503.
GET	/metrics	Prometheus metrics.

Standard Iceberg clients don't call these directly

Spark, Trino, and PyIceberg drive the endpoints above through their Iceberg REST catalog implementations — you rarely call them by hand. The reference is here for debugging, scripting, and building custom integrations. The exact set of advertised endpoints and capabilities for a given deployment is always returned by GET /v1/config.