Object Operations

S3 object operations for uploading, downloading, and managing objects

This page documents the S3 API operations for managing objects in Garage.

PutObject

Uploads an object to a bucket.

PUT /{bucket}/{key} HTTP/1.1
Host: s3.garage.example.com
Content-Type: application/octet-stream
Content-Length: {size}

Request Headers

Content-Type · string

MIME type of the object

Content-MD5 · string

Base64-encoded MD5 hash of the object data for integrity verification

x-amz-meta-* · string

User-defined metadata (e.g., x-amz-meta-author: John Doe)

Cache-Control · string

Cache control directives

Content-Disposition · string

Presentation information for the object

Content-Encoding · string

Content encodings applied to the object

Content-Language · string

Language of the content

Expires · string

Expiry date for the object

Checksums

Garage supports additional checksum algorithms:

x-amz-checksum-crc32 · string

Base64-encoded CRC32 checksum

x-amz-checksum-crc32c · string

Base64-encoded CRC32C checksum

x-amz-checksum-sha1 · string

Base64-encoded SHA1 checksum

x-amz-checksum-sha256 · string

Base64-encoded SHA256 checksum

Example

AWS CLI

aws s3 cp file.txt s3://my-bucket/file.txt \
  --endpoint-url https://s3.garage.example.com

cURL

curl -X PUT https://s3.garage.example.com/my-bucket/file.txt \
  -H "Authorization: AWS4-HMAC-SHA256 ..." \
  -H "Content-Type: text/plain" \
  --data-binary @file.txt

Response

HTTP/1.1 200 OK
ETag: "d41d8cd98f00b204e9800998ecf8427e"
x-amz-version-id: 1a2b3c4d

ETag · string

Entity tag (MD5 hash for unencrypted objects)

x-amz-version-id · string

Version ID of the object (hex-encoded UUID)

GetObject

Retrieves an object from a bucket.

GET /{bucket}/{key} HTTP/1.1
Host: s3.garage.example.com

Query Parameters

response-cache-control · string

Override Cache-Control header in response

response-content-disposition · string

Override Content-Disposition header in response

response-content-encoding · string

Override Content-Encoding header in response

response-content-language · string

Override Content-Language header in response

response-content-type · string

Override Content-Type header in response

response-expires · string

Override Expires header in response

Request Headers

Range · string

Downloads a specific byte range (e.g., bytes=0-1023)

If-Match · string

Return object only if ETag matches

If-None-Match · string

Return object only if ETag doesn’t match

If-Modified-Since · string

Return object only if modified since specified date

If-Unmodified-Since · string

Return object only if not modified since specified date

x-amz-checksum-mode · string

Set to ENABLED to receive checksum headers in response

Example

AWS CLI

aws s3 cp s3://my-bucket/file.txt file.txt \
  --endpoint-url https://s3.garage.example.com

cURL

curl https://s3.garage.example.com/my-bucket/file.txt \
  -H "Authorization: AWS4-HMAC-SHA256 ..." \
  -o file.txt

Range Request

curl https://s3.garage.example.com/my-bucket/file.txt \
  -H "Authorization: AWS4-HMAC-SHA256 ..." \
  -H "Range: bytes=0-1023" \
  -o first-kb.bin

Response

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 1024
ETag: "d41d8cd98f00b204e9800998ecf8427e"
Last-Modified: Tue, 04 Mar 2026 10:30:00 GMT
Accept-Ranges: bytes

{object data}

HeadObject

Retrieves metadata about an object without downloading the object itself.

HEAD /{bucket}/{key} HTTP/1.1
Host: s3.garage.example.com

Example

AWS CLI

aws s3api head-object --bucket my-bucket --key file.txt \
  --endpoint-url https://s3.garage.example.com

cURL

curl -I https://s3.garage.example.com/my-bucket/file.txt \
  -H "Authorization: AWS4-HMAC-SHA256 ..."

Response

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 1024
ETag: "d41d8cd98f00b204e9800998ecf8427e"
Last-Modified: Tue, 04 Mar 2026 10:30:00 GMT
Accept-Ranges: bytes

DeleteObject

Deletes an object from a bucket.

DELETE /{bucket}/{key} HTTP/1.1
Host: s3.garage.example.com

Example

AWS CLI

aws s3 rm s3://my-bucket/file.txt \
  --endpoint-url https://s3.garage.example.com

cURL

