S3 API Documentation

🚀 Quickstart

Three steps to start uploading files to Petadata Storage with your favorite SDK.

Create an access key (Access Key + Secret) in the customer panel under Keys.
Point your S3 client to https://s3.petadata.com.br:2222 with region us-east-1.
Use S3 operations as usual. List, upload, download, delete, multipart, presigned URLs, all compatible.

Python (boto3)$ pip install boto3

import boto3
from botocore.config import Config

s3 = boto3.client(
    's3',
    endpoint_url='https://s3.petadata.com.br:2222',
    aws_access_key_id='SUA_ACCESS_KEY',
    aws_secret_access_key='SUA_SECRET_KEY',
    region_name='us-east-1',
    config=Config(s3={'addressing_style': 'path'}),
)

for b in s3.list_buckets()['Buckets']:        # lista buckets
    print(b['Name'])

s3.upload_file('photo.jpg', 'meu-bucket', 'fotos/photo.jpg')          # upload
s3.download_file('meu-bucket', 'fotos/photo.jpg', 'local.jpg')        # download
s3.delete_object(Bucket='meu-bucket', Key='fotos/photo.jpg')         # delete

url = s3.generate_presigned_url(                # presigned URL (GET, 1h)
    'get_object',
    Params={'Bucket': 'meu-bucket', 'Key': 'fotos/photo.jpg'},
    ExpiresIn=3600,
)

Node.js (@aws-sdk/client-s3)$ npm i @aws-sdk/client-s3

import {
    S3Client, ListBucketsCommand,
    PutObjectCommand, GetObjectCommand, DeleteObjectCommand,
} from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { readFile } from 'node:fs/promises';

const s3 = new S3Client({
    endpoint: 'https://s3.petadata.com.br:2222',
    region: 'us-east-1',
    credentials: { accessKeyId: 'SUA_ACCESS_KEY', secretAccessKey: 'SUA_SECRET_KEY' },
    forcePathStyle: true,
});

const { Buckets } = await s3.send(new ListBucketsCommand({}));   // lista buckets
console.log(Buckets.map(b => b.Name));

await s3.send(new PutObjectCommand({                              // upload
    Bucket: 'meu-bucket', Key: 'fotos/photo.jpg', Body: await readFile('photo.jpg'),
}));
const obj = await s3.send(new GetObjectCommand({ Bucket: 'meu-bucket', Key: 'fotos/photo.jpg' })); // download
await s3.send(new DeleteObjectCommand({ Bucket: 'meu-bucket', Key: 'fotos/photo.jpg' }));          // delete

const url = await getSignedUrl(                                   // presigned URL (GET, 1h)
    s3, new GetObjectCommand({ Bucket: 'meu-bucket', Key: 'fotos/photo.jpg' }), { expiresIn: 3600 },
);

Go (aws-sdk-go-v2)go get github.com/aws/aws-sdk-go-v2

cfg, _ := config.LoadDefaultConfig(ctx,
    config.WithRegion("us-east-1"),
    config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(
        "SUA_ACCESS_KEY", "SUA_SECRET_KEY", "")),
)
client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.BaseEndpoint = aws.String("https://s3.petadata.com.br:2222")
    o.UsePathStyle = true
})

out, _ := client.ListBuckets(ctx, &s3.ListBucketsInput{})        // lista buckets
for _, b := range out.Buckets { fmt.Println(*b.Name) }

f, _ := os.Open("photo.jpg")                                     // upload
client.PutObject(ctx, &s3.PutObjectInput{
    Bucket: aws.String("meu-bucket"), Key: aws.String("fotos/photo.jpg"), Body: f,
})
obj, _ := client.GetObject(ctx, &s3.GetObjectInput{             // download
    Bucket: aws.String("meu-bucket"), Key: aws.String("fotos/photo.jpg"),
})
defer obj.Body.Close()
client.DeleteObject(ctx, &s3.DeleteObjectInput{                 // delete
    Bucket: aws.String("meu-bucket"), Key: aws.String("fotos/photo.jpg"),
})

