vStash - S3 Compatible API and Management
API docs by Redocly

vStash S3 Compatible API (1.0.0)

Download OpenAPI specification:

vStash Support: support@vultr.com URL: https://www.vultr.com

A high-performance S3-compatible object storage API with management console.

Features

  • Full S3 API compatibility for basic operations
  • Multipart upload support
  • Presigned URLs
  • Management console API
  • Enterprise storage backend

Authentication

Uses AWS Signature Version 4 for S3 API endpoints and API keys for management endpoints.

S3 Buckets

S3 bucket operations

List buckets

Returns a list of all buckets owned by the authenticated sender of the request

Authorizations:
AWS4-HMAC-SHA256

Responses

Check if bucket exists

Determines if a bucket exists and you have permission to access it

Authorizations:
AWS4-HMAC-SHA256
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

Responses

Create bucket

Creates a new S3 bucket

Authorizations:
AWS4-HMAC-SHA256
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

Responses

Delete bucket

Deletes the S3 bucket. The bucket must be empty before it can be deleted

Authorizations:
AWS4-HMAC-SHA256
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

Responses

List objects in bucket

Returns some or all of the objects in a bucket

Authorizations:
AWS4-HMAC-SHA256
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

query Parameters
prefix
string <= 255 characters
Example: prefix=photos/

Limits the response to keys that begin with the specified prefix

marker
string <= 255 characters
Example: marker=photos/2023/

Specifies the key to start with when listing objects

max-keys
integer [ 1 .. 1000 ]
Default: 1000
Example: max-keys=100

Maximum number of keys to return

delimiter
string <= 1 characters
Example: delimiter=/

Character used to group keys

uploads
string
Value: ""

List multipart uploads when present

Responses

S3 Objects

S3 object operations

Get object metadata

Retrieves metadata from an object without returning the object itself

Authorizations:
AWS4-HMAC-SHA256
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

key
required
string <= 255 characters
Example: folder/file.txt

Object key (file path) within the bucket

Responses

Get object

Retrieves objects from Amazon S3

Authorizations:
AWS4-HMAC-SHA256
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

key
required
string <= 255 characters
Example: folder/file.txt

Object key (file path) within the bucket

query Parameters
uploadId
string

List parts when present with upload ID

Responses

Put object

Adds an object to a bucket

Authorizations:
AWS4-HMAC-SHA256
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

key
required
string <= 255 characters
Example: folder/file.txt

Object key (file path) within the bucket

query Parameters
partNumber
integer [ 1 .. 10000 ]

Part number for multipart upload

uploadId
string

Upload ID for multipart upload part

Request Body schema: application/octet-stream

Object data

string <binary>

Responses

Delete object

Removes the null version of an object and inserts a delete marker

Authorizations:
AWS4-HMAC-SHA256
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

key
required
string <= 255 characters
Example: folder/file.txt

Object key (file path) within the bucket

query Parameters
uploadId
string

Abort multipart upload when present

Responses

S3 Multipart

S3 multipart upload operations

Initiate or complete multipart upload

Initiates a multipart upload or completes a multipart upload by assembling uploaded parts

Authorizations:
AWS4-HMAC-SHA256
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

key
required
string <= 255 characters
Example: folder/file.txt

Object key (file path) within the bucket

query Parameters
uploads
string
Value: ""

Initiate multipart upload when present

uploadId
string

Complete multipart upload with this upload ID

Request Body schema: application/xml

Complete multipart upload request

Array of objects

Responses

Management - Stats

System statistics and monitoring

Get system statistics

Returns overall system statistics including storage usage, object counts, etc.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "credentials": 5,
  • "buckets": 12,
  • "objects": 1250,
  • "total_storage": 1073741824,
  • "total_storage_human": "1.0 GB",
  • "active_multipart_uploads": 3,
  • "active_presigned_urls": 15
}

Management - Credentials

Access key and credential management

List credentials

Returns a list of all access credentials

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "credentials": [
    ]
}

Create credential

Creates a new access credential

Authorizations:
ApiKey
Request Body schema: application/json
required
user_name
string

Optional user name

access_key
string

Optional custom access key (auto-generated if not provided)

secret_key
string

Optional custom secret key (auto-generated if not provided)

Responses

Request samples

Content type
application/json
{
  • "user_name": "john-doe",
  • "access_key": "AKIAIOSFODNN7EXAMPLE",
  • "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "access_key": "AKIAIOSFODNN7EXAMPLE",
  • "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  • "user_name": "john-doe",
  • "is_active": true,
  • "created_at": "2023-01-15T10:30:00Z"
}

Get credential details

Returns detailed information about a specific credential

Authorizations:
ApiKey
path Parameters
id
required
integer >= 1
Example: 1

