Create an Object Storage bucket

post https://api.linode.com/{apiVersion}/object-storage/buckets

Creates an Object Storage bucket in the specified data center (region). If the bucket already exists on your account, this operation returns a 200 response with that bucket as if the API just created it.

📘

Accounts with negative balances can't access this operation.

The API still supports the clusterId equivalent (us-west-1) when setting a region for a new bucket, but you should use the regionId (us-west) instead.

You can use an outside API, such as the Ceph Object Gateway S3 API for more options.

OAuth scopes

object_storage:read_write

Learn more...

Path Params

apiVersion

string

required

Enum Call either the v4 URL, or v4beta for operations still in Beta.

Body Params

Information about the bucket you want to create.

acl

string

Defaults to private

The S3 predefined collection of grantees and permissions set for the bucket, also referred to as a Canned ACL.

cors_enabled

boolean

If set to false, cross-origin resource sharing (CORS) is disabled for all origins in the bucket.

endpoint_type

string

The type of s3_endpoint available to the active user in this region. See Endpoint types for more information.

label

string

required

The name for this bucket.

A bucket name can contain from 3 to 63 alphanumeric characters, dashes (-), or dots (.).
A bucket name can't end in a dash and you can't use two consecutive dashes.
A bucket name can't start or end in a dot, and you can't use two consecutive dots. As a best practice, only use dots if a certificate you're using with your bucket requires it. (For example, if you're using a custom TLS certificate.)
A bucket name needs to be unique in the region where you're creating the bucket. The API only reserves labels for the region where active buckets are created and stored. If you want to reserve this bucket's label in another region, create a new bucket with the same label in the new region.

region

string

The id assigned to the data center (region) where this Object Storage bucket should be created.

📘
This supports legacy clusterId values that represented a specific region. For example, us-east-1 is the legacy reference for the us-east region.

s3_endpoint

string

The active user's S3-compatible endpoint URL, based on the endpoint_type and region.

Responses

Response body

object

cluster

string

deprecated

Deprecated The legacy clusterId equivalent for the regionId where this bucket lives. The API maintains this for backward compatibility.

📘

This value and the regionId are interchangeable when used in requests. Best practice is to use the regionId.

This value is empty for newer regions that don't have a legacy clusterId.

created

date-time

When this bucket was created.

endpoint_type

string

The type of s3_endpoint available to the active user in this region. See Endpoint types for more information.

E0 E1 E2 E3

hostname

string

The hostname where this bucket can be accessed. This hostname can be accessed through a browser if the bucket is made public.

label

string

The name of this bucket.

objects

integer

The number of objects stored in this bucket.

region

string

The id of the region where this Object Storage bucket lives.

s3_endpoint

string

The active user's S3-compatible endpoint URL, based on the endpoint_type and region.

size

integer

The size of the bucket in bytes.

Language

Credentials


xxxxxxxxxx
1
curl --request POST \
2
     --url https://api.linode.com/v4/object-storage/buckets \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json' \
5
     --data '{"acl":"private"}'


xxxxxxxxxx
10
 
1
{
2
  "created": "2019-01-01T01:23:45",
3
  "endpoint_type": "E1",
4
  "hostname": "example-bucket-1.us-east-12.linodeobjects.com",
5
  "label": "example-bucket",
6
  "objects": 4,
7
  "region": "us-east",
8
  "s3_endpoint": "us-east-12.linodeobjects.com",
9
  "size": 188318981
10
}

📘

200The bucket created successfully.

📘

defaultSee Errors for the range of possible error response codes.