ps := s3.NewPresignClient(client)                               // presigned URL (GET, 1h)
req, _ := ps.PresignGetObject(ctx, &s3.GetObjectInput{
    Bucket: aws.String("meu-bucket"), Key: aws.String("fotos/photo.jpg"),
}, s3.WithPresignExpires(time.Hour))
fmt.Println(req.URL)

Java (AWS SDK 2.x)software.amazon.awssdk:s3

S3Client s3 = S3Client.builder()
    .endpointOverride(URI.create("https://s3.petadata.com.br:2222"))
    .region(Region.US_EAST_1)
    .credentialsProvider(StaticCredentialsProvider.create(
        AwsBasicCredentials.create("SUA_ACCESS_KEY", "SUA_SECRET_KEY")))
    .forcePathStyle(true)
    .build();

// lista buckets
s3.listBuckets().buckets().forEach(b -> System.out.println(b.name()));

// upload / download / delete
s3.putObject(b -> b.bucket("meu-bucket").key("fotos/photo.jpg"), Paths.get("photo.jpg"));
s3.getObject(b -> b.bucket("meu-bucket").key("fotos/photo.jpg"), Paths.get("local.jpg"));
s3.deleteObject(b -> b.bucket("meu-bucket").key("fotos/photo.jpg"));

// presigned URL (GET, 1h)
S3Presigner presigner = S3Presigner.builder()
    .endpointOverride(URI.create("https://s3.petadata.com.br:2222"))
    .region(Region.US_EAST_1)
    .credentialsProvider(StaticCredentialsProvider.create(
        AwsBasicCredentials.create("SUA_ACCESS_KEY", "SUA_SECRET_KEY")))
    .build();
String url = presigner.presignGetObject(p -> p
    .signatureDuration(Duration.ofHours(1))
    .getObjectRequest(r -> r.bucket("meu-bucket").key("fotos/photo.jpg")))
    .url().toString();

C# (.NET, AWSSDK.S3)dotnet add package AWSSDK.S3

var config = new AmazonS3Config {
    ServiceURL = "https://s3.petadata.com.br:2222",
    AuthenticationRegion = "us-east-1",
    ForcePathStyle = true,
};
var s3 = new AmazonS3Client("SUA_ACCESS_KEY", "SUA_SECRET_KEY", config);

// lista buckets
foreach (var b in (await s3.ListBucketsAsync()).Buckets)
    Console.WriteLine(b.BucketName);

// upload / download / delete
await s3.PutObjectAsync(new PutObjectRequest {
    BucketName = "meu-bucket", Key = "fotos/photo.jpg", FilePath = "photo.jpg" });
var obj = await s3.GetObjectAsync("meu-bucket", "fotos/photo.jpg");
await obj.WriteResponseStreamToFileAsync("local.jpg", false, default);
await s3.DeleteObjectAsync("meu-bucket", "fotos/photo.jpg");

// presigned URL (GET, 1h)
string url = s3.GetPreSignedURL(new GetPreSignedUrlRequest {
    BucketName = "meu-bucket", Key = "fotos/photo.jpg",
    Expires = DateTime.UtcNow.AddHours(1),
});

PHP (AWS SDK)composer require aws/aws-sdk-php

$s3 = new Aws\S3\S3Client([
    'version' => 'latest',
    'region' => 'us-east-1',
    'endpoint' => 'https://s3.petadata.com.br:2222',
    'use_path_style_endpoint' => true,
    'credentials' => ['key' => 'SUA_ACCESS_KEY', 'secret' => 'SUA_SECRET_KEY'],
]);

foreach ($s3->listBuckets()['Buckets'] as $b) {        // lista buckets
    echo $b['Name'].PHP_EOL;
}

