MinIO AIStor Tables API Reference

MinIO AIStor Tables implements native Apache Iceberg tables support directly within MinIO AIStor object storage, eliminating dependencies on external catalog services or metadata databases. The MinIO AIStor Tables API provides a RESTful interface compatible with the Iceberg REST Catalog specification.

Iceberg clients typically require a base path consisting of the MinIO AIStor endpoint and catalog API path (https://aistor.example.net:9000/_iceberg). Refer to the documentation for your preferred client, library, or application for specific behaviors around endpoint construction.

All API requests use the following base path:

http://example.net:9000/_iceberg/v1

Replace example.net with your MinIO AIStor server hostname or IP address.

All requests require AWS Signature Version 4 (SigV4) authentication with the service name s3tables. Requests must include standard AWS SigV4 headers:

• Authorization - AWS SigV4 signature
• X-Amz-Date - Request timestamp
• X-Amz-Content-SHA256 - Payload hash

To authenticate a request:

1. Create an HTTP request with method, URL, headers, and body.
2. Calculate the payload hash (SHA256 of request body).
3. Generate the SigV4 signature using your access key and secret key.
4. Add the signature to the Authorization header.

Most AWS SDKs and libraries provide built-in SigV4 signing functionality. For example, the following Python code uses boto3and botocore:

from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest
import boto3

session = boto3.Session(
    aws_access_key_id='your-access-key',
    aws_secret_access_key='your-secret-key'
)

request = AWSRequest(
    method='POST',
    url='http://localhost:9000/_iceberg/v1/warehouses',
    data='{"name":"analytics"}',
    headers={'Content-Type': 'application/json'}
)

SigV4Auth(session.get_credentials(), 's3tables', 'region').add_auth(request)

Warehouses serve as the root container for all tables and namespaces.

Create a new warehouse for storing tables and namespaces.

POST /_iceberg/v1/warehouses

Request body:

{
  "name": "analytics",
  "upgrade-existing": false
}

Response: 200 OK

{
  "name": "analytics"
}

Action: s3tables:CreateWarehouse

MinIO AIStor creates the underlying warehouse bucket with versioning enabled and purge-on-delete configured. Iceberg relies on versioning to recover from failed transactions and to expire snapshots safely, so this configuration is applied automatically at warehouse creation. When you upgrade an existing bucket to a warehouse, the same versioning configuration is applied.

Because warehouse buckets require versioning, you cannot suspend versioning on a warehouse bucket. A PUT bucket-versioning request that attempts to set the Suspended state (or that supplies excluded prefixes) on a warehouse bucket is rejected with HTTP 400 Bad Request and the S3 error code InvalidBucketState (“This bucket is a Tables warehouse, versioning cannot be suspended.”).

Return all warehouses accessible to the authenticated user or service.

GET /_iceberg/v1/warehouses

Query parameters:

Response: 200 OK

{
  "warehouses": ["analytics", "dev", "staging"],
  "next-page-token": "token-for-next-page"
}

Action: s3tables:ListWarehouses

Retrieve metadata for a specific warehouse.

GET /_iceberg/v1/warehouses/{warehouse}

Response: 200 OK

{
  "name": "analytics",
  "bucket": "mybucket",
  "uuid": "9c12d441-03fe-4693-9a96-a0705ddf69c1",
  "created-at": "2025-10-22T10:30:00Z",
  "properties": {
    "owner": "data-team",
    "description": "Data science tables",
    "environment": "production"
  }
}

Action: s3tables:GetWarehouse

Resource: arn:aws:s3tables:::bucket/{warehouse}

Remove a warehouse. The warehouse must be empty (no namespaces) before deletion.

DELETE /_iceberg/v1/warehouses/{warehouse}

Query parameters:

Response: 204 No Content

Action: s3tables:DeleteWarehouse

Resource: arn:aws:s3tables:::bucket/{warehouse}

Namespaces organize tables within a warehouse and support custom properties.

Create a new namespace within a warehouse.

POST /_iceberg/v1/{warehouse}/namespaces

Request body:

{
  "namespace": ["data_science"],
  "properties": {
    "owner": "data-team",
    "description": "Data science tables",
    "environment": "production"
  }
}

Response: 200 OK

{
  "namespace": ["data_science"],
  "properties": {
    "owner": "data-team",
    "description": "Data science tables",
    "environment": "production"
  }
}

Action: s3tables:CreateNamespace

Resource: arn:aws:s3tables:::bucket/{warehouse}

Return all namespaces in a warehouse.

GET /_iceberg/v1/{warehouse}/namespaces

Query parameters:

Response: 200 OK

{
  "namespaces": [
    ["data_science"],
    ["engineering"],
    ["marketing"]
  ],
  "next-page-token": "token-for-next-page"
}

Action: s3tables:ListNamespaces

Resource: arn:aws:s3tables:::bucket/{warehouse}

Retrieve namespace properties.

GET /_iceberg/v1/{warehouse}/namespaces/{namespace}

Response: 200 OK

{
  "namespace": ["data_science"],
  "properties": {
    "owner": "data-team",
    "description": "Data science tables"
  }
}

Action: s3tables:GetNamespace

Resource: arn:aws:s3tables:::bucket/{warehouse}

Update or add namespace properties.

POST /_iceberg/v1/{warehouse}/namespaces/{namespace}/properties

Request body:

{
  "updates": {
    "owner": "new-team",
    "description": "Updated description"
  },
  "removals": ["environment"]
}

Response: 200 OK

{
  "updated": ["owner", "description"],
  "removed": ["environment"],
  "missing": []
}

Action: s3tables:UpdateNamespaceProperties

Remove a namespace. The namespace must be empty (no tables) before deletion.

DELETE /_iceberg/v1/{warehouse}/namespaces/{namespace}

Response: 204 No Content

Action: s3tables:DeleteNamespace

Resource: arn:aws:s3tables:::bucket/{warehouse}

Tables are Apache Iceberg tables with schema, partitioning, and transaction support.

Create a new table with specified schema and optional partitioning.

POST /_iceberg/v1/{warehouse}/namespaces/{namespace}/tables

Request body:

{
  "name": "orders",
  "schema": {
    "type": "struct",
    "fields": [
      {
        "id": 1,
        "name": "order_id",
        "type": "long",
        "required": true
      },
      {
        "id": 2,
        "name": "customer_id",
        "type": "long",
        "required": true
      },
      {
        "id": 3,
        "name": "order_date",
        "type": "date",
        "required": true
      },
      {
        "id": 4,
        "name": "amount",
        "type": "decimal(10,2)",
        "required": true
      }
    ]
  },
  "partition-spec": [
    {
      "name": "order_date_year",
      "transform": "year",
      "source-id": 3,
      "field-id": 1000
    }
  ],
  "properties": {
    "owner": "orders-team",
    "description": "Order transactions"
  }
}

Restrictions:

• MinIO AIStor manages table locations, you cannot specify a custom location.
• Properties cannot begin with write.data.path.
• Most write.metadata.* properties are not supported.

Response: 200 OK

{
  "metadata": {
    "format-version": 2,
    "table-uuid": "9c12d441-03fe-4693-9a96-a0705ddf69c1",
    "location": "s3://analytics/data_science/orders",
    "current-schema-id": 0,
    "schemas": [...],
    "partition-specs": [...],
    "properties": {...}
  },
  "metadata-location": "s3://analytics/.aistor-tables/data_science/orders/metadata/v1.metadata.json",
  "config": {}
}

Action: s3tables:CreateTable

Resource: arn:aws:s3tables:::bucket/{warehouse}/table/*

Conditions:

• s3tables:namespace - Restrict by namespace name
• s3tables:tableName - Restrict by table name

Setting stage-create to true creates the table as a draft. A staged table:

• Is invisible to List tables and cannot be loaded with Get table metadata.
• Returns a null metadata-location in the create response, which signals that the table is a draft without a final, queryable metadata location.

Finalize a staged table with a subsequent commit to the table endpoint (see Commit table changes). The commit marks the table as live, populates its metadata-location, and makes it visible to List tables. Staging lets you atomically create a table together with its first data commit.

Return all tables in a namespace.

GET /_iceberg/v1/{warehouse}/namespaces/{namespace}/tables

Query parameters:

Response: 200 OK

{
  "identifiers": [
    {
      "namespace": ["data_science"],
      "name": "orders"
    },
    {
      "namespace": ["data_science"],
      "name": "customers"
    }
  ],
  "next-page-token": "token-for-next-page"
}

Action: s3tables:ListTables

Retrieve complete table metadata including schema, partitioning, and snapshots.

GET /_iceberg/v1/{warehouse}/namespaces/{namespace}/tables/{table}

Response: 200 OK

{
  "metadata": {
    "format-version": 2,
    "table-uuid": "9c12d441-03fe-4693-9a96-a0705ddf69c1",
    "location": "s3://analytics/data_science/orders",
    "last-updated-ms": 1698854400000,
    "current-schema-id": 0,
    "schemas": [...],
    "current-snapshot-id": 3051729675574597004,
    "snapshots": [...],
    "partition-specs": [...],
    "properties": {...}
  },
  "metadata-location": "s3://analytics/.aistor-tables/data_science/orders/metadata/v3.metadata.json"
}

Action: s3tables:GetTable

Resource: arn:aws:s3tables:::bucket/{warehouse}/table/*

You can also use a HEAD request to check if a table exists without returning metadata.

HEAD /_iceberg/v1/{warehouse}/namespaces/{namespace}/tables/{table}

Response:

• 200 OK - Table exists
• 404 Not Found - Table does not exist

Atomically commit changes to a table using optimistic concurrency control.

POST /_iceberg/v1/{warehouse}/namespaces/{namespace}/tables/{table}

Request body:

{
  "identifier": {
    "namespace": ["data_science"],
    "name": "orders"
  },
  "requirements": [
    {
      "type": "assert-table-uuid",
      "uuid": "9c12d441-03fe-4693-9a96-a0705ddf69c1"
    },
    {
      "type": "assert-last-assigned-field-id",
      "last-assigned-field-id": 4
    }
  ],
  "updates": [
    {
      "action": "append",
      "manifest-list": "s3://analytics/data_science/orders/metadata/snap-3051729675574597004.avro"
    }
  ]
}

Commit requirements:

Requirements validate preconditions before applying updates. Common types include:

Commit updates:

Updates modify table state atomically. Common actions include:

Response: 200 OK

{
  "metadata": {...},
  "metadata-location": "s3://analytics/.aistor-tables/data_science/orders/metadata/v4.metadata.json"
}

Action: s3tables:UpdateTable

Move a table to a different namespace or change its name.

POST /_iceberg/v1/{warehouse}/tables/rename

Request body:

{
  "source": {
    "namespace": ["data_science"],
    "name": "orders"
  },
  "destination": {
    "namespace": ["analytics"],
    "name": "order_history"
  }
}

Response: 204 No Content

Action: s3tables:RenameTable

Remove a table from the catalog.

DELETE /_iceberg/v1/{warehouse}/namespaces/{namespace}/tables/{table}

Query parameters:

Response: 204 No Content

Purge Behavior:

• purgeRequested=true (default) - Remove both catalog metadata and table data files.
• purgeRequested=false - Remove only catalog entry, preserving data files.

DELETE /_iceberg/v1/{warehouse}/namespaces/{namespace}/tables/{table}?purgeRequested=false

Action: s3tables:DeleteTable

Resource: arn:aws:s3tables:::bucket/{warehouse}/table/*

Return a sample of rows from the current snapshot of a table without a query engine. Rows are read directly from the table’s Parquet data files using an Iceberg scan, so no external engine is required.

GET /_iceberg/v1/{warehouse}/namespaces/{namespace}/tables/{table}/preview

Query parameters:

Response: 200 OK

{
  "schema": [
    { "name": "order_id", "type": "int64" },
    { "name": "amount", "type": "decimal128(10, 2)" }
  ],
  "rows": [
    [1001, "42.50"],
    [1002, "17.00"]
  ],
  "row_count": 2
}

A request for a table that does not exist returns 404 Not Found with error type NoSuchTableException.

Action: s3tables:GetTableData

Resource: arn:aws:s3tables:::bucket/{warehouse}/table/*

Return the last execution status of each automated maintenance job for a table.

GET /_iceberg/v1/{warehouse}/namespaces/{namespace}/tables/{table}/maintenance-job-status

Response: 200 OK

{
  "tableARN": "arn:aws:s3tables:::bucket/analytics/table/9c12d441-03fe-4693-9a96-a0705ddf69c1",
  "status": {
    "icebergSnapshotManagement": {
      "status": "Successful",
      "lastRunTimestamp": "2026-07-24T10:30:00Z"
    },
    "icebergCompaction": {
      "status": "Failed",
      "lastRunTimestamp": "2026-07-24T09:15:00Z",
      "failureMessage": "compaction aborted"
    },
    "icebergUnreferencedFileRemoval": {
      "status": "Not_Yet_Run"
    }
  }
}

The status object contains one entry per maintenance type that is configured on the table: icebergSnapshotManagement, icebergCompaction, and icebergUnreferencedFileRemoval. Each entry has the following fields:

A maintenance type reports Disabled when it is turned off in the table or warehouse configuration, or when the corresponding maintenance feature is disabled cluster-wide. A type that is enabled but has never executed reports Not_Yet_Run.

You can retrieve the same information from the command line with mc table maintenance status.

Action: s3tables:GetTableMaintenanceJobStatus

Resource: arn:aws:s3tables:::bucket/{warehouse}/table/*

The List warehouses, List namespaces, and List tables operations support a case-insensitive substring search filter and an optional statistics mode intended for console and UI use.

Add search to any list request to return only the entries whose name contains the given substring, matched case-insensitively. The filter works with both the default token-based pagination and the statistics mode described below.

GET /_iceberg/v1/analytics/namespaces/data_science/tables?search=order

Add stats=true to a list request to include aggregate statistics for each returned entry and switch from token-based pagination to index-based pagination.

GET /_iceberg/v1/warehouses?stats=true&page=0&page_size=100&sort=size&sort_order=desc

Query parameters:

The allowed sort values depend on the entity being listed:

When sort is omitted, entries are ordered by name.

Response headers:

In statistics mode, the response body adds a stats object keyed by entry name alongside the normal listing fields:

{
  "warehouses": ["analytics", "dev"],
  "stats": {
    "analytics": {
      "namespaces": 3,
      "tables": 12,
      "records": 4500000,
      "size": 892000000
    }
  }
}

Commit changes to multiple tables atomically.

POST /_iceberg/v1/{warehouse}/transactions/commit

Request body:

{
  "table-changes": [
    {
      "identifier": {
        "namespace": ["data_science"],
        "name": "orders"
      },
      "requirements": [...],
      "updates": [...]
    },
    {
      "identifier": {
        "namespace": ["data_science"],
        "name": "customers"
      },
      "requirements": [...],
      "updates": [...]
    }
  ]
}

Response: 200 OK

The transaction succeeds only if all table commits succeed. If any table commit fails, the entire transaction is rolled back.

Retrieve catalog-level configuration and capabilities.

GET /_iceberg/v1/{warehouse}/config?warehouse={warehouse}

Response: 200 OK

{
  "defaults": {
    "s3.endpoint": "http://localhost:9000",
    "s3.delete-enabled": "false"
  },
  "overrides": {}
}

The catalog returns s3.delete-enabled=false to signal clients not to attempt client-side deletion of table data files. Deletion is handled server-side by the catalog when a table is dropped with purge. See Delete table for details.

Return system-wide aggregate statistics across all warehouses. This is a MinIO AIStor extension with no AWS S3 Tables equivalent.

GET /_iceberg/v1/stats

Response: 200 OK

{
  "warehouses": 3,
  "namespaces": 12,
  "tables": 148,
  "records": 4500000,
  "size": 892000000,
  "updated_at": "2026-07-24T10:30:00Z"
}

Each of the numeric count and size fields is omitted from the response when its value is zero. The updated_at field is always present; before any statistics have been computed it serializes as 0001-01-01T00:00:00Z.

Action: s3tables:ListWarehouses

All errors return JSON responses with the following structure:

{
  "error": {
    "code": 409,
    "type": "IcebergTableAlreadyExists",
    "message": "The specified table already exists."
  }
}

Common error types:

Entity names must follow these rules:

Additional constraints:

• Multi-level namespaces: Maximum 10 nested namespaces.
• Custom table locations: Not allowed (MinIO AIStor manages locations).
• Property size: Each property key and value limited to 2KB.

MinIO AIStor Tables does not impose hard rate limits but implements best-effort concurrency control:

• Concurrent commits to the same table use optimistic locking.
• Failed commits due to conflicts should be retried with exponential backoff.
• Maximum transaction timeout is configurable per deployment.

MinIO AIStor Tables is compatible with the AWS S3 Tables API, so tools and clients built for AWS S3 Tables work with minimal or no changes:

• /buckets is an alias for /warehouses. AWS S3 Tables uses TableBucket for the concept that MinIO AIStor calls a warehouse.
• Policy actions accept both s3tables:CreateWarehouse and s3tables:CreateTableBucket as equivalents. See Controlling access to MinIO AIStor Tables.
• The ARN format matches the AWS S3 Tables specification.