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.
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
oauth
object_storage:read_write
Path Parameters
clusterId
stringRequired
The ID of the cluster this bucket exists in.
bucket
stringRequired
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
oauth
object_storage:read_only
Path Parameters
clusterId
stringRequired
The ID of the cluster this bucket exists in.
bucket
stringRequired
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.
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.
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
oauth
object_storage:read_only
Path Parameters
clusterId
stringRequired
The ID of the cluster this bucket exists in.
bucket
stringRequired
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.
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
oauth
object_storage:read_only
Path Parameters
clusterId
stringRequired
The ID of the cluster this bucket exists in.
bucket
stringRequired
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
oauth
object_storage:read_write
Path Parameters
clusterId
stringRequired
The ID of the cluster this bucket exists in.
bucket
stringRequired
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”.
Deletes this Object Storage bucket’s user uploaded TLS/SSL certificate and private key.
Authorizations
personalAccessToken
oauth
object_storage:read_write
Path Parameters
clusterId
stringRequired
The ID of the cluster this bucket exists in.
bucket
stringRequired
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
oauth
object_storage:read_only
Path Parameters
clusterId
stringRequired
The ID of the cluster this bucket exists in.
bucket
stringRequired
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.
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
oauth
object_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
clusterId
stringRequired
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
oauth
object_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
oauth
object_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_writeread_only
This Limited Access Key’s permissions for the selected bucket.
label
string
The label given to this key. For display purposes only.
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
oauth
object_storage:read_write
Path Parameters
keyId
integerRequired
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
oauth
object_storage:read_only
Path Parameters
keyId
integerRequired
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
oauth
object_storage:read_write
Path Parameters
keyId
integerRequired
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.