$s3->putObject(['Bucket' => 'meu-bucket', 'Key' => 'fotos/photo.jpg', 'SourceFile' => 'photo.jpg']); // upload
$s3->getObject(['Bucket' => 'meu-bucket', 'Key' => 'fotos/photo.jpg', 'SaveAs' => 'local.jpg']);     // download
$s3->deleteObject(['Bucket' => 'meu-bucket', 'Key' => 'fotos/photo.jpg']);                           // delete

$cmd = $s3->getCommand('GetObject', ['Bucket' => 'meu-bucket', 'Key' => 'fotos/photo.jpg']);   // presigned (1h)
$url = (string) $s3->createPresignedRequest($cmd, '+1 hour')->getUri();

Ruby (aws-sdk-s3)$ gem install aws-sdk-s3

require 'aws-sdk-s3'

s3 = Aws::S3::Client.new(
  endpoint: 'https://s3.petadata.com.br:2222',
  region: 'us-east-1',
  access_key_id: 'SUA_ACCESS_KEY',
  secret_access_key: 'SUA_SECRET_KEY',
  force_path_style: true,
)

s3.list_buckets.buckets.each { |b| puts b.name }                          # lista buckets

s3.put_object(bucket: 'meu-bucket', key: 'fotos/photo.jpg', body: File.open('photo.jpg'))   # upload
s3.get_object(bucket: 'meu-bucket', key: 'fotos/photo.jpg', response_target: 'local.jpg')   # download
s3.delete_object(bucket: 'meu-bucket', key: 'fotos/photo.jpg')                              # delete

signer = Aws::S3::Presigner.new(client: s3)                               # presigned URL (GET, 1h)
url = signer.presigned_url(:get_object, bucket: 'meu-bucket', key: 'fotos/photo.jpg', expires_in: 3600)

Rust (aws-sdk-s3)$ cargo add aws-sdk-s3

use aws_sdk_s3::{Client, Config};
use aws_sdk_s3::config::{Credentials, Region};
use aws_sdk_s3::presigning::PresigningConfig;
use aws_sdk_s3::primitives::ByteStream;
use std::time::Duration;

let creds = Credentials::new("SUA_ACCESS_KEY", "SUA_SECRET_KEY", None, None, "static");
let cfg = Config::builder()
    .endpoint_url("https://s3.petadata.com.br:2222")
    .region(Region::new("us-east-1"))
    .credentials_provider(creds)
    .force_path_style(true)
    .build();
let s3 = Client::from_conf(cfg);

for b in s3.list_buckets().send().await?.buckets() {                 // lista buckets
    println!("{}", b.name().unwrap_or_default());
}

let body = ByteStream::from_path("photo.jpg").await?;               // upload
s3.put_object().bucket("meu-bucket").key("fotos/photo.jpg").body(body).send().await?;
let obj = s3.get_object().bucket("meu-bucket").key("fotos/photo.jpg").send().await?; // download
s3.delete_object().bucket("meu-bucket").key("fotos/photo.jpg").send().await?;        // delete

let presigned = s3.get_object().bucket("meu-bucket").key("fotos/photo.jpg")          // presigned (1h)
    .presigned(PresigningConfig::expires_in(Duration::from_secs(3600))?).await?;
println!("{}", presigned.uri());

Kotlin (AWS SDK for Kotlin)aws.sdk.kotlin:s3

val s3 = S3Client {
    endpointUrl = Url.parse("https://s3.petadata.com.br:2222")
    region = "us-east-1"
    forcePathStyle = true
    credentialsProvider = StaticCredentialsProvider {
        accessKeyId = "SUA_ACCESS_KEY"
        secretAccessKey = "SUA_SECRET_KEY"
    }
}

s3.listBuckets().buckets?.forEach { println(it.name) }              // lista buckets

