Client API: Object Storage: Buckets

Name	In	Type	Required
`service_id`	path	integer	yes

Responses

Section titled Make a bucket in the chosen region, or the service's home region

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`items`	array of BucketOut
`items[].id`	integer
`items[].name`	string
`items[].region`	string or null
`items[].location_id`	integer or null
`items[].location_name`	string or null
`items[].quota_bytes`	integer or null
`items[].used_bytes`	integer
`items[].object_count`	integer
`items[].usage_measured_at`	string or null
`items[].created_at`	string or null
`items[].deleted_at`	string or null
`items[].endpoint`	string or null
`items[].url`	string or null
`items[].cors_rules`	integer	How many CORS rules the bucket has
`items[].lifecycle_rules`	integer	How many lifecycle rules the bucket has
`items[].public_url`	string or null	The bucket's public URL while it is on, otherwise null
`items[].custom_domains`	integer	How many custom domains are linked to the bucket
`items[].versioning`	string, one of `off`, `enabled`, `suspended`	Whether the bucket keeps every version of its objects; once on, it is never off again
`items[].object_lock`	ObjectLockOut	A bucket's Object Lock and the default retention it gives new versions.
`items[].encryption`	boolean	True when objects written to the bucket are encrypted
`total`	integer
`bucket_prefix`	string
`max_buckets`	integer

Make a bucket in the chosen region, or the service's home region

POST /api/v1/client/object-storage/{service_id}/buckets

Make a bucket in the chosen region, or the service's home region.

versioning keeps every version of every object from the start. object_lock creates the bucket with Object Lock, which you cannot add later and which keeps versioning on for good; give it a mode and days or years for a default retention on every new version. Answers 422 when the default retention is out of range.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`service_id`	path	integer	yes

Request body

application/json (required)

Field	Type	Required	Description
`name`	string	yes
`location_id`	integer or null	no
`versioning`	boolean	no	Keep every version of every object. Object Lock turns this on whatever it says
`object_lock`	ObjectLockCreate or null	no	Create the bucket with Object Lock, which cannot be added later. Leave out for no lock
`object_lock.mode`	string, one of `GOVERNANCE`, `COMPLIANCE` or null	no	The default retention's mode; leave out for a lock with no default retention
`object_lock.days`	integer or null	no	Default retention in days, from 1 to 36500
`object_lock.years`	integer or null	no	Default retention in years, from 1 to 100, instead of days
`encryption`	boolean or null	no	Encrypt every object written to the bucket. Leave out to encrypt when default encryption is available. True while it is not available answers 409

Responses

Section titled Get bucket

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 201 response:

Field	Type	Description
`id`	integer
`name`	string
`region`	string or null
`location_id`	integer or null
`location_name`	string or null
`quota_bytes`	integer or null
`used_bytes`	integer
`object_count`	integer
`usage_measured_at`	string or null
`created_at`	string or null
`deleted_at`	string or null
`endpoint`	string or null
`url`	string or null
`cors_rules`	integer	How many CORS rules the bucket has
`lifecycle_rules`	integer	How many lifecycle rules the bucket has
`public_url`	string or null	The bucket's public URL while it is on, otherwise null
`custom_domains`	integer	How many custom domains are linked to the bucket
`versioning`	string, one of `off`, `enabled`, `suspended`	Whether the bucket keeps every version of its objects; once on, it is never off again
`object_lock`	ObjectLockOut	A bucket's Object Lock and the default retention it gives new versions.
`object_lock.enabled`	boolean	Whether the bucket was created with Object Lock
`object_lock.mode`	string, one of `GOVERNANCE`, `COMPLIANCE` or null	The default retention's mode; null for no default retention
`object_lock.days`	integer or null	How long the default retention keeps each new version, in days
`object_lock.years`	integer or null	`days` in years, when it is a whole number of years
`encryption`	boolean	True when objects written to the bucket are encrypted

Get bucket

GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`service_id`	path	integer	yes
`bucket_id`	path	integer	yes

Responses

Section titled Remove a bucket

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`id`	integer
`name`	string
`region`	string or null
`location_id`	integer or null
`location_name`	string or null
`quota_bytes`	integer or null
`used_bytes`	integer
`object_count`	integer
`usage_measured_at`	string or null
`created_at`	string or null
`deleted_at`	string or null
`endpoint`	string or null
`url`	string or null
`cors_rules`	integer	How many CORS rules the bucket has
`lifecycle_rules`	integer	How many lifecycle rules the bucket has
`public_url`	string or null	The bucket's public URL while it is on, otherwise null
`custom_domains`	integer	How many custom domains are linked to the bucket
`versioning`	string, one of `off`, `enabled`, `suspended`	Whether the bucket keeps every version of its objects; once on, it is never off again
`object_lock`	ObjectLockOut	A bucket's Object Lock and the default retention it gives new versions.
`object_lock.enabled`	boolean	Whether the bucket was created with Object Lock
`object_lock.mode`	string, one of `GOVERNANCE`, `COMPLIANCE` or null	The default retention's mode; null for no default retention
`object_lock.days`	integer or null	How long the default retention keeps each new version, in days
`object_lock.years`	integer or null	`days` in years, when it is a whole number of years
`encryption`	boolean	True when objects written to the bucket are encrypted

Remove a bucket

DELETE /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}

Remove a bucket. Refused while it holds objects unless force is set.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes
`bucket_id`	path	integer	yes
`force`	query	boolean	no	Destroy the objects in it as well Default: `False`.

Responses

Section titled Get bucket cors

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`ok`	boolean
`bucket`	string
`region`	string or null
`objects_destroyed`	integer

Get bucket cors

GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/cors

The bucket's CORS rules: which web pages on other sites may use it from a browser, with which methods and headers.

An empty list means the bucket has no rules of its own. Browsers on any site can then send it signed or presigned requests, and its public URL and custom domains answer no other site. An S3 client that reads the bucket's CORS sees one more rule first, coritan-dashboard, which lets the dashboard's file browser upload. This list never holds it.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID
`bucket_id`	path	integer	yes	The bucket's ID, from the service's bucket list

Responses

