Object Storage v4.176.0

Object Storage Buckets List

GET https://api.linode.com/v4/object-storage/buckets

Returns a paginated list of all Object Storage Buckets that you own.

This endpoint is available for convenience. It is recommended that instead you use the more fully-featured S3 API directly.

Authorizations

personalAccessToken
oauthobject_storage:read_only

Request Samples

Response Samples

Responses

Object Storage Bucket Create

POST https://api.linode.com/v4/object-storage/buckets

Creates an Object Storage Bucket in the specified cluster.

Accounts with negative balances cannot access this command.

If the bucket already exists and is owned by you, this endpoint returns a 200 response with that bucket as if it had just been created.

This endpoint is available for convenience. It is recommended that instead you use the more fully-featured S3 API directly.

Authorizations

personalAccessToken
oauthobject_storage:read_write

Request Samples

Request Body Schema

acl
string
Enum: private public-read authenticated-read public-read-write Default: private

The Access Control Level of the bucket using a canned ACL string. For more fine-grained control of ACLs, use the S3 API directly.

cluster
Required
string

The ID of the Object Storage Cluster where this bucket should be created.

cors_enabled
boolean
Default: false

If true, the bucket will be created with CORS enabled for all origins. For more fine-grained controls of CORS, use the S3 API directly.

label
Required
string

The name for this bucket. Must be unique in the cluster you are creating the bucket in, or an error will be returned. Labels will be reserved only for the cluster that active buckets are created and stored in. If you want to reserve this bucket’s label in another cluster, you must create a new bucket with the same label in the new cluster.

Response Samples

Responses

Object Storage Buckets in Cluster List

GET https://api.linode.com/v4/object-storage/buckets/{clusterId}

Returns a list of Buckets in this cluster belonging to this Account.

This endpoint is available for convenience. It is recommended that instead you use the more fully-featured S3 API directly.

Authorizations

personalAccessToken
oauthobject_storage:read_only

Path Parameters

clusterIdstring
Required

The ID of the cluster this bucket exists in.

Request Samples

Response Samples

Responses

Object Storage Bucket Remove

DELETE https://api.linode.com/v4/object-storage/buckets/{clusterId}/{bucket}

Removes a single bucket.

Bucket objects must be removed prior to removing the bucket. While buckets containing objects may be deleted using the s3cmd command-line tool, such operations can fail if the bucket contains too many objects. The recommended way to empty large buckets is to use the S3 API to configure lifecycle policies that remove all objects, then delete the bucket.

This endpoint is available for convenience. It is recommended that instead you use the more fully-featured S3 API directly.

Authorizations

personalAccessToken
oauthobject_storage:read_write

Path Parameters

clusterIdstring
Required

The ID of the cluster this bucket exists in.

bucketstring
Required

The bucket name.

Request Samples

Response Samples

Responses

Object Storage Bucket View

GET https://api.linode.com/v4/object-storage/buckets/{clusterId}/{bucket}

Returns a single Object Storage Bucket.

This endpoint is available for convenience. It is recommended that instead you use the more fully-featured S3 API directly.

Authorizations

personalAccessToken
oauthobject_storage:read_only

Path Parameters

clusterIdstring
Required

The ID of the cluster this bucket exists in.

bucketstring
Required

The bucket name.

Request Samples

Response Samples

Responses

Object Storage Bucket Access Modify

POST https://api.linode.com/v4/object-storage/buckets/{clusterId}/{bucket}/access

Allows changing basic Cross-origin Resource Sharing (CORS) and Access Control Level (ACL) settings. Only allows enabling/disabling CORS for all origins, and/or setting canned ACLs.

For more fine-grained control of both systems, please use the more fully-featured S3 API directly.

Authorizations

personalAccessToken
oauthobject_storage:read_write

Path Parameters

clusterIdstring
Required

The ID of the cluster this bucket exists in.

bucketstring
Required

The bucket name.

Request Samples

Request Body Schema

acl
string
Enum: private public-read authenticated-read public-read-write custom