s3.putObject {                                                      // upload
    bucket = "meu-bucket"; key = "fotos/photo.jpg"
    body = ByteStream.fromFile(File("photo.jpg"))
}
s3.getObject(GetObjectRequest { bucket = "meu-bucket"; key = "fotos/photo.jpg" }) { resp ->  // download
    resp.body?.writeToFile(File("local.jpg"))
}
s3.deleteObject { bucket = "meu-bucket"; key = "fotos/photo.jpg" }  // delete

val presigned = s3.presignGetObject(                               // presigned URL (GET, 1h)
    GetObjectRequest { bucket = "meu-bucket"; key = "fotos/photo.jpg" }, 1.hours)
println(presigned.url)

AWS CLI$ pip install awscli

# ~/.aws/credentials
[petadata]
aws_access_key_id = SUA_ACCESS_KEY
aws_secret_access_key = SUA_SECRET_KEY

# uso (sempre com --endpoint-url e --profile)
export PD="aws --endpoint-url https://s3.petadata.com.br:2222 --profile petadata"

$PD s3 ls                                                  # lista buckets
$PD s3 cp ./photo.jpg s3://meu-bucket/fotos/              # upload
$PD s3 cp s3://meu-bucket/fotos/photo.jpg ./local.jpg     # download
$PD s3 rm s3://meu-bucket/fotos/photo.jpg                 # delete
$PD s3 presign s3://meu-bucket/fotos/photo.jpg --expires-in 3600   # presigned (1h)

🔐 Authentication

🔑

SigV4

AWS standard. Every key generated in the panel signs correctly when used with SDKs.

🔗

Presigned URLs

Issue temporary URLs for upload or download without exposing your key. Validity from 1 second to 7 days.

🌐

Anonymous (public)

Buckets with a public policy allow GET and HEAD with no credentials. Handy for static distribution.

Where to get your credentials: In the customer panel, open Keys, create a new key, copy the Access Key and Secret Key. Each key can be bound to specific buckets.

📦 Supported operations

Exhaustive table of available operations. Blocks are intentional, for security or business-model reasons.

✅ Fully supported ⚠️ Supported with caveats

🗂️ Bucket operations

Operation	HTTP	Status	Notes
ListBuckets	GET /	✅	Lists only buckets owned by your account, using public names.
HeadBucket	HEAD /{bucket}	✅	—
ListObjects / V2	GET /{bucket}	✅	Accepts prefix, delimiter, max-keys, continuation-token (V2), and start-after.
GetBucketPolicy	GET /{bucket}?policy	✅	The returned policy references buckets by their public names within your account.
PutBucketPolicy	PUT /{bucket}?policy	⚠️	The policy must reference only buckets within your account.
DeleteBucketPolicy	DELETE /{bucket}?policy	✅	—
Versioning	/{bucket}?versioning	✅	Versioning and bucket/object tagging are supported via the S3 API.
Bucket / Object Tagging	/{bucket}[/{key}]?tagging	✅	—
Lifecycle	/{bucket}?lifecycle	✅	Expiration and transition rules are supported; expiration permanently deletes objects that match the rule.

📄 Object operations

Operation	HTTP	Status	Notes
GetObject	GET /{bucket}/{key}	✅	Accepts Range, If-Match, If-None-Match, and other standard headers.
HeadObject	HEAD /{bucket}/{key}	✅	—
PutObject	PUT /{bucket}/{key}	✅	Supports aws-chunked and STREAMING-AWS4-HMAC-SHA256-PAYLOAD bodies for large uploads.
DeleteObject	DELETE /{bucket}/{key}	✅	—
CopyObject	PUT + x-amz-copy-source	✅	Use the public name of the source bucket in x-amz-copy-source. Copies between buckets within your account are supported.
GetObjectTagging / PutObjectTagging	/{bucket}/{key}?tagging	✅	—

🧩 Multipart upload