Section titled Replace the bucket's CORS rules with the ones sent, at most 99

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`bucket_id`	integer
`rules`	array of CorsRule
`rules[].id`	string or null	A name for the rule, up to 255 characters. Optional.
`rules[].allowed_origins`	array of string	Origins whose pages may use the bucket, such as https://example.com. Each may hold one , as in https://.example.com; * alone allows every origin.
`rules[].allowed_methods`	array of string	Any of GET, PUT, POST, DELETE and HEAD
`rules[].allowed_headers`	array of string	Request headers the page may send, such as Content-Type. Each may hold one *.
`rules[].expose_headers`	array of string	Response headers the page may read, such as ETag. No *.
`rules[].max_age_seconds`	integer or null	How long a browser may keep the answer to its preflight request, in seconds
`max_rules`	integer

Replace the bucket's CORS rules with the ones sent, at most 99

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/cors

Replace the bucket's CORS rules with the ones sent, at most 99.

The rules follow Amazon S3's: each needs at least one origin and one method (GET, PUT, POST, DELETE or HEAD); an origin or an allowed header may hold one *; exposed headers hold none. A browser request uses the first rule that matches its origin, method and headers. Answers 422 with the rule at fault, 409 when the service is not active, and 429 after 60 rule changes in an hour. An empty list removes every rule, as DELETE does. The rules apply within a minute.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID
`bucket_id`	path	integer	yes	The bucket's ID, from the service's bucket list

Request body

application/json (required)

Field	Type	Required	Description
`rules`	array of CorsRule	yes	Every rule the bucket should have, at most 99: S3 holds 100 and the dashboard keeps one so its file browser can upload. An empty list removes them all.
`rules[].id`	string or null	no	A name for the rule, up to 255 characters. Optional.
`rules[].allowed_origins`	array of string	yes	Origins whose pages may use the bucket, such as https://example.com. Each may hold one , as in https://.example.com; * alone allows every origin.
`rules[].allowed_methods`	array of string	yes	Any of GET, PUT, POST, DELETE and HEAD
`rules[].allowed_headers`	array of string	no	Request headers the page may send, such as Content-Type. Each may hold one *.
`rules[].expose_headers`	array of string	no	Response headers the page may read, such as ETag. No *.
`rules[].max_age_seconds`	integer or null	no	How long a browser may keep the answer to its preflight request, in seconds

Responses

Section titled Remove every CORS rule from the bucket

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`bucket_id`	integer
`rules`	array of CorsRule
`rules[].id`	string or null	A name for the rule, up to 255 characters. Optional.
`rules[].allowed_origins`	array of string	Origins whose pages may use the bucket, such as https://example.com. Each may hold one , as in https://.example.com; * alone allows every origin.
`rules[].allowed_methods`	array of string	Any of GET, PUT, POST, DELETE and HEAD
`rules[].allowed_headers`	array of string	Request headers the page may send, such as Content-Type. Each may hold one *.
`rules[].expose_headers`	array of string	Response headers the page may read, such as ETag. No *.
`rules[].max_age_seconds`	integer or null	How long a browser may keep the answer to its preflight request, in seconds
`max_rules`	integer

Remove every CORS rule from the bucket

DELETE /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/cors

Remove every CORS rule from the bucket. Browsers on any site can then send it signed or presigned requests, and its public URL and custom domains answer no other site.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID
`bucket_id`	path	integer	yes	The bucket's ID, from the service's bucket list

Responses

Section titled Link a custom domain to the bucket

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`bucket_id`	integer
`rules`	array of CorsRule
`rules[].id`	string or null	A name for the rule, up to 255 characters. Optional.
`rules[].allowed_origins`	array of string	Origins whose pages may use the bucket, such as https://example.com. Each may hold one , as in https://.example.com; * alone allows every origin.
`rules[].allowed_methods`	array of string	Any of GET, PUT, POST, DELETE and HEAD
`rules[].allowed_headers`	array of string	Request headers the page may send, such as Content-Type. Each may hold one *.
`rules[].expose_headers`	array of string	Response headers the page may read, such as ETag. No *.
`rules[].max_age_seconds`	integer or null	How long a browser may keep the answer to its preflight request, in seconds
`max_rules`	integer

Link a custom domain to the bucket

POST /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/domains

Link a custom domain to the bucket. A bucket takes up to 10.