The Access Control Level of the bucket, as a canned ACL string. For more fine-grained control of ACLs, use the S3 API directly.

cors_enabled
boolean

If true, the bucket will be created with CORS enabled for all origins. For more fine-grained controls of CORS, use the S3 API directly.

Response Samples

Responses

Object Storage Bucket Access Update

PUT https://api.linode.com/v4/object-storage/buckets/{clusterId}/{bucket}/access

Allows changing basic Cross-origin Resource Sharing (CORS) and Access Control Level (ACL) settings. Only allows enabling/disabling CORS for all origins, and/or setting canned ACLs.

For more fine-grained control of both systems, please use the more fully-featured S3 API directly.

Authorizations

personalAccessToken
oauthobject_storage:read_write

Path Parameters

clusterIdstring
Required

The ID of the cluster this bucket exists in.

bucketstring
Required

The bucket name.

Request Samples

Request Body Schema

acl
string
Enum: private public-read authenticated-read public-read-write custom

The Access Control Level of the bucket, as a canned ACL string. For more fine-grained control of ACLs, use the S3 API directly.

cors_enabled
boolean

If true, the bucket will be created with CORS enabled for all origins. For more fine-grained controls of CORS, use the S3 API directly.

Response Samples

Responses

Object Storage Object ACL Config View

GET https://api.linode.com/v4/object-storage/buckets/{clusterId}/{bucket}/object-acl

View an Object’s configured Access Control List (ACL) in this Object Storage bucket. ACLs define who can access your buckets and objects and specify the level of access granted to those users.

This endpoint is available for convenience. It is recommended that instead you use the more fully-featured S3 API directly.

Authorizations

personalAccessToken
oauthobject_storage:read_only

Path Parameters

clusterIdstring
Required

The ID of the cluster this bucket exists in.

bucketstring
Required

The bucket name.

Query Parameters

name
Type:
string
Default:

The name of the object for which to retrieve its Access Control List (ACL). Use the Object Storage Bucket Contents List endpoint to access all object names in a bucket.

Request Samples

Response Samples

Responses

Object Storage Object ACL Config Update

PUT https://api.linode.com/v4/object-storage/buckets/{clusterId}/{bucket}/object-acl

Update an Object’s configured Access Control List (ACL) in this Object Storage bucket. ACLs define who can access your buckets and objects and specify the level of access granted to those users.

This endpoint is available for convenience. It is recommended that instead you use the more fully-featured S3 API directly.

Authorizations

personalAccessToken
oauthobject_storage:read_write

Path Parameters

clusterIdstring
Required

The ID of the cluster this bucket exists in.

bucketstring
Required

The bucket name.

Request Samples

Request Body Schema

acl
Required
string
Enum: private public-read authenticated-read public-read-write custom

The Access Control Level of the bucket, as a canned ACL string. For more fine-grained control of ACLs, use the S3 API directly.

name
Required
string

The name of the object for which to update its Access Control List (ACL). Use the Object Storage Bucket Contents List endpoint to access all object names in a bucket.

Response Samples

Responses

Object Storage Bucket Contents List

GET https://api.linode.com/v4/object-storage/buckets/{clusterId}/{bucket}/object-list

Returns the contents of a bucket. The contents are paginated using a marker, which is the name of the last object on the previous page. Objects may be filtered by prefix and delimiter as well; see Query Parameters for more information.

This endpoint is available for convenience. It is recommended that instead you use the more fully-featured S3 API directly.

Authorizations

personalAccessToken
oauthobject_storage:read_only

Path Parameters

clusterIdstring
Required

The ID of the cluster this bucket exists in.

bucketstring
Required

The bucket name.

Query Parameters

marker
Type:
string
Default:

The “marker” for this request, which can be used to paginate through large buckets. Its value should be the value of the next_marker property returned with the last page. Listing bucket contents does not support arbitrary page access. See the next_marker property in the responses section for more details.

delimiter
Type:
string
Default:

The delimiter for object names; if given, object names will be returned up to the first occurrence of this character. This is most commonly used with the / character to allow bucket transversal in a manner similar to a filesystem, however any delimiter may be used. Use in conjunction with prefix to see object names past the first occurrence of the delimiter.

prefix
Type:
string
Default:

Filters objects returned to only those whose name start with the given prefix. Commonly used in conjunction with delimiter to allow transversal of bucket contents in a manner similar to a filesystem.

page_size
Type:
integer 25..500
Default: 100
Default:
100

The number of items to return per page.

Request Samples

Response Samples

Responses

Object Storage Object URL Create

POST https://api.linode.com/v4/object-storage/buckets/{clusterId}/{bucket}/object-url

Creates a pre-signed URL to access a single Object in a bucket. This can be used to share objects, and also to create/delete objects by using the appropriate HTTP method in your request body’s method parameter.

This endpoint is available for convenience. It is recommended that instead you use the more fully-featured S3 API directly.

Authorizations

personalAccessToken
oauthobject_storage:read_write

Path Parameters

clusterIdstring
Required

The ID of the cluster this bucket exists in.

bucketstring
Required

The bucket name.

Request Samples

Request Body Schema

content_type
string

The expected Content-type header of the request this signed URL will be valid for. If provided, the Content-type header must be sent with the request when this URL is used, and must be the same as it was when the signed URL was created. Required for all methods except “GET” or “DELETE”.

expires_in
integer 360..86400
Default: 3600

How long this signed URL will be valid for, in seconds. If omitted, the URL will be valid for 3600 seconds (1 hour).

method
Required
string
Default: GET

The HTTP method allowed to be used with the pre-signed URL.

name
Required
string

The name of the object that will be accessed with the pre-signed URL. This object need not exist, and no error will be returned if it doesn’t. This behavior is useful for generating pre-signed URLs to upload new objects to by setting the method to “PUT”.

Response Samples

Responses

Object Storage TLS/SSL Cert Delete

DELETE https://api.linode.com/v4/object-storage/buckets/{clusterId}/{bucket}/ssl

Deletes this Object Storage bucket’s user uploaded TLS/SSL certificate and private key.

Authorizations

personalAccessToken
oauthobject_storage:read_write

Path Parameters

clusterIdstring
Required

The ID of the cluster this bucket exists in.

bucketstring
Required

The bucket name.

Request Samples

Response Samples

Responses

Object Storage TLS/SSL Cert View

GET https://api.linode.com/v4/object-storage/buckets/{clusterId}/{bucket}/ssl

Returns a boolean value indicating if this bucket has a corresponding TLS/SSL certificate that was uploaded by an Account user.

Authorizations

personalAccessToken
oauthobject_storage:read_only

Path Parameters

clusterIdstring
Required

The ID of the cluster this bucket exists in.

bucketstring
Required

The bucket name.

Request Samples

Response Samples

Responses

Object Storage TLS/SSL Cert Upload

POST https://api.linode.com/v4/object-storage/buckets/{clusterId}/{bucket}/ssl

Upload a TLS/SSL certificate and private key to be served when you visit your Object Storage bucket via HTTPS. Your TLS/SSL certificate and private key are stored encrypted at rest.

To replace an expired certificate, delete your current certificate and upload a new one.

Authorizations

personalAccessToken
oauthobject_storage:read_write

Path Parameters

clusterIdstring
Required

The ID of the cluster this bucket exists in.

bucketstring
Required

The bucket name.

Request Samples

Request Body Schema

certificate
Required
string

Your Base64 encoded and PEM formatted SSL certificate.

Line breaks must be represented as “\n” in the string for requests (but not when using the Linode CLI)

private_key
Required
string

The private key associated with this TLS/SSL certificate.

Line breaks must be represented as “\n” in the string for requests (but not when using the Linode CLI)

Response Samples

Responses

Object Storage Cancel

POST https://api.linode.com/v4/object-storage/cancel

Cancel Object Storage on an Account.

Warning: Removes all buckets and their contents from your Account. This data is irretrievable once removed.