Unique identifier for the credential

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "access_key": "AKIAIOSFODNN7EXAMPLE",
  • "user_name": "john-doe",
  • "is_active": true,
  • "created_at": "2023-01-15T10:30:00Z",
  • "bucket_count": 3,
  • "buckets": [
    ]
}

Update credential

Updates an existing credential

Authorizations:
ApiKey
path Parameters
id
required
integer >= 1
Example: 1

Unique identifier for the credential

Request Body schema: application/json
required
user_name
string
is_active
boolean

Responses

Request samples

Content type
application/json
{
  • "user_name": "john-doe",
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Delete credential

Deletes an access credential

Authorizations:
ApiKey
path Parameters
id
required
integer >= 1
Example: 1

Unique identifier for the credential

Responses

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Management - Buckets

Bucket management via console

List all buckets

Returns a list of all buckets with detailed information

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "buckets": [
    ]
}

Create bucket

Creates a new bucket via management API

Authorizations:
ApiKey
Request Body schema: application/json
required
name
required
string^[a-z0-9\-\.]+$
owner_id
required
integer
region
string
Default: "us-east-1"

Responses

Request samples

Content type
application/json
{
  • "name": "my-new-bucket",
  • "owner_id": 1,
  • "region": "us-east-1"
}

Response samples

Content type
application/json
{
  • "name": "my-bucket",
  • "region": "us-east-1",
  • "owner": "john-doe",
  • "created_at": "2023-01-15T10:30:00Z",
  • "object_count": 150,
  • "total_size": 1073741824,
  • "total_size_human": "1.0 GB",
  • "objects": [
    ]
}

Get bucket details

Returns detailed information about a specific bucket including objects

Authorizations:
ApiKey
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

Responses

Response samples

Content type
application/json
{
  • "name": "my-bucket",
  • "region": "us-east-1",
  • "owner": "john-doe",
  • "created_at": "2023-01-15T10:30:00Z",
  • "object_count": 150,
  • "total_size": 1073741824,
  • "total_size_human": "1.0 GB",
  • "objects": [
    ]
}

Delete bucket

Deletes a bucket via management API

Authorizations:
ApiKey
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

Responses

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

Management - Objects

Object management via console

List objects in bucket

Returns a list of objects in the specified bucket

Authorizations:
ApiKey
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

query Parameters
prefix
string <= 255 characters
Example: prefix=photos/

Limits the response to keys that begin with the specified prefix

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ]
}

Delete multiple objects

Deletes multiple objects from a bucket

Authorizations:
ApiKey
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

Request Body schema: application/json
required
keys
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "keys": [
    ]
}

Response samples

Content type
application/json
{
  • "deleted": [
    ]
}

Get object details

Returns detailed information about a specific object

Authorizations:
ApiKey
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

key
required
string <= 255 characters
Example: folder/file.txt

Object key (file path) within the bucket

Responses

Response samples

Content type
application/json
{
  • "key": "photos/vacation.jpg",
  • "size": 1024000,
  • "size_human": "1.0 MB",
  • "content_type": "image/jpeg",
  • "etag": "9bb58f26192e4ba00f01e2e7b136bbd8",
  • "is_multipart": false,
  • "created_at": "2023-01-15T10:30:00Z",
  • "part_count": 0,
  • "metadata": {
    },
  • "storage_path": "my-bucket/objects/ab/cd/abcdef123456...",
  • "updated_at": "2023-01-15T10:30:00Z"
}

Delete object

Deletes a specific object

Authorizations:
ApiKey
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

key
required
string <= 255 characters
Example: folder/file.txt

Object key (file path) within the bucket

Responses

Response samples

Content type
application/json
{
  • "message": "Operation completed successfully"
}

List multipart uploads

Returns active multipart uploads for a bucket

Authorizations:
ApiKey
path Parameters
bucket
required
string [ 3 .. 63 ] characters ^[a-z0-9\-\.]+$
Example: my-bucket

Name of the S3 bucket

Responses

Response samples

Content type
application/json
{
  • "uploads": [
    ]
}

Management - Presigned URLs

Presigned URL management

List presigned URLs

Returns active presigned URLs

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "urls": [
    ]
}

Create presigned URL

Generates a new presigned URL

Authorizations:
ApiKey
Request Body schema: application/json
required
bucket_name
required
string
object_key
required
string
method
string
Default: "GET"
Enum: "GET" "PUT" "POST" "DELETE"
expires_in
integer [ 1 .. 604800 ]
Default: 3600

Expiration time in seconds (max 7 days)

access_key
required
string

Responses

Request samples

Content type
application/json
{
  • "bucket_name": "my-bucket",
  • "object_key": "file.txt",
  • "method": "GET",
  • "expires_in": 3600,
  • "access_key": "AKIAIOSFODNN7EXAMPLE"
}

Response samples

Content type
application/json
{
  • "url": "/my-bucket/file.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20230115%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230115T103000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=abc123&hash=def456"
}