curl -X DELETE https://s3.garage.example.com/my-bucket/file.txt \
  -H "Authorization: AWS4-HMAC-SHA256 ..."

Response

HTTP/1.1 204 No Content

DeleteObject succeeds even if the object doesn’t exist (idempotent operation).

DeleteObjects

Deletes multiple objects in a single request.

POST /{bucket}?delete HTTP/1.1
Host: s3.garage.example.com
Content-Type: application/xml

Request Body

<?xml version="1.0" encoding="UTF-8"?>
<Delete>
  <Object>
    <Key>file1.txt</Key>
  </Object>
  <Object>
    <Key>file2.txt</Key>
  </Object>
  <Quiet>false</Quiet>
</Delete>

Example

AWS CLI

aws s3api delete-objects --bucket my-bucket \
  --delete "Objects=[{Key=file1.txt},{Key=file2.txt}]" \
  --endpoint-url https://s3.garage.example.com

Response

<?xml version="1.0" encoding="UTF-8"?>
<DeleteResult>
  <Deleted>
    <Key>file1.txt</Key>
  </Deleted>
  <Deleted>
    <Key>file2.txt</Key>
  </Deleted>
</DeleteResult>

CopyObject

Copies an object from one location to another.

PUT /{dest-bucket}/{dest-key} HTTP/1.1
Host: s3.garage.example.com
x-amz-copy-source: /source-bucket/source-key

Request Headers

x-amz-copy-source · string · required

Source object in format: /bucket/key

x-amz-copy-source-if-match · string

Copy only if source ETag matches

x-amz-copy-source-if-none-match · string

Copy only if source ETag doesn’t match

x-amz-copy-source-if-modified-since · string

Copy only if source modified since date

x-amz-copy-source-if-unmodified-since · string

Copy only if source not modified since date

x-amz-metadata-directive · string

COPY (default) or REPLACE to override metadata

Example

AWS CLI

aws s3 cp s3://source-bucket/file.txt s3://dest-bucket/copy.txt \
  --endpoint-url https://s3.garage.example.com

cURL

curl -X PUT https://s3.garage.example.com/dest-bucket/copy.txt \
  -H "Authorization: AWS4-HMAC-SHA256 ..." \
  -H "x-amz-copy-source: /source-bucket/file.txt"

Response

<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
  <ETag>"d41d8cd98f00b204e9800998ecf8427e"</ETag>
  <LastModified>2026-03-04T10:30:00.000Z</LastModified>
</CopyObjectResult>

PostObject

Uploads an object using HTML form-based upload.

POST /{bucket} HTTP/1.1
Host: s3.garage.example.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

Example HTML Form

<form action="https://s3.garage.example.com/my-bucket" method="post" enctype="multipart/form-data">
  <input type="hidden" name="key" value="uploads/${filename}" />
  <input type="hidden" name="acl" value="private" />
  <input type="hidden" name="x-amz-algorithm" value="AWS4-HMAC-SHA256" />
  <input type="hidden" name="x-amz-credential" value="GK.../20260304/garage/s3/aws4_request" />
  <input type="hidden" name="x-amz-date" value="20260304T120000Z" />
  <input type="hidden" name="policy" value="{base64-encoded-policy}" />
  <input type="hidden" name="x-amz-signature" value="{signature}" />
  <input type="file" name="file" />
  <button type="submit">Upload</button>
</form>

PostObject is useful for browser-based uploads. See AWS documentation for policy document format.

Block Storage Details

Garage stores objects using a content-addressed block storage system:

Inline Storage

Objects smaller than the inline threshold (3KB by default) are stored directly in the object table for better performance.

Block-based Storage

Larger objects are split into blocks:

1. Data is chunked based on the configured block_size (default: 1MB)
2. Each block is encrypted (if SSE-C is used) and hashed with BLAKE2
3. Blocks are distributed across cluster nodes
4. Block references are stored in the version table

Checksums

Garage calculates and verifies checksums during upload:

• MD5: Used as ETag for non-encrypted objects
• SHA256: Optional, for AWS Signature v4
• CRC32/CRC32C/CRC64NVME: Optional additional checksums

Unsupported Operations

The following object operations are not implemented:

• Object ACLs (GetObjectAcl, PutObjectAcl)
• Object tagging (GetObjectTagging, PutObjectTagging, DeleteObjectTagging)
• Object legal hold and retention
• Object torrents
• Object versioning (separate version operations)

See Also

• Multipart Uploads - For large objects
• Bucket Operations
• S3 Authentication