Skip to content

API Reference

IOLake provides an S3-compatible REST API.

Contents

Quick Start

Using AWS CLI

# Configure endpoint
export AWS_ENDPOINT_URL=http://localhost:9000
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key

# Create bucket
aws s3 mb s3://my-bucket

# Upload object
aws s3 cp file.txt s3://my-bucket/

# List objects
aws s3 ls s3://my-bucket/

# Download object
aws s3 cp s3://my-bucket/file.txt ./downloaded.txt

# Delete object
aws s3 rm s3://my-bucket/file.txt

Using Python (boto3)

import boto3

s3 = boto3.client(
    's3',
    endpoint_url='http://localhost:9000',
    aws_access_key_id='your-access-key',
    aws_secret_access_key='your-secret-key',
)

# Create bucket
s3.create_bucket(Bucket='my-bucket')

# Upload object
s3.put_object(Bucket='my-bucket', Key='hello.txt', Body=b'Hello World')

# Download object
response = s3.get_object(Bucket='my-bucket', Key='hello.txt')
data = response['Body'].read()

# List objects
response = s3.list_objects_v2(Bucket='my-bucket')
for obj in response.get('Contents', []):
    print(obj['Key'])

Using cURL

# List buckets (no auth)
curl http://localhost:9000/

# Create bucket (no auth mode)
curl -X PUT http://localhost:9000/my-bucket

# Upload object
curl -X PUT -d "Hello World" http://localhost:9000/my-bucket/hello.txt

# Download object
curl http://localhost:9000/my-bucket/hello.txt

API Endpoints

S3 API

Operation Method Path
List Buckets GET /
Create Bucket PUT /{bucket}
Delete Bucket DELETE /{bucket}
Head Bucket HEAD /{bucket}
List Objects GET /{bucket}
Put Object PUT /{bucket}/{key}
Get Object GET /{bucket}/{key}
Delete Object DELETE /{bucket}/{key}
Head Object HEAD /{bucket}/{key}

See S3 Operations for the complete reference.

Iceberg REST Catalog API

Operation Method Path
Get Config GET /iceberg/v1/config
List Namespaces GET /iceberg/v1/namespaces
Create Namespace POST /iceberg/v1/namespaces
Load Namespace GET /iceberg/v1/namespaces/{ns}
Drop Namespace DELETE /iceberg/v1/namespaces/{ns}
List Tables GET /iceberg/v1/namespaces/{ns}/tables
Create Table POST /iceberg/v1/namespaces/{ns}/tables
Load Table GET /iceberg/v1/namespaces/{ns}/tables/{table}
Update Table POST /iceberg/v1/namespaces/{ns}/tables/{table}
Drop Table DELETE /iceberg/v1/namespaces/{ns}/tables/{table}
Rename Table POST /iceberg/v1/tables/rename

See Iceberg REST Catalog for the complete reference.

IAM and STS

Operation Method Path
IAM (CreateUser, PutUserPolicy, CreateRole, …) POST, signed for iam, form body /
STS AssumeRole, GetSessionToken, GetCallerIdentity POST, signed for sts, form body /
STS AssumeRoleWithWebIdentity POST (unsigned, form body) /

The AWS IAM and STS wire formats on the S3 endpoint: point an AWS SDK's or the AWS CLI's iam and sts clients at it. See the IAM and STS APIs.

Admin API (/_admin/*)

SigV4-signed JSON. The system admin uses all of it; a tenant admin the tenant-scoped parts for its own tenant. The management SDKs wrap every call.

Area Paths Reference
Tenants and tenant admins /_admin/tenants, /_admin/tenants/{name}/admins IAM
Users and access keys /_admin/users, /_admin/users/{id}/access-keys, /_admin/access-keys/{id} IAM
Policies /_admin/policies, /_admin/policies/{attach,detach,attached} IAM
Groups /_admin/groups, /_admin/groups/{id}/members IAM
Roles /_admin/roles IAM
Identity providers, config /_admin/config/identity/openid/{name}, /_admin/config IAM
Audit stream /_admin/audit Audit
Public access block /_admin/public-access-block Public Access
Buckets /_admin/buckets, /_admin/buckets/{name}/{policy,owner,quota,dedup,objects} S3 ops
Bucket settings /_admin/buckets/{name}/{versioning,object-lock,encryption,lifecycle,replication} S3 ops § admin API
Pools, nodes, OSDs, rebalance /_admin/pools, /_admin/nodes, /_admin/topology, /_admin/osds/{id}/admin-state, /_admin/rebalance/*, /_admin/drain-status Operations
KMS /_admin/kms/* Features § SSE
Iceberg warehouses /_admin/warehouses Iceberg
Delta Sharing shares and recipients /_admin/shares, /_admin/shares/{share}/tables, /_admin/recipients Features § Delta Sharing
Usage and metrics /_admin/usage, /_admin/cluster-info, /_admin/metrics/query[_range] Metrics

Health Check

curl http://localhost:9000/health
# {"status":"healthy"}

Error Responses

IOLake returns standard S3 error responses:

<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Code>NoSuchBucket</Code>
    <Message>The specified bucket does not exist</Message>
    <BucketName>nonexistent-bucket</BucketName>
    <RequestId>abc123</RequestId>
</Error>

Common Error Codes

Code HTTP Status Description
AccessDenied 403 Access denied
BucketAlreadyExists 409 Bucket exists
BucketNotEmpty 409 Bucket not empty
NoSuchBucket 404 Bucket not found
NoSuchKey 404 Object not found
InvalidAccessKeyId 403 Invalid credentials
SignatureDoesNotMatch 403 Signature mismatch, of the request or of a streaming upload's chunk
XAmzContentSHA256Mismatch 400 The body is not the one whose SHA-256 was signed
MalformedTrailerError 400 A trailer named in x-amz-trailer is missing from the body