Using the Polaris REST APIs with curl

Step-by-step curl examples for the Management and Iceberg REST APIs: tokens, catalogs, principals, roles, grants, namespaces and tables.

This guide shows how to use the Polaris REST APIs with plain curl, without the Polaris CLI or a query engine. It covers the steps most setups need:

  1. Get an access token.
  2. Create a catalog (Management API).
  3. Create a principal and give it access to the catalog (Management API).
  4. Create namespaces and tables as that principal (Iceberg REST API).
  5. Clean up.

The catalog uses FILE storage inside the Polaris container, so no cloud account or object store is needed. This setup is not intended for production use.

Prerequisites๐Ÿ”—

  • Docker and Docker Compose v2.
  • jq, to read values from JSON responses.

Run all commands from the root of the Polaris source repository. The larger request bodies are in site/content/guides/assets/rest-api/ and are passed to curl with -d @<file>.

Start Polaris๐Ÿ”—

Start Polaris with an in-memory metastore. The root credentials are root / s3cr3t:

docker compose -f site/content/guides/rest-api/docker-compose.yml up

Check that Polaris is up. The health endpoint is on the management port, 8182:

curl -s http://localhost:8182/q/health | jq .

Get an access token๐Ÿ”—

Polaris APIs expect an OAuth2 bearer token. Request one for the root principal with the client_credentials grant:

export ROOT_TOKEN=$(curl -s http://localhost:8181/api/catalog/v1/oauth/tokens \
  --user root:s3cr3t \
  -d grant_type=client_credentials \
  -d scope=PRINCIPAL_ROLE:ALL | jq -r .access_token)

--user sends the client ID and secret as HTTP Basic authentication. scope=PRINCIPAL_ROLE:ALL activates all principal roles granted to the principal.

Polaris can serve several realms. Requests without a Polaris-Realm header go to the default realm, which is POLARIS in this guide. To target another realm, add -H "Polaris-Realm: <realm>" to every request, including the token request.

Management API: create a catalog๐Ÿ”—

Create a catalog named quickstart_catalog using create-catalog.json:

curl -s -X POST http://localhost:8181/api/management/v1/catalogs \
  -H "Authorization: Bearer $ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d @site/content/guides/assets/rest-api/create-catalog.json | jq .

List the catalogs:

curl -s http://localhost:8181/api/management/v1/catalogs \
  -H "Authorization: Bearer $ROOT_TOKEN" | jq .

Management API: create a principal and grant access๐Ÿ”—

Clients and engines should not use the root credentials. Create a principal for them instead. The response contains the new principal’s credentials, which are only returned once:

