S3 Objects API¶

Manage objects within S3-compatible buckets. All endpoints require JWT authentication.

Base path: /api/v1/buckets/{bucket}/objects

# Upload (auto presigned, auto multipart for large files)
await client.s3.upload("bucket", "key", Path("file.bin"))
# Download
await client.s3.download("bucket", "key", Path("output.bin"))

# CLI — single file or entire directory
rahcp s3 upload my-bucket data/file.bin ./file.bin
rahcp s3 upload-all my-bucket ./local-dir
rahcp s3 download my-bucket data/file.bin -o ./file.bin
rahcp s3 download-all my-bucket -o ./local-backup

Single-Object Endpoints¶

These endpoints operate on individual objects using the object key as a path parameter.

Upload object¶

POST /api/v1/buckets/{bucket}/objects/{key}

Upload a file as a multipart form. The object key is specified in the URL path.

Request body: Multipart form data with a file field.

Response: UploadObjectResponse — { bucket, key, status }

Download object¶

GET /api/v1/buckets/{bucket}/objects/{key}

Returns the object content as a streaming response with appropriate Content-Type and Content-Disposition headers.

Query parameters:

Get object metadata¶

HEAD /api/v1/buckets/{bucket}/objects/{key}

Response: HeadObjectResponse

Delete object¶

DELETE /api/v1/buckets/{bucket}/objects/{key}

Query parameters:

Response: ObjectMutationResponse — { status, bucket, key }

Copy object¶

POST /api/v1/buckets/{bucket}/objects/{key}/copy

Copy an object from a source location to this destination key.

Request body:

Response: ObjectMutationResponse

Get object ACL¶

GET /api/v1/buckets/{bucket}/objects/{key}/acl

Response: AclResponse — { owner, grants }

Set object ACL¶

PUT /api/v1/buckets/{bucket}/objects/{key}/acl

Request body: AclPolicy — { Owner, Grants }

Response: StatusResponse

Bulk Endpoints¶

These endpoints operate on multiple objects at once.

List objects¶

GET /api/v1/buckets/{bucket}/objects

Query parameters:

Response: ListObjectsResponse

Bulk delete¶

POST /api/v1/buckets/{bucket}/objects/delete

Request body:

Response: DeleteObjectsResponse — { status, deleted, errors }

Bulk download (ZIP)¶

POST /api/v1/buckets/{bucket}/objects/download

Downloads multiple objects as a single ZIP archive (streaming response).

Request body:

Bulk presigned URLs¶

POST /api/v1/buckets/{bucket}/objects/presign

Generate presigned URLs for multiple objects.

Request body:

Response: BulkPresignResponse — { urls: [{ key, url }], expires_in }

Object Versions¶

Browse version history for objects in versioning-enabled buckets.

List object versions¶

GET /api/v1/buckets/{bucket}/versions

Returns all object versions and delete markers for the bucket.

Query parameters:

Response: ListObjectVersionsResponse

Multipart Upload¶

Upload large files in parts. The frontend automatically uses presigned multipart upload for files >= 100 MB — the browser uploads parts directly to HCP/S3 via presigned URLs, bypassing the backend for data transfer.

Base path: /api/v1/buckets/{bucket}/multipart

Presigned multipart upload (recommended)¶

POST /api/v1/buckets/{bucket}/multipart/{key}/presign

Creates a multipart upload and returns presigned URLs for each part. The browser uploads parts directly to HCP/S3, bypassing the backend for data transfer. This is the recommended approach for large files.

Request body:

Response: PresignedMultipartResponse

Errors:

• 400 — Too many parts (file_size / part_size > 10,000)
• 422 — Invalid file_size or part_size

Flow:

sequenceDiagram
    participant Browser
    participant Backend
    participant HCP as HCP S3

    Browser->>Backend: POST /presign {file_size, part_size}
    Backend->>HCP: CreateMultipartUpload
    HCP-->>Backend: UploadId
    Note over Backend: Generate presigned URLs<br/>(local HMAC signing, no network)
    Backend-->>Browser: {upload_id, urls[], total_parts}

    loop Each part (6 concurrent)
        Browser->>HCP: PUT presigned_url (raw bytes)
        HCP-->>Browser: 200 + ETag header
    end

    Browser->>Backend: POST /complete {upload_id, parts[]}
    Backend->>HCP: CompleteMultipartUpload
    HCP-->>Backend: 200 + final ETag
    Backend-->>Browser: {bucket, key, etag}

1. Client calls this endpoint → gets upload_id + presigned URLs
2. Client PUTs raw bytes directly to each presigned URL (no FormData, no backend proxy)
3. Client reads ETag from each response header
4. Client calls Complete with the collected { PartNumber, ETag } pairs

Initiate multipart upload (proxied)¶

POST /api/v1/buckets/{bucket}/multipart/{key}

Returns an upload ID to use for subsequent proxied part uploads. For new integrations, prefer the presigned approach instead.

Response: CreateMultipartUploadResponse (201 Created)

Upload part¶

PUT /api/v1/buckets/{bucket}/multipart/{key}

Upload a single part of a multipart upload.

Query parameters:

Request body: Binary file data (multipart form with file field)

Response: UploadPartResponse

Complete multipart upload¶

POST /api/v1/buckets/{bucket}/multipart/{key}/complete

Assemble all uploaded parts into the final object.

Request body:

Response: CompleteMultipartUploadResponse — { bucket, key, etag }

Abort multipart upload¶

POST /api/v1/buckets/{bucket}/multipart/{key}/abort

Abort an in-progress upload and discard all uploaded parts.

Request body:

Response: StatusResponse — { status: "aborted" }

List uploaded parts¶

GET /api/v1/buckets/{bucket}/multipart/{key}/parts

Query parameters:

Response: ListPartsResponse

S3 Credentials & Presigned URLs¶

These endpoints are at the API root level (not scoped to a bucket).

Generate presigned URL¶

POST /api/v1/presign

Request body:

Response: PresignedUrlResponse — { url, bucket, key, expires_in, method }

Get S3 credentials¶

GET /api/v1/credentials

Response: S3CredentialsResponse

CORS Configuration for Presigned Uploads¶

Presigned multipart uploads send PUT requests directly from the browser to the HCP S3 endpoint. For this to work, the target HCP namespace must have CORS configured to:

1. Allow PUT requests from your frontend origin
2. Expose the ETag response header (needed to complete the upload)

Required CORS configuration¶

Set this on the namespace-level CORS settings (or tenant-level as a default):

<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>https://your-frontend-domain.com</AllowedOrigin>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedHeader>*</AllowedHeader>
    <ExposeHeader>ETag</ExposeHeader>
  </CORSRule>
</CORSConfiguration>

What each setting does¶

Code Examples¶

# List objects with prefix
curl -s "http://localhost:8000/api/v1/buckets/my-bucket/objects?prefix=documents/&max_keys=50" \
  -H "Authorization: Bearer $TOKEN" | jq .

# Upload an object
curl -s -X POST \
  http://localhost:8000/api/v1/buckets/my-bucket/objects/documents/report.pdf \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/report.pdf" | jq .

# Download an object
curl -s http://localhost:8000/api/v1/buckets/my-bucket/objects/documents/report.pdf \
  -H "Authorization: Bearer $TOKEN" -o report.pdf

# Get object metadata
curl -s -I http://localhost:8000/api/v1/buckets/my-bucket/objects/documents/report.pdf \
  -H "Authorization: Bearer $TOKEN"

# Bulk delete
curl -s -X POST http://localhost:8000/api/v1/buckets/my-bucket/objects/delete \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["temp/file1.txt", "temp/file2.txt"]}' | jq .

# Copy an object between buckets
curl -s -X POST \
  http://localhost:8000/api/v1/buckets/dest-bucket/objects/archive/report.pdf/copy \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source_bucket": "source-bucket", "source_key": "documents/report.pdf"}' | jq .

# Get S3 credentials
curl -s http://localhost:8000/api/v1/credentials \
  -H "Authorization: Bearer $TOKEN" | jq .

# List object versions
curl -s "http://localhost:8000/api/v1/buckets/my-bucket/versions?prefix=documents/" \
  -H "Authorization: Bearer $TOKEN" | jq .

# Download a specific version
curl -s "http://localhost:8000/api/v1/buckets/my-bucket/objects/report.pdf?version_id=v123" \
  -H "Authorization: Bearer $TOKEN" -o report-v123.pdf

# Delete a specific version permanently
curl -s -X DELETE \
  "http://localhost:8000/api/v1/buckets/my-bucket/objects/report.pdf?version_id=v123" \
  -H "Authorization: Bearer $TOKEN" | jq .

# Presigned multipart upload: get presigned URLs (recommended)
curl -s -X POST \
  http://localhost:8000/api/v1/buckets/my-bucket/multipart/large-file.bin/presign \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_size": 52428800}' | jq .

# Presigned multipart upload: upload part directly to HCP (raw bytes, no auth needed)
curl -s -X PUT "PRESIGNED_URL_FROM_ABOVE" \
  --data-binary @/path/to/part1.bin

# Multipart upload: initiate (proxied — legacy)
curl -s -X POST \
  http://localhost:8000/api/v1/buckets/my-bucket/multipart/large-file.bin \
  -H "Authorization: Bearer $TOKEN" | jq .

# Multipart upload: upload part (proxied — legacy)
curl -s -X PUT \
  "http://localhost:8000/api/v1/buckets/my-bucket/multipart/large-file.bin?upload_id=UPLOAD_ID&part_number=1" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/part1.bin" | jq .

# Multipart upload: complete
curl -s -X POST \
  http://localhost:8000/api/v1/buckets/my-bucket/multipart/large-file.bin/complete \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"upload_id": "UPLOAD_ID", "parts": [{"PartNumber": 1, "ETag": "\"etag1\""}]}' | jq .