When the domain is in a DNS zone this account holds on Coritan, we add its CNAME record and the domain is verified at once. If the name already has records in that zone, or is the zone's apex, we leave the zone as it is and the domain's error says how to point it. Otherwise it is pending: publish the two records in its records (a TXT at _coritan-storage.<hostname> and a CNAME to the bucket's public host), then call verify. Once verified we request its certificate.

Answers 403 as turning the public URL on does, 409 when the bucket has 10 domains or the hostname is in use on the platform, and 422 for a name that is not a hostname or belongs to the platform.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID.
`bucket_id`	path	integer	yes	The bucket's ID, from `GET /client/object-storage/{service_id}/buckets`.

Request body

application/json (required)

Field	Type	Required	Description
`hostname`	string	yes	The hostname, such as `cdn.example.com`.

Responses

Section titled Unlink a custom domain

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 201 response:

Field	Type	Description
`bucket_id`	integer
`bucket_name`	string
`public_url`	string or null	The bucket's public URL while it is on.
`public_url_enabled`	boolean
`public_url_available`	boolean	False when the platform offers no public URLs yet.
`disabled`	DisabledOut or null	Set when our staff turned public access off. It stays off until they turn it back on.
`disabled.at`	string or null
`disabled.reason`	string or null
`good_standing`	boolean	Whether the account may turn public access on: a saved payment method, credit or a paid invoice.
`website`	WebsiteOut
`website.enabled`	boolean
`website.index`	string	The object served for `/` and for every path that ends in `/`.
`website.error`	string or null	The object served, with status 404, for a missing key.
`website.spa`	boolean	Whether a missing key is answered with the index document and status 200.
`domains`	array of DomainOut
`domains[].hostname`	string
`domains[].status`	string	`pending` until its records are checked, `verified` once proved, `active` once its certificate is issued, `failed` when the last check did not find the records.
`domains[].url`	string or null	`https://<hostname>` once the domain serves the bucket.
`domains[].error`	string or null	What the last check found wrong, when `status` is `failed`. For a domain in your own zone, why we could not add its `CNAME` record.
`domains[].records`	array of DomainRecord
`domains[].created_at`	string or null
`domains[].verified_at`	string or null
`max_domains`	integer
`cname_target`	string or null	What each custom domain's CNAME record points at.
`rate_limit_per_minute`	integer	Requests one visitor address may make to the public URL in a minute.

Unlink a custom domain

DELETE /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/domains/{hostname}

Unlink a custom domain. It stops serving the bucket at once, and a CNAME record we added to your own zone for it is removed.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID.
`bucket_id`	path	integer	yes	The bucket's ID, from `GET /client/object-storage/{service_id}/buckets`.
`hostname`	path	string	yes	The custom domain, such as `cdn.example.com`.

Responses

Section titled Check a pending domain's DNS records now

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`bucket_id`	integer
`bucket_name`	string
`public_url`	string or null	The bucket's public URL while it is on.
`public_url_enabled`	boolean
`public_url_available`	boolean	False when the platform offers no public URLs yet.
`disabled`	DisabledOut or null	Set when our staff turned public access off. It stays off until they turn it back on.
`disabled.at`	string or null
`disabled.reason`	string or null
`good_standing`	boolean	Whether the account may turn public access on: a saved payment method, credit or a paid invoice.
`website`	WebsiteOut
`website.enabled`	boolean
`website.index`	string	The object served for `/` and for every path that ends in `/`.
`website.error`	string or null	The object served, with status 404, for a missing key.
`website.spa`	boolean	Whether a missing key is answered with the index document and status 200.
`domains`	array of DomainOut
`domains[].hostname`	string
`domains[].status`	string	`pending` until its records are checked, `verified` once proved, `active` once its certificate is issued, `failed` when the last check did not find the records.
`domains[].url`	string or null	`https://<hostname>` once the domain serves the bucket.
`domains[].error`	string or null	What the last check found wrong, when `status` is `failed`. For a domain in your own zone, why we could not add its `CNAME` record.
`domains[].records`	array of DomainRecord
`domains[].created_at`	string or null
`domains[].verified_at`	string or null
`max_domains`	integer
`cname_target`	string or null	What each custom domain's CNAME record points at.
`rate_limit_per_minute`	integer	Requests one visitor address may make to the public URL in a minute.

Check a pending domain's DNS records now

POST /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/domains/{hostname}/verify

Check a pending domain's DNS records now.

The TXT record must hold the domain's token, and the hostname must point at the bucket's public host: by CNAME, or by address records that match it. When both are there the domain is verified and its certificate is requested. When not, its status becomes failed with an error that says what is missing; publish the records and check again. A domain already verified is answered as it is.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID.
`bucket_id`	path	integer	yes	The bucket's ID, from `GET /client/object-storage/{service_id}/buckets`.
`hostname`	path	string	yes	The custom domain, such as `cdn.example.com`.

Responses

Section titled Get bucket encryption

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`bucket_id`	integer
`bucket_name`	string
`public_url`	string or null	The bucket's public URL while it is on.
`public_url_enabled`	boolean
`public_url_available`	boolean	False when the platform offers no public URLs yet.
`disabled`	DisabledOut or null	Set when our staff turned public access off. It stays off until they turn it back on.
`disabled.at`	string or null
`disabled.reason`	string or null
`good_standing`	boolean	Whether the account may turn public access on: a saved payment method, credit or a paid invoice.
`website`	WebsiteOut
`website.enabled`	boolean
`website.index`	string	The object served for `/` and for every path that ends in `/`.
`website.error`	string or null	The object served, with status 404, for a missing key.
`website.spa`	boolean	Whether a missing key is answered with the index document and status 200.
`domains`	array of DomainOut
`domains[].hostname`	string
`domains[].status`	string	`pending` until its records are checked, `verified` once proved, `active` once its certificate is issued, `failed` when the last check did not find the records.
`domains[].url`	string or null	`https://<hostname>` once the domain serves the bucket.
`domains[].error`	string or null	What the last check found wrong, when `status` is `failed`. For a domain in your own zone, why we could not add its `CNAME` record.
`domains[].records`	array of DomainRecord
`domains[].created_at`	string or null
`domains[].verified_at`	string or null
`max_domains`	integer
`cname_target`	string or null	What each custom domain's CNAME record points at.
`rate_limit_per_minute`	integer	Requests one visitor address may make to the public URL in a minute.

Get bucket encryption

GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/encryption

The bucket's default encryption: whether objects written to it are encrypted, and whether you can turn it on now.

Encryption applies to objects written after it was turned on. Objects already in the bucket are not encrypted and are not changed.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID
`bucket_id`	path	integer	yes	The bucket's ID, from the service's bucket list

Responses

Section titled Turn default encryption on or off for the bucket

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`bucket_id`	integer	The bucket's ID
`enabled`	boolean	True when objects written to the bucket are encrypted
`algorithm`	string or null	AES256 while encryption is on, otherwise null
`available`	boolean	Whether you can turn encryption on for this bucket now. False when encryption is not offered yet or the service is not active. You can always turn it off while the service is active.
`reason`	string or null	Why available is false, in a sentence. Null when it is true.

Turn default encryption on or off for the bucket

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/encryption

Turn default encryption on or off for the bucket.

On encrypts every object written to the bucket from now on with AES-256. Reading, listing, copying, presigned URLs and the public URL work as before, and your access keys need nothing extra. Objects already in the bucket stay as they were. To encrypt them, copy each one over itself or upload it again. Off stops encrypting new objects and leaves the ones already encrypted readable. Answers 409 when you turn it on while it is not offered yet, and 409 when the service is not active. Answers 429 after 60 changes in an hour. The change applies within seconds.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID
`bucket_id`	path	integer	yes	The bucket's ID, from the service's bucket list

Request body

application/json (required)

Field	Type	Required	Description
`enabled`	boolean	yes	True encrypts every object written to the bucket from now on. False stops encrypting new objects. Objects already in the bucket keep the state they were written in.

Responses

Section titled The bucket's lifecycle rules: what we delete from it, and when

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`bucket_id`	integer	The bucket's ID
`enabled`	boolean	True when objects written to the bucket are encrypted
`algorithm`	string or null	AES256 while encryption is on, otherwise null
`available`	boolean	Whether you can turn encryption on for this bucket now. False when encryption is not offered yet or the service is not active. You can always turn it off while the service is active.
`reason`	string or null	Why available is false, in a sentence. Null when it is true.

The bucket's lifecycle rules: what we delete from it, and when

GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/lifecycle

The bucket's lifecycle rules: what we delete from it, and when.

New buckets start with one rule (default_rule_id) that aborts unfinished multipart uploads after 7 days. Rules run once a day, so an object can stay up to a day after its rule makes it due.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID
`bucket_id`	path	integer	yes	The bucket's ID, from the service's bucket list

Responses

Section titled Replace the bucket's lifecycle rules with the ones sent, at most 100

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`bucket_id`	integer
`rules`	array of LifecycleRule
`rules[].id`	string or null	A name for the rule, unique in the bucket. Blank names become rule-1, rule-2 and so on.
`rules[].enabled`	boolean	False keeps the rule without applying it
`rules[].prefix`	string	Only keys that start with this. Empty means every key.
`rules[].tags`	array of LifecycleTag	Only objects with all of these tags, up to 10
`rules[].object_size_greater_than`	integer or null	Only objects larger than this many bytes
`rules[].object_size_less_than`	integer or null	Only objects smaller than this many bytes
`rules[].expiration_days`	integer or null	Delete objects this many days after they were uploaded
`rules[].expiration_date`	string or null	Delete objects from this date on, YYYY-MM-DD, at midnight UTC
`rules[].expired_object_delete_marker`	boolean	Remove a delete marker once it is the only version of its key left
`rules[].noncurrent_days`	integer or null	Delete an old version this many days after a newer one replaced it
`rules[].newer_noncurrent_versions`	integer or null	Keep this many of the newest old versions whatever their age, 1–100. Needs noncurrent_days.
`rules[].abort_incomplete_multipart_days`	integer or null	Abort a multipart upload this many days after it started, if it is still unfinished
`max_rules`	integer
`default_rule_id`	string	The ID of the rule new buckets start with

Replace the bucket's lifecycle rules with the ones sent, at most 100

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/lifecycle

Replace the bucket's lifecycle rules with the ones sent, at most 100.

Each rule picks objects by key prefix, tags and size, and needs at least one action: delete objects some days after upload or from a date, delete old versions some days after they were replaced (keeping the newest few if asked), remove delete markers that are the only version left, or abort multipart uploads still unfinished after some days. Days count from the object's upload time, in UTC. Transitions to another storage class are refused. Answers 422 with the rule at fault, 409 when the service is not active, and 429 after 60 rule changes in an hour. An empty list removes every rule, as DELETE does. Deletions the rules make are free.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID
`bucket_id`	path	integer	yes	The bucket's ID, from the service's bucket list

Request body

application/json (required)

Field	Type	Required	Description
`rules`	array of LifecycleRuleIn	yes	Every rule the bucket should have, at most 100. An empty list removes them all.
`rules[].id`	string or null	no	A name for the rule, unique in the bucket. Blank names become rule-1, rule-2 and so on.
`rules[].enabled`	boolean	no	False keeps the rule without applying it
`rules[].prefix`	string	no	Only keys that start with this. Empty means every key.
`rules[].tags`	array of LifecycleTag	no	Only objects with all of these tags, up to 10
`rules[].object_size_greater_than`	integer or null	no	Only objects larger than this many bytes
`rules[].object_size_less_than`	integer or null	no	Only objects smaller than this many bytes
`rules[].expiration_days`	integer or null	no	Delete objects this many days after they were uploaded
`rules[].expiration_date`	string or null	no	Delete objects from this date on, YYYY-MM-DD, at midnight UTC
`rules[].expired_object_delete_marker`	boolean	no	Remove a delete marker once it is the only version of its key left
`rules[].noncurrent_days`	integer or null	no	Delete an old version this many days after a newer one replaced it
`rules[].newer_noncurrent_versions`	integer or null	no	Keep this many of the newest old versions whatever their age, 1–100. Needs noncurrent_days.
`rules[].abort_incomplete_multipart_days`	integer or null	no	Abort a multipart upload this many days after it started, if it is still unfinished
`rules[].transitions`	array of any or null	no	Not offered. Any value is refused, since there is one storage class.
`rules[].noncurrent_version_transitions`	array of any or null	no	Not offered, as transitions

Responses

Section titled Remove every lifecycle rule from the bucket, the default one included

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`bucket_id`	integer
`rules`	array of LifecycleRule
`rules[].id`	string or null	A name for the rule, unique in the bucket. Blank names become rule-1, rule-2 and so on.
`rules[].enabled`	boolean	False keeps the rule without applying it
`rules[].prefix`	string	Only keys that start with this. Empty means every key.
`rules[].tags`	array of LifecycleTag	Only objects with all of these tags, up to 10
`rules[].object_size_greater_than`	integer or null	Only objects larger than this many bytes
`rules[].object_size_less_than`	integer or null	Only objects smaller than this many bytes
`rules[].expiration_days`	integer or null	Delete objects this many days after they were uploaded
`rules[].expiration_date`	string or null	Delete objects from this date on, YYYY-MM-DD, at midnight UTC
`rules[].expired_object_delete_marker`	boolean	Remove a delete marker once it is the only version of its key left
`rules[].noncurrent_days`	integer or null	Delete an old version this many days after a newer one replaced it
`rules[].newer_noncurrent_versions`	integer or null	Keep this many of the newest old versions whatever their age, 1–100. Needs noncurrent_days.
`rules[].abort_incomplete_multipart_days`	integer or null	Abort a multipart upload this many days after it started, if it is still unfinished
`max_rules`	integer
`default_rule_id`	string	The ID of the rule new buckets start with

Remove every lifecycle rule from the bucket, the default one included

DELETE /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/lifecycle

Remove every lifecycle rule from the bucket, the default one included. Nothing is deleted from it on a schedule after this.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID
`bucket_id`	path	integer	yes	The bucket's ID, from the service's bucket list

Responses

Section titled List lifecycle runs

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`bucket_id`	integer
`rules`	array of LifecycleRule
`rules[].id`	string or null	A name for the rule, unique in the bucket. Blank names become rule-1, rule-2 and so on.
`rules[].enabled`	boolean	False keeps the rule without applying it
`rules[].prefix`	string	Only keys that start with this. Empty means every key.
`rules[].tags`	array of LifecycleTag	Only objects with all of these tags, up to 10
`rules[].object_size_greater_than`	integer or null	Only objects larger than this many bytes
`rules[].object_size_less_than`	integer or null	Only objects smaller than this many bytes
`rules[].expiration_days`	integer or null	Delete objects this many days after they were uploaded
`rules[].expiration_date`	string or null	Delete objects from this date on, YYYY-MM-DD, at midnight UTC
`rules[].expired_object_delete_marker`	boolean	Remove a delete marker once it is the only version of its key left
`rules[].noncurrent_days`	integer or null	Delete an old version this many days after a newer one replaced it
`rules[].newer_noncurrent_versions`	integer or null	Keep this many of the newest old versions whatever their age, 1–100. Needs noncurrent_days.
`rules[].abort_incomplete_multipart_days`	integer or null	Abort a multipart upload this many days after it started, if it is still unfinished
`max_rules`	integer
`default_rule_id`	string	The ID of the rule new buckets start with

List lifecycle runs

GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/lifecycle/runs

The latest daily runs of the bucket's lifecycle rules, newest first: when each ran, what it removed and aborted, and what went wrong.

A run that stops before the end of a large bucket says so with complete false, and the next run carries on where it stopped. What a run could not delete is still due, and the next run tries again.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID
`bucket_id`	path	integer	yes	The bucket's ID, from the service's bucket list
`limit`	query	integer	no	How many runs to return, newest first, 1–100 Default: `20`.

Responses

Section titled The bucket's event notification rules, oldest first

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`items`	array of LifecycleRun
`items[].id`	integer
`items[].started_at`	string or null
`items[].finished_at`	string or null	Empty while the run is going
`items[].removed_objects`	integer	Objects, old versions and delete markers removed
`items[].removed_bytes`	integer	Bytes deleted for good
`items[].aborted_uploads`	integer
`items[].complete`	boolean	False when the run stopped before the end of the bucket. The next run carries on from there.
`items[].error`	string or null
`total`	integer

The bucket's event notification rules, oldest first

GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/notifications

The bucket's event notification rules, oldest first.

Each rule names its events, the prefix and suffix a key must have, the url events go to, its status (active or paused, with paused_reason when we paused it after a day of failed deliveries), when a delivery last worked or failed, and how many are waiting (pending). The signing secret is never listed. limits holds the rules a bucket may have and the retry schedule; events lists what each event covers.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, as `GET .../buckets` lists it

Responses

Section titled Add a rule: POST each matching event in the bucket to url

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Add a rule: POST each matching event in the bucket to url

POST /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/notifications

Add a rule: POST each matching event in the bucket to url.

Answers the rule and its signing_secret, which is shown this once; keep it to check the X-Coritan-Signature header of each delivery. Refused with 422 when the address is not https, is inside Coritan, or resolves to a private, loopback or link-local network; with 409 when the bucket already has 100 rules or the rule overlaps another (they share an event and a key could match both filters).

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, as `GET .../buckets` lists it

Request body

application/json (required)

Field	Type	Required	Description
`events`	array of string	yes	What to send: `object-create` (PutObject, CopyObject, CompleteMultipartUpload, PostObject), `object-delete` (DeleteObject, DeleteObjects, LifecycleDeletion), or both
`url`	string	yes	The https:// address to POST each event to
`prefix`	string	no	Only keys that start with this
`suffix`	string	no	Only keys that end with this
`description`	string or null	no	Your own words for the rule

Responses

Section titled Change a rule

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Change a rule

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/notifications/{rule_id}

Change a rule. Fields left out stay as they are.

enabled: false pauses it and cancels the events waiting to be sent; enabled: true turns it back on, and it sends changes made from then on. The same checks as creating a rule apply.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, as `GET .../buckets` lists it
`rule_id`	path	integer	yes	The notification rule's id

Request body

application/json (required)

Field	Type	Required	Description
`events`	array of string or null	no	As when creating; leave it out to keep it
`url`	string or null	no	A new https:// address
`prefix`	string or null	no	A new prefix; "" for none
`suffix`	string or null	no	A new suffix; "" for none
`description`	string or null	no	New words
`enabled`	boolean or null	no	false pauses the rule and cancels its queued events; true turns it back on

Responses

Section titled Delete a rule

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Delete a rule

DELETE /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/notifications/{rule_id}

Delete a rule. Events waiting to be sent for it are cancelled.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, as `GET .../buckets` lists it
`rule_id`	path	integer	yes	The notification rule's id

Responses

Section titled The rule's deliveries of the last 30 days, newest first

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

The rule's deliveries of the last 30 days, newest first

GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/notifications/{rule_id}/deliveries

The rule's deliveries of the last 30 days, newest first.

Each names the event (event_name, the object key, size, etag, version_id, event_time), its status (pending, sending, delivered, failed, cancelled), the attempts made, when the next is due, and the address's response_status and the start of its response_body. next_before_id is null on the last page.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, as `GET .../buckets` lists it
`rule_id`	path	integer	yes	The notification rule's id
`status`	query	string or null	no	Only deliveries in this state: pending, sending, delivered, failed, cancelled
`limit`	query	integer	no	Deliveries per page, newest first Default: `50`.
`before_id`	query	integer or null	no	The `next_before_id` of the previous page, for the page after it

Responses

Section titled Replace the rule's signing secret and answer the new one, shown this once

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Replace the rule's signing secret and answer the new one, shown this once

POST /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/notifications/{rule_id}/rotate-secret

Replace the rule's signing secret and answer the new one, shown this once. Every delivery from now on is signed with it, retries of earlier events included, so update your receiver straight away.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, as `GET .../buckets` lists it
`rule_id`	path	integer	yes	The notification rule's id

Responses

Section titled Send test notification

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Send test notification

POST /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/notifications/{rule_id}/test

Send the rule's address a test event now, signed like any other, and answer what it replied.

The body is {"Service": "Coritan Object Storage", "Event": "s3:TestEvent", ...}. delivered is true when the address answered with a 2xx status; response_status and response_body hold what it said. A test is never retried and never pauses the rule. It works on a paused rule too, so you can check a fix before turning it back on.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, as `GET .../buckets` lists it
`rule_id`	path	integer	yes	The notification rule's id

Responses

Section titled Get bucket object lock

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Get bucket object lock

GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/object-lock

Whether the bucket has Object Lock, and the default retention it gives every new version: mode (GOVERNANCE or COMPLIANCE) and days, or null for none. years repeats days when it is a whole number of years.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, from the bucket list

Responses

Section titled Change the default retention of a bucket with Object Lock

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`enabled`	boolean	Whether the bucket was created with Object Lock
`mode`	string, one of `GOVERNANCE`, `COMPLIANCE` or null	The default retention's mode; null for no default retention
`days`	integer or null	How long the default retention keeps each new version, in days
`years`	integer or null	`days` in years, when it is a whole number of years
`bucket_id`	integer

Change the default retention of a bucket with Object Lock

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/object-lock

Change the default retention of a bucket with Object Lock.

Send a mode with days or years, or mode null to remove the default. Versions that already exist keep the retention they have. A compliance default can only be made longer and stays compliance: anything else answers 409 with the current mode and days. To shorten or remove a governance default, set confirm to the bucket's name, or the answer is 422. A bucket created without Object Lock answers 409, because Object Lock can only be chosen at creation.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, from the bucket list

Request body

application/json (required)

Field	Type	Required	Description
`mode`	string, one of `GOVERNANCE`, `COMPLIANCE` or null	no	The default retention's mode; null removes the default retention
`days`	integer or null	no	How long, in days, from 1 to 36500
`years`	integer or null	no	How long, in years, from 1 to 100, instead of days
`confirm`	string or null	no	The bucket's name, needed to shorten or remove a governance default

Responses

Section titled One page of the bucket under prefix, folders first

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`enabled`	boolean	Whether the bucket was created with Object Lock
`mode`	string, one of `GOVERNANCE`, `COMPLIANCE` or null	The default retention's mode; null for no default retention
`days`	integer or null	How long the default retention keeps each new version, in days
`years`	integer or null	`days` in years, when it is a whole number of years
`bucket_id`	integer

One page of the bucket under prefix, folders first

GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects

One page of the bucket under prefix, folders first.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes
`bucket_id`	path	integer	yes
`prefix`	query	string	no
`token`	query	string or null	no
`max_keys`	query	integer	no	Default: `200`.
`flat`	query	boolean	no	No folder collapsing: every key under the prefix Default: `False`.

Responses

Section titled Delete named objects

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`items`	array of ObjectItem
`items[].key`	string
`items[].size`	integer or null
`items[].last_modified`	string or null
`items[].etag`	string or null
`items[].is_prefix`	boolean
`prefix`	string
`next_token`	string or null

Delete named objects

DELETE /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects

Delete named objects. Per-key failures are reported, not raised.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`service_id`	path	integer	yes
`bucket_id`	path	integer	yes

Request body

application/json (required)

Field	Type	Required
`keys`	array of string	yes

Responses

Section titled Get object details

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`deleted`	integer
`errors`	array of object

Get object details

GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects/details

One version of an object: its size, type, metadata and tags, its retention and legal hold, and the key's versions. Answers 404 for a key or version that does not exist, or a version that is a delete marker.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, from the bucket list
`key`	query	string	yes	The object's key
`version_id`	query	string or null	no	A version's id; the current version when left out

Responses

Section titled Put a legal hold on a version, or take it off

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`key`	string
`version_id`	string
`is_latest`	boolean
`size`	integer
`content_type`	string or null
`etag`	string or null
`last_modified`	string or null
`metadata`	Metadata	The object's `x-amz-meta-*` values
`tags`	array of TagOut
`tags[].key`	string
`tags[].value`	string
`retention`	RetentionView or null
`retention.mode`	string, one of `GOVERNANCE`, `COMPLIANCE`
`retention.until`	string	When the retention ends, UTC
`retention.active`	boolean	False once the date has passed
`legal_hold`	boolean
`object_lock`	boolean	Whether the bucket has Object Lock, so retention and legal holds apply
`versioning`	string, one of `off`, `enabled`, `suspended`
`versions`	array of VersionItem	This key's versions and delete markers, newest first, up to 50
`versions[].key`	string
`versions[].version_id`	string	The version's id; `null` for an object written while versioning was off
`versions[].is_latest`	boolean	Whether this is the object's current version
`versions[].is_delete_marker`	boolean	A delete marker hides the object; deleting the marker brings it back
`versions[].size`	integer or null
`versions[].last_modified`	string or null
`versions[].etag`	string or null
`versions_truncated`	boolean	True when the key has more than 50

Put a legal hold on a version, or take it off

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects/legal-hold

Put a legal hold on a version, or take it off. While a version has a legal hold nobody can delete it, whatever its retention says. Answers 409 on a bucket without Object Lock.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, from the bucket list

Request body

application/json (required)

Field	Type	Required	Description
`key`	string	yes	The object's key
`version_id`	string or null	no	The version's id; the current version when left out
`on`	boolean	yes	True puts a legal hold on the version; false takes it off

Responses

Section titled A short-lived URL the browser uses directly for one GET, PUT or DELETE

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`key`	string
`version_id`	string
`legal_hold`	boolean

A short-lived URL the browser uses directly for one GET, PUT or DELETE

POST /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects/presign

A short-lived URL the browser uses directly for one GET, PUT or DELETE.

Anyone who has the URL can use it until it expires. We count each request made with it like one signed with your own key and bill it to your account, as the bucket's owner.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`service_id`	path	integer	yes
`bucket_id`	path	integer	yes

Request body

application/json (required)

Field	Type	Required	Description
`key`	string	yes
`op`	string, one of `get`, `put`, `delete`	yes
`content_type`	string or null	no
`expires`	integer or null	no
`download`	boolean	no
`version_id`	string or null	no	For get: the version to download, from the versions list. Leave out for the current one

Responses

Section titled Restore object version

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`url`	string
`method`	string
`headers`	Headers
`expires_in`	integer
`expires_at`	string
`version_id`	string or null	The version the URL downloads, when one was asked for

Restore object version

POST /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects/restore

Make an older version current again by copying it over the current one, with its metadata and tags. The version it replaces is kept. Answers 409 on a bucket that does not keep versions, 404 for a version that does not exist, and 422 for a version larger than 5 GB.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, from the bucket list

Request body

application/json (required)

Field	Type	Required	Description
`key`	string	yes
`version_id`	string	yes	The version to copy over the current one

Responses

Section titled Give a version a retention, or change the one it has

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`ok`	boolean
`key`	string
`restored_from`	string
`version_id`	string	The id of the new current version

Give a version a retention, or change the one it has

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects/retention

Give a version a retention, or change the one it has.

Compliance retention can only be made longer and stays compliance: anything else answers 409 with locked_until. Governance retention can be made longer freely; to shorten it, or to remove it with mode null, set confirm to the object's name after the last /, or the answer is 422. Removed governance retention ends within a minute. Answers 409 on a bucket without Object Lock, and 422 for a date less than a minute ahead or more than 100 years ahead.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, from the bucket list

Request body

application/json (required)

Field	Type	Required	Description
`key`	string	yes	The object's key
`version_id`	string or null	no	The version's id; the current version when left out
`mode`	string, one of `GOVERNANCE`, `COMPLIANCE` or null	no	The retention's mode; null removes governance retention, which then ends within a minute
`until`	string (date-time) or null	no	When the retention ends, ISO 8601; at least a minute ahead
`confirm`	string or null	no	The object's name after the last `/`, needed to shorten or remove governance retention

Responses

Section titled Delete one version or delete marker for good

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`key`	string
`version_id`	string
`retention`	RetentionView or null
`retention.mode`	string, one of `GOVERNANCE`, `COMPLIANCE`
`retention.until`	string	When the retention ends, UTC
`retention.active`	boolean	False once the date has passed

Delete one version or delete marker for good

DELETE /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects/version

Delete one version or delete marker for good. There is no undo.

A version with a legal hold, or under compliance retention, answers 409; for compliance locked_until says when it can be deleted. A version under governance retention answers 409 unless bypass_governance is true and confirm is the object's name after the last / (422 when it does not match). Deleting a delete marker makes the version under it current again.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, from the bucket list

Request body

application/json (required)

Field	Type	Required	Description
`key`	string	yes
`version_id`	string	yes	The version or delete marker to remove
`bypass_governance`	boolean	no	Delete a version under governance retention anyway
`confirm`	string or null	no	The object's name after the last `/`, needed with `bypass_governance`

Responses

Section titled List object versions

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`ok`	boolean
`key`	string
`version_id`	string
`delete_marker`	boolean	True when what was removed was a delete marker

List object versions

GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects/versions

One page of every version and delete marker under prefix, by key and newest first, with the folders under it. A bucket that never kept versions lists each object once, with version_id null.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, from the bucket list
`prefix`	query	string	no	Only keys that start with this
`key_marker`	query	string or null	no	`next_key_marker` from the page before
`version_marker`	query	string or null	no	`next_version_marker` from the page before
`max_keys`	query	integer	no	Versions and delete markers per page, from 1 to 1000 Default: `100`.
`flat`	query	boolean	no	Every key under the prefix, with no folders Default: `False`.

Responses

Section titled Get public access

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`items`	array of VersionItem
`items[].key`	string
`items[].version_id`	string	The version's id; `null` for an object written while versioning was off
`items[].is_latest`	boolean	Whether this is the object's current version
`items[].is_delete_marker`	boolean	A delete marker hides the object; deleting the marker brings it back
`items[].size`	integer or null
`items[].last_modified`	string or null
`items[].etag`	string or null
`prefixes`	array of string	Folders directly under `prefix`; empty when `flat` is true
`prefix`	string
`next_key_marker`	string or null	Pass back as `key_marker` for the next page
`next_version_marker`	string or null	Pass back as `version_marker` for the next page

Get public access

GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/public

How the bucket is served to the public: its public URL, its custom domains with the DNS records each needs, and its website settings.

public_url_available is false when the platform offers no public URLs yet; custom domains still work then. disabled is set when our staff turned public access off. Answers 404 for a bucket that is not this service's.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID.
`bucket_id`	path	integer	yes	The bucket's ID, from `GET /client/object-storage/{service_id}/buckets`.

Responses

Section titled Turn the bucket's public URL on or off

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`bucket_id`	integer
`bucket_name`	string
`public_url`	string or null	The bucket's public URL while it is on.
`public_url_enabled`	boolean
`public_url_available`	boolean	False when the platform offers no public URLs yet.
`disabled`	DisabledOut or null	Set when our staff turned public access off. It stays off until they turn it back on.
`disabled.at`	string or null
`disabled.reason`	string or null
`good_standing`	boolean	Whether the account may turn public access on: a saved payment method, credit or a paid invoice.
`website`	WebsiteOut
`website.enabled`	boolean
`website.index`	string	The object served for `/` and for every path that ends in `/`.
`website.error`	string or null	The object served, with status 404, for a missing key.
`website.spa`	boolean	Whether a missing key is answered with the index document and status 200.
`domains`	array of DomainOut
`domains[].hostname`	string
`domains[].status`	string	`pending` until its records are checked, `verified` once proved, `active` once its certificate is issued, `failed` when the last check did not find the records.
`domains[].url`	string or null	`https://<hostname>` once the domain serves the bucket.
`domains[].error`	string or null	What the last check found wrong, when `status` is `failed`. For a domain in your own zone, why we could not add its `CNAME` record.
`domains[].records`	array of DomainRecord
`domains[].created_at`	string or null
`domains[].verified_at`	string or null
`max_domains`	integer
`cname_target`	string or null	What each custom domain's CNAME record points at.
`rate_limit_per_minute`	integer	Requests one visitor address may make to the public URL in a minute.

Turn the bucket's public URL on or off

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/public

Turn the bucket's public URL on or off.

While it is on, anyone with a link can read every object in the bucket at https://<token>.<public domain>/<key>, and each read our edge does not answer from its cache counts as a Class B operation. Listing the bucket is never public. The URL keeps its token when you turn it off and on again.

Turning it on answers 403 when the account has no saved payment method, no credit and no paid invoice, and when our staff turned public access off for the bucket; 409 when the platform offers no public URLs yet.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID.
`bucket_id`	path	integer	yes	The bucket's ID, from `GET /client/object-storage/{service_id}/buckets`.

Request body

application/json (required)

Field	Type	Required	Description
`enabled`	boolean	yes	True to serve the bucket at its public URL, false to stop.

Responses

Section titled Purge cache

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`bucket_id`	integer
`bucket_name`	string
`public_url`	string or null	The bucket's public URL while it is on.
`public_url_enabled`	boolean
`public_url_available`	boolean	False when the platform offers no public URLs yet.
`disabled`	DisabledOut or null	Set when our staff turned public access off. It stays off until they turn it back on.
`disabled.at`	string or null
`disabled.reason`	string or null
`good_standing`	boolean	Whether the account may turn public access on: a saved payment method, credit or a paid invoice.
`website`	WebsiteOut
`website.enabled`	boolean
`website.index`	string	The object served for `/` and for every path that ends in `/`.
`website.error`	string or null	The object served, with status 404, for a missing key.
`website.spa`	boolean	Whether a missing key is answered with the index document and status 200.
`domains`	array of DomainOut
`domains[].hostname`	string
`domains[].status`	string	`pending` until its records are checked, `verified` once proved, `active` once its certificate is issued, `failed` when the last check did not find the records.
`domains[].url`	string or null	`https://<hostname>` once the domain serves the bucket.
`domains[].error`	string or null	What the last check found wrong, when `status` is `failed`. For a domain in your own zone, why we could not add its `CNAME` record.
`domains[].records`	array of DomainRecord
`domains[].created_at`	string or null
`domains[].verified_at`	string or null
`max_domains`	integer
`cname_target`	string or null	What each custom domain's CNAME record points at.
`rate_limit_per_minute`	integer	Requests one visitor address may make to the public URL in a minute.

Purge cache

POST /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/public/purge

Make our edge forget what it cached for the bucket, on its public URL and every custom domain. Name up to 100 paths to purge those alone, or leave them out to purge everything. The next request for each path reads the object again. Answers 409 when nothing serves the bucket.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID.
`bucket_id`	path	integer	yes	The bucket's ID, from `GET /client/object-storage/{service_id}/buckets`.

Request body

application/json

Field	Type	Required	Description
`paths`	array of string or null	no	Paths to purge, such as `/images/logo.png`. Leave it out to purge everything the bucket serves.

Responses

Section titled The bucket's replication rules, the buckets a new rule may copy to, and the limits

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`hosts`	array of string	The hostnames whose cached copies were purged.
`paths`	array of string	The paths purged; empty when everything was.

The bucket's replication rules, the buckets a new rule may copy to, and the limits

GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/replication

The bucket's replication rules, the buckets a new rule may copy to, and the limits.

Each rule has its destination (dest_bucket_id, dest_bucket_name, dest_region), prefix, replicate_deletes, enabled and its status: copying while the objects the bucket held when the rule was made are copied, active, paused, or error when the last pass could not copy everything (last_failures, last_error). replicated_through is the time up to which every change has reached the destination, and lag_seconds how long ago that was; both are null until the first copy ends. objects_copied, bytes_copied and objects_deleted count since the rule was made.

destinations lists your buckets in other regions. Answers 404 for a service or bucket that is not this account's.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The source bucket's id

Responses

Section titled Add replication rule

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Add replication rule

POST /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/replication

Copy this bucket's objects into another of your buckets in another region, and keep copying. The first copy of what the bucket holds starts within five minutes; after it, new and changed objects are copied every five minutes, and once a day we check that the destination holds everything. With replicate_deletes, that daily check also removes from the destination what the source no longer holds under the prefix. Keys stay the same. Copies are free; the storage they take is billed as storage in the destination's service.

Answers the rule as GET lists it. Answers 404 for a service or bucket that is not this account's, 409 when the service is not active, when the bucket already has 10 rules or this one, when the destination copies into this bucket already (replication cannot run in a circle), or when another rule copies into the same keys of a destination that replicates deletes; 422 when the destination is in the same region; and 429 after 60 rule changes in an hour.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The source bucket's id

Request body

application/json (required)

Field	Type	Required	Description
`dest_bucket_id`	integer	yes	The bucket to copy into: one of your buckets in another region, from destinations
`prefix`	string	no	Copy only the keys that start with this. Empty copies the whole bucket
`replicate_deletes`	boolean	no	When true, the daily check also deletes from the destination the objects under the prefix that the source no longer holds

Responses

Section titled Change a rule's prefix, turn replicated deletes on or off, or pause and resume it

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Change a rule's prefix, turn replicated deletes on or off, or pause and resume it

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/replication/{rule_id}

Change a rule's prefix, turn replicated deletes on or off, or pause and resume it. Only the fields sent change. A new prefix runs the first copy again; a paused rule picks up the changes it missed when it starts again.

Answers the rule. Answers 404 for a rule that is not this account's, 409 when the service is not active or the change conflicts with another rule, and 429 after 60 rule changes in an hour.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The source bucket's id
`rule_id`	path	integer	yes	The rule's id, from the list

Request body

application/json (required)

Field	Type	Required	Description
`prefix`	string or null	no	A new prefix. The first copy runs again for it
`replicate_deletes`	boolean or null	no	Turn replicated deletes on or off
`enabled`	boolean or null	no	False pauses the rule; true starts it again from where it stopped

Responses

Section titled Remove a rule

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Remove a rule

DELETE /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/replication/{rule_id}

Remove a rule. Nothing more is copied; the objects it already copied stay in the destination. Works whatever the service's status.

Answers {"deleted": true, "id"}. Answers 404 for a rule that is not this account's and 429 after 60 rule changes in an hour.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The source bucket's id
`rule_id`	path	integer	yes	The rule's id, from the list

Responses

Section titled Turn versioning on for a bucket, or suspend it

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Turn versioning on for a bucket, or suspend it

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/versioning

Turn versioning on for a bucket, or suspend it.

While versioning is on, every overwrite and delete keeps the version it replaces, and those versions count toward the GB-months you are billed for. Suspending stops keeping new versions and keeps the ones the bucket holds. Versioning cannot be turned off once it is on, so off is not accepted. Answers 409 for suspended on a bucket with Object Lock, which keeps versioning on, and when the service is not active.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's id
`bucket_id`	path	integer	yes	The bucket's id, from the bucket list

Request body

application/json (required)

Field	Type	Required	Description
`status`	string, one of `enabled`, `suspended`	yes	`enabled` keeps every version of every object; `suspended` stops keeping new ones and keeps the versions the bucket holds. Versioning cannot be turned off once it is on

Responses

Section titled Serve the bucket as a static website on its public URL and custom domains

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type	Description
`bucket_id`	integer
`versioning`	string, one of `off`, `enabled`, `suspended`
`object_lock`	ObjectLockOut	A bucket's Object Lock and the default retention it gives new versions.
`object_lock.enabled`	boolean	Whether the bucket was created with Object Lock
`object_lock.mode`	string, one of `GOVERNANCE`, `COMPLIANCE` or null	The default retention's mode; null for no default retention
`object_lock.days`	integer or null	How long the default retention keeps each new version, in days
`object_lock.years`	integer or null	`days` in years, when it is a whole number of years

Serve the bucket as a static website on its public URL and custom domains

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/website

Serve the bucket as a static website on its public URL and custom domains.

With enabled, / and every path ending in / answer with the index document under that prefix (default index.html), and a path with no object whose <path>/<index> exists redirects to <path>/. A missing key answers with the error document and status 404, or, with spa, with the root index document and status 200, which is what a single page app needs. error and spa cannot both be set (422). Saving purges what the edge cached for the bucket.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes	The Object Storage service's ID.
`bucket_id`	path	integer	yes	The bucket's ID, from `GET /client/object-storage/{service_id}/buckets`.

Request body

application/json (required)

Field	Type	Required	Description
`enabled`	boolean	yes	True to answer `/` and paths ending in `/` with the index document.
`index`	string or null	no	The index document's key. Default `index.html`.
`error`	string or null	no	The error document's key, served with status 404.
`spa`	boolean	no	Answer every missing key with the index document and status 200.

Responses