PRINCIPAL_RESPONSE=$(curl -s -X POST http://localhost:8181/api/management/v1/principals \
  -H "Authorization: Bearer $ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"principal": {"name": "quickstart_user"}}')
export USER_CLIENT_ID=$(echo "$PRINCIPAL_RESPONSE" | jq -r .credentials.clientId)
export USER_CLIENT_SECRET=$(echo "$PRINCIPAL_RESPONSE" | jq -r .credentials.clientSecret)

Privileges are granted to catalog roles, catalog roles are assigned to principal roles, and principal roles are assigned to principals. See Entities and Access Control for details.

Create a principal role and a catalog role:

curl -s -X POST http://localhost:8181/api/management/v1/principal-roles \
  -H "Authorization: Bearer $ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"principalRole": {"name": "quickstart_user_role"}}' | jq .

curl -s -X POST http://localhost:8181/api/management/v1/catalogs/quickstart_catalog/catalog-roles \
  -H "Authorization: Bearer $ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"catalogRole": {"name": "quickstart_catalog_role"}}' | jq .

Assign the principal role to the principal, and the catalog role to the principal role:

curl -s -X PUT http://localhost:8181/api/management/v1/principals/quickstart_user/principal-roles \
  -H "Authorization: Bearer $ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"principalRole": {"name": "quickstart_user_role"}}'

curl -s -X PUT http://localhost:8181/api/management/v1/principal-roles/quickstart_user_role/catalog-roles/quickstart_catalog \
  -H "Authorization: Bearer $ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"catalogRole": {"name": "quickstart_catalog_role"}}'

Grant CATALOG_MANAGE_CONTENT to the catalog role. It allows creating, listing, reading and writing all namespaces and tables in the catalog:

curl -s -X PUT http://localhost:8181/api/management/v1/catalogs/quickstart_catalog/catalog-roles/quickstart_catalog_role/grants \
  -H "Authorization: Bearer $ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"grant": {"type": "catalog", "privilege": "CATALOG_MANAGE_CONTENT"}}'

List the grants of the catalog role:

curl -s http://localhost:8181/api/management/v1/catalogs/quickstart_catalog/catalog-roles/quickstart_catalog_role/grants \
  -H "Authorization: Bearer $ROOT_TOKEN" | jq .

Iceberg REST API: namespaces and tables๐Ÿ”—

From here on, use the new principal. Request a token with its credentials:

export USER_TOKEN=$(curl -s http://localhost:8181/api/catalog/v1/oauth/tokens \
  --user "$USER_CLIENT_ID:$USER_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope=PRINCIPAL_ROLE:ALL | jq -r .access_token)

Iceberg clients start by reading the catalog configuration. The warehouse parameter is the catalog name, and the returned prefix is used in all following paths. Here the prefix is the catalog name, which is why the paths below start with quickstart_catalog:

curl -s "http://localhost:8181/api/catalog/v1/config?warehouse=quickstart_catalog" \
  -H "Authorization: Bearer $USER_TOKEN" | jq .overrides

Create a namespace and list the namespaces:

curl -s -X POST http://localhost:8181/api/catalog/v1/quickstart_catalog/namespaces \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace": ["quickstart_namespace"]}' | jq .

curl -s http://localhost:8181/api/catalog/v1/quickstart_catalog/namespaces \
  -H "Authorization: Bearer $USER_TOKEN" | jq .

Create a table using create-table.json, which defines an Iceberg schema with two columns:

curl -s -X POST http://localhost:8181/api/catalog/v1/quickstart_catalog/namespaces/quickstart_namespace/tables \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d @site/content/guides/assets/rest-api/create-table.json | jq '."metadata-location"'

List the tables in the namespace, then load the table to see its metadata:

curl -s http://localhost:8181/api/catalog/v1/quickstart_catalog/namespaces/quickstart_namespace/tables \
  -H "Authorization: Bearer $USER_TOKEN" | jq .

curl -s http://localhost:8181/api/catalog/v1/quickstart_catalog/namespaces/quickstart_namespace/tables/quickstart_table \
  -H "Authorization: Bearer $USER_TOKEN" | jq .metadata.schemas

Clean up๐Ÿ”—

Drop the table and the namespace:

curl -s -X DELETE http://localhost:8181/api/catalog/v1/quickstart_catalog/namespaces/quickstart_namespace/tables/quickstart_table \
  -H "Authorization: Bearer $USER_TOKEN"

curl -s -X DELETE http://localhost:8181/api/catalog/v1/quickstart_catalog/namespaces/quickstart_namespace \
  -H "Authorization: Bearer $USER_TOKEN"

Dropping a table this way removes it from the catalog but leaves its files in storage. Adding ?purgeRequested=true also deletes the files, but Polaris rejects it unless purging is enabled, either server-wide with the DROP_WITH_PURGE_ENABLED feature flag or per catalog with the polaris.config.drop-with-purge.enabled catalog property.

A catalog can only be dropped when it is empty, which includes catalog roles other than catalog_admin. Delete the catalog role first, then the catalog, the principal role and the principal:

curl -s -X DELETE http://localhost:8181/api/management/v1/catalogs/quickstart_catalog/catalog-roles/quickstart_catalog_role \
  -H "Authorization: Bearer $ROOT_TOKEN"

curl -s -X DELETE http://localhost:8181/api/management/v1/catalogs/quickstart_catalog \
  -H "Authorization: Bearer $ROOT_TOKEN"

curl -s -X DELETE http://localhost:8181/api/management/v1/principal-roles/quickstart_user_role \
  -H "Authorization: Bearer $ROOT_TOKEN"

curl -s -X DELETE http://localhost:8181/api/management/v1/principals/quickstart_user \
  -H "Authorization: Bearer $ROOT_TOKEN"

Stop Polaris:

docker compose -f site/content/guides/rest-api/docker-compose.yml down

Next Steps๐Ÿ”—