Bucket Operations API Reference

Complete REST API documentation for S3 bucket management, lifecycle policies, and Object Lock.

Last updated: Sep 23, 2026

Aarkam.Gateway implements standard Amazon S3 compatible REST endpoints for bucket provisioning, access control, and regulatory WORM configuration.

1. Supported Bucket Operations

Operation	HTTP Method	URI Path	Description
`ListBuckets`	`GET`	`/`	Returns a list of all buckets owned by the authenticated tenant.
`CreateBucket`	`PUT`	`/{bucket}`	Creates a new sovereign storage bucket.
`DeleteBucket`	`DELETE`	`/{bucket}`	Deletes an empty storage bucket.
`HeadBucket`	`HEAD`	`/{bucket}`	Determines if a bucket exists and you have permission to access it.
`GetBucketLocation`	`GET`	`/{bucket}?location`	Returns the sovereign geographical region of the bucket.
`PutBucketVersioning`	`PUT`	`/{bucket}?versioning`	Enables or suspends object versioning.
`PutObjectLockConfiguration`	`PUT`	`/{bucket}?object-lock`	Configures default WORM retention parameters for the bucket.

2. API Operation Details

CreateBucket (`PUT /

Creates a new bucket within the authenticated tenant namespace.

Request Headers

Host: s3.aarkam.io
x-amz-bucket-object-lock-enabled: true (Optional, enables WORM retention)

Request Body (XML)

<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <LocationConstraint>sa-central-1</LocationConstraint>
</CreateBucketConfiguration>

Response

HTTP/1.1 200 OK
Location: /financial-vault-2026
Date: Wed, 24 Sep 2026 12:00:00 GMT

PutObjectLockConfiguration (`PUT /

Applies regulatory Write-Once-Read-Many (WORM) retention rules, preventing unauthorized deletion or tampering.

Request Body (XML)

<ObjectLockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <ObjectLockEnabled>Enabled</ObjectLockEnabled>
    <Rule>
        <DefaultRetention>
            <Mode>COMPLIANCE</Mode>
            <Days>2555</Days>
        </DefaultRetention>
    </Rule>
</ObjectLockConfiguration>

Retention Modes Supported:

COMPLIANCE: Protected objects cannot be deleted or modified by any user, including the root administrator, until the retention period expires.
GOVERNANCE: Users with special IAM permissions (s3:BypassGovernanceRetention) can alter retention settings.