Authorizations

personalAccessToken
oauthobject_storage:read_write

Request Samples

Response Samples

Responses

Clusters List

GET https://api.linode.com/v4/object-storage/clusters

Returns a paginated list of Object Storage Clusters that are available for use. Users can connect to the clusters with third party clients to create buckets and upload objects.

Authorizations

Request Samples

Response Samples

Responses

Cluster View

GET https://api.linode.com/v4/object-storage/clusters/{clusterId}

Returns a single Object Storage Cluster.

Authorizations

Path Parameters

clusterIdstring
Required

The ID of the Cluster.

Request Samples

Response Samples

Responses

Object Storage Keys List

GET https://api.linode.com/v4/object-storage/keys

Returns a paginated list of Object Storage Keys for authenticating to the Object Storage S3 API.

Authorizations

personalAccessToken
oauthobject_storage:read_only

Request Samples

Response Samples

Responses

Object Storage Key Create

POST https://api.linode.com/v4/object-storage/keys

Provisions a new Object Storage Key on your account.

  • Accounts with negative balances cannot access this command.
  • A successful request triggers an obj_access_key_create event.
  • To create a Limited Access Key with specific permissions, send a bucket_access array.
  • To create a Limited Access Key without access to any buckets, send an empty bucket_access array.
  • To create an Access Key with unlimited access to all clusters and all buckets, omit the bucket_access array.

Authorizations

personalAccessToken
oauthobject_storage:read_write

Request Samples

Request Body Schema

bucket_access
array of objects

Defines this key as a Limited Access Key. Limited Access Keys restrict this Object Storage key’s access to only the bucket(s) declared in this array and define their bucket-level permissions.

Limited Access Keys can:

  • list all buckets available on this Account, but cannot perform any actions on a bucket unless it has access to the bucket.

  • create new buckets, but do not have any access to the buckets it creates, unless explicitly given access to them.

Note: You can create an Object Storage Limited Access Key without access to any buckets. This is achieved by sending a request with an empty bucket_access array.

Note: If this field is omitted, a regular unlimited access key is issued.

bucket_name
string

The unique label of the bucket to which the key will grant limited access.

cluster
string

The Object Storage cluster where a bucket to which the key is granting access is hosted.

permissions
string
Enum: read_write read_only

This Limited Access Key’s permissions for the selected bucket.

label
string

The label given to this key. For display purposes only.

Response Samples

Responses

Object Storage Key Revoke

DELETE https://api.linode.com/v4/object-storage/keys/{keyId}

Revokes an Object Storage Key. This keypair will no longer be usable by third-party clients.

  • A successful request triggers an obj_access_key_delete event.

Authorizations

personalAccessToken
oauthobject_storage:read_write

Path Parameters

keyIdinteger
Required

The key to look up.

Request Samples

Response Samples

Responses

Object Storage Key View

GET https://api.linode.com/v4/object-storage/keys/{keyId}

Returns a single Object Storage Key provisioned for your account.

Authorizations

personalAccessToken
oauthobject_storage:read_only

Path Parameters

keyIdinteger
Required

The key to look up.

Request Samples

Response Samples

Responses

Object Storage Key Update

PUT https://api.linode.com/v4/object-storage/keys/{keyId}

Updates an Object Storage Key on your account.

  • A successful request triggers an obj_access_key_update event.

Authorizations

personalAccessToken
oauthobject_storage:read_write

Path Parameters

keyIdinteger
Required

The key to look up.

Request Samples

Request Body Schema

label
string

The label for this keypair, for display purposes only.

Response Samples

Responses

Object Storage Transfer View

GET https://api.linode.com/v4/object-storage/transfer

The amount of outbound data transfer used by your account’s Object Storage buckets. Object Storage adds 1 terabyte of outbound data transfer to your data transfer pool. See the Object Storage Overview guide for details on Object Storage transfer quotas.

Authorizations

personalAccessToken
oauthobject_storage:read_only

Request Samples

Response Samples

Responses