Operation	HTTP	Status
CreateMultipartUpload	POST /{bucket}/{key}?uploads	✅
UploadPart	PUT /{bucket}/{key}?partNumber=N&uploadId=...	✅
ListParts	GET /{bucket}/{key}?uploadId=...	✅
CompleteMultipartUpload	POST /{bucket}/{key}?uploadId=...	✅
AbortMultipartUpload	DELETE /{bucket}/{key}?uploadId=...	✅
ListMultipartUploads	GET /{bucket}?uploads	✅

🔗 Presigned URLs

Generate temporary upload (PUT) or download (GET) links without exposing your keys. The signature and expiry are validated on every request before access is authorized.

⏱️Accepted validity: 1 second up to 7 days (604800 seconds).
🕒Clock skew tolerance: ±15 minutes. Keep your server NTP-synced.
🔁Works for GET, PUT, DELETE, and any other operation your SDK can presign.

🌐 Public (anonymous) buckets

Apply a BucketPolicy granting GetObject to Principal "*" and the content becomes available via direct URL. Useful for CDN, static sites, or shared assets.

bucket policy JSON

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": "*",
    "Action": ["s3:GetObject"],
    "Resource": ["arn:aws:s3:::meu-bucket/*"]
  }]
}

Direct URL for public objects:


                    https://s3.petadata.com.br:2222/meu-bucket/imagem.jpg

🚨 Common error codes

Code	HTTP	Meaning
SignatureDoesNotMatch	403	Request signature does not match. Check your Secret Key, the region (us-east-1), and your server clock.
InvalidAccessKeyId	403	The Access Key does not exist or has been disabled. Check it in the panel.
AccessDenied	403	The key used has no permission for this operation or this bucket.
NoSuchBucket	404	Bucket not found for your account. Check the name in the panel.
NoSuchKey	404	Object not found within the given bucket.
KeyTooLongError	400	A segment of the object key exceeded 255 bytes.
RequestTimeTooSkewed	403	Clock difference between your client and our server exceeds 15 minutes.
AccountSuspended	403	Your account is suspended (balance or manual block). Add credits or contact support to reactivate.
QuotaExceeded	403	Storage quota exceeded. The account goes read-only: listing, downloading, and deleting stay available so you can free space, but new uploads are blocked until you are back under the limit or reserve more space.
AuthorizationQueryParametersError	400	Invalid presigned URL parameters: X-Amz-Expires outside 1..604800 seconds, or a malformed X-Amz-Date.
MigrationInProgress	503	Your account is being migrated between instances. Write operations (PUT/POST/DELETE) are temporarily unavailable; reads keep working.
ServiceUnavailable	503	The storage service is temporarily unavailable (instance or server down). Retry shortly.
NotImplemented	501	The requested feature (e.g., per-bucket CORS or website configuration) is not supported by the storage backend.

⚠️ Limitations and gotchas

Unsupported S3 operations

Operation	Notes
CreateBucket	Bucket creation happens in the customer panel, not via SDK.
DeleteBucket	Bucket deletion happens in the customer panel, not via SDK.
Get/PutBucketAcl, Get/PutObjectAcl	Bucket and object ACLs are not supported (returns AccessDenied). Use BucketPolicy to control access.
GetBucketLogging	Server-access logging via the S3 API is not supported (returns AccessDenied); use bucket notifications.
CORS	Cross-origin requests are allowed globally; per-bucket CORS configuration is not supported (returns 501).
Website	Static website hosting configuration is not supported by the storage backend (returns 501).

🛣️

Path-style only

URLs in the form https://s3.petadata.com.br:2222/bucket/key. Virtual-host-style (bucket.s3.petadata.com.br) is not supported. Set forcePathStyle = true in the SDK.

📏

Max key segment length

Each slash-separated segment of the object key supports up to 255 bytes. Larger keys return 400 KeyTooLongError.

🌍

Fixed region us-east-1

The service assumes us-east-1 for every SigV4 signature. Use exactly that region in the SDK; declaring another region causes SignatureDoesNotMatch.

🔒

HTTPS required

The endpoint only accepts TLS connections on port 2222. Plain HTTP is rejected.