API Documentation

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.cloudstorage.io",
    region_name="eu-central-1",
    aws_access_key_id="YOUR_ACCESS_KEY",
    aws_secret_access_key="YOUR_SECRET_KEY",
)

# Upload a file
s3.upload_file("local-file.txt", "my-bucket", "remote-file.txt")

# Download a file
s3.download_file("my-bucket", "remote-file.txt", "downloaded.txt")

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

s3.create_bucket(
    Bucket="my-new-bucket",
    CreateBucketConfiguration={"LocationConstraint": "eu-central-1"},
)

response = s3.list_buckets()
for bucket in response["Buckets"]:
    print(bucket["Name"], bucket["CreationDate"])

# Upload from file
s3.upload_file("local-file.txt", "my-bucket", "path/to/file.txt")

# Upload from bytes
s3.put_object(
    Bucket="my-bucket",
    Key="hello.txt",
    Body=b"Hello, CloudStorage!",
    ContentType="text/plain",
)

# Download to file
s3.download_file("my-bucket", "path/to/file.txt", "local-file.txt")

# Read into memory
response = s3.get_object(Bucket="my-bucket", Key="hello.txt")
data = response["Body"].read()
print(data.decode("utf-8"))

s3.delete_object(Bucket="my-bucket", Key="path/to/file.txt")

# List all objects
response = s3.list_objects_v2(Bucket="my-bucket")
for obj in response.get("Contents", []):
    print(f"{obj['Key']:40s} {obj['Size']:>10d} bytes")

# List with prefix (like a directory)
response = s3.list_objects_v2(Bucket="my-bucket", Prefix="data/2025/")
for obj in response.get("Contents", []):
    print(obj["Key"])

# Paginate through many objects
paginator = s3.get_paginator("list_objects_v2")
for page in paginator.paginate(Bucket="my-bucket"):
    for obj in page.get("Contents", []):
        print(obj["Key"])

# Generate a URL valid for 1 hour (3600 seconds)
url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "my-bucket", "Key": "report.pdf"},
    ExpiresIn=3600,
)
print(url)
# https://s3.cloudstorage.io/my-bucket/report.pdf?X-Amz-Algorithm=...

# Generate a URL that allows uploading
url = s3.generate_presigned_url(
    "put_object",
    Params={
        "Bucket": "my-bucket",
        "Key": "uploads/user-file.jpg",
        "ContentType": "image/jpeg",
    },
    ExpiresIn=600,  # 10 minutes
)

# Client can then upload with:
# curl -X PUT -H "Content-Type: image/jpeg" --data-binary @photo.jpg "URL"

# Upload using multipart form-data (file field)
curl -X POST https://cloudstorage.io/api/v1/files \
  -H "X-API-Key: YOUR_ACCESS_KEY:YOUR_SECRET_KEY" \
  -F "[email protected]"

# Response:
# {
#   "id": "abc123",
#   "key": "photo.jpg",
#   "bucket": "default",
#   "size": 204800,
#   "contentType": "image/jpeg",
#   "createdAt": "2026-01-15T10:30:00Z"
# }

# Download a file by ID
curl https://cloudstorage.io/api/v1/files/abc123 \
  -H "X-API-Key: YOUR_ACCESS_KEY:YOUR_SECRET_KEY" \
  -o downloaded-file.jpg

curl https://cloudstorage.io/api/shares \
  -H "Cookie: session=your-session-cookie"

# Response:
# {
#   "shares": [
#     {
#       "id": "share_abc123",
#       "code": "abc123",
#       "fileName": "presentation.pdf",
#       "downloads": 12,
#       "maxDownloads": 50,
#       "expiresAt": "2026-01-22T10:30:00Z",
#       "active": true
#     }
#   ]
# }

# Generate a 200x200 cover thumbnail with smart cropping
curl "https://cloudstorage.io/api/img/my-bucket/photos/hero.jpg?w=200&h=200&fit=cover&gravity=sm"

# Use in an HTML img tag:
# <img src="https://cloudstorage.io/api/img/my-bucket/photos/hero.jpg?w=200&h=200&fit=cover" />

import crypto from "crypto";

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post("/webhooks/cloudstorage", (req, res) => {
  const signature = req.headers["x-cloudstorage-signature"];
  const isValid = verifyWebhook(JSON.stringify(req.body), signature, WEBHOOK_SECRET);
  if (!isValid) return res.status(401).send("Invalid signature");
  // Process event...
  res.status(200).send("OK");
});