Client API: Object Storage

Section titled The account's object storage services with their headline numbers

Status	Meaning
`200`	Success.

Fields of a 200 response:

Field	Type
`regions`	array of RegionOut
`regions[].id`	integer
`regions[].code`	string
`regions[].name`	string
`regions[].country_code`	string or null
`regions[].endpoint`	string

The account's object storage services with their headline numbers

GET /api/v1/client/object-storage/services

The account's object storage services with their headline numbers.

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

Responses

Section titled Get service

Status	Meaning
`200`	Success.

Fields of a 200 response:

Field	Type
`items`	array of ServiceItem
`items[].id`	integer
`items[].service_id`	integer
`items[].label`	string
`items[].hostname`	string or null
`items[].status`	string
`items[].product_name`	string or null
`items[].billing_cycle`	string or null
`items[].region`	string or null
`items[].location_id`	integer or null
`items[].namespace`	string
`items[].bucket_prefix`	string
`items[].quota_bytes`	integer or null
`items[].used_bytes`	integer
`items[].object_count`	integer
`items[].bucket_count`	integer
`items[].key_count`	integer
`items[].overage_per_gb_month`	number or null
`items[].created_at`	string or null
`items[].next_due_date`	string or null
`total`	integer

Get service

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

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

Parameters

Name	In	Type	Required
`service_id`	path	integer	yes

Responses

Section titled List buckets

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

Fields of a 200 response:

Field	Type
`id`	integer
`service_id`	integer
`label`	string
`hostname`	string or null
`status`	string
`product_name`	string or null
`billing_cycle`	string or null
`region`	string or null
`location_id`	integer or null
`namespace`	string
`bucket_prefix`	string
`quota_bytes`	integer or null
`used_bytes`	integer
`object_count`	integer
`bucket_count`	integer
`key_count`	integer
`overage_per_gb_month`	number or null
`created_at`	string or null
`next_due_date`	string or null
`endpoints`	array of EndpointOut
`endpoints[].region`	string
`endpoints[].endpoint`	string
`overage_gb`	number
`grace_days`	integer
`max_buckets`	integer
`presign_max_seconds`	integer

List buckets

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

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

Parameters

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
`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
`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.

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
`name`	string	yes
`location_id`	integer or null	no

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
`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

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
`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

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 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
`ok`	boolean
`bucket`	string
`region`	string or null
`objects_destroyed`	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 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
`deleted`	integer
`errors`	array of object

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.

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
`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

Responses

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

Fields of a 200 response:

Field	Type
`url`	string
`method`	string
`headers`	Headers
`expires_in`	integer
`expires_at`	string

List keys

Section titled List keys

GET /api/v1/client/object-storage/{service_id}/keys

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

Parameters

Name	In	Type	Required
`service_id`	path	integer	yes

Responses

Section titled Issue a key

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

Fields of a 200 response:

Field	Type
`items`	array of KeyOut
`items[].id`	integer
`items[].access_key_id`	string
`items[].label`	string
`items[].bucket_id`	integer or null
`items[].bucket_name`	string or null
`items[].scope`	string, one of `bucket`, `all`
`items[].mode`	string, one of `read`, `read_write`
`items[].actions`	array of string
`items[].is_active`	boolean
`items[].last_used_at`	string or null
`items[].created_at`	string or null
`total`	integer

Issue a key

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

Issue a key. The secret is in this response and nowhere else after.

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
`label`	string	yes
`bucket_id`	integer or null	no
`mode`	string, one of `read`, `read_write`	no

Responses

Section titled Revoke key

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

Fields of a 201 response:

Field	Type
`id`	integer
`access_key_id`	string
`label`	string
`bucket_id`	integer or null
`bucket_name`	string or null
`scope`	string, one of `bucket`, `all`
`mode`	string, one of `read`, `read_write`
`actions`	array of string
`is_active`	boolean
`last_used_at`	string or null
`created_at`	string or null
`secret_key`	string
`endpoint`	string or null
`region`	string or null
`activation_note`	string

Revoke key

DELETE /api/v1/client/object-storage/{service_id}/keys/{key_id}

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

Parameters

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

Responses

Section titled Stored bytes and objects over time, as the hourly meter recorded them

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

Fields of a 200 response:

Field	Type
`ok`	boolean
`access_key_id`	string

Stored bytes and objects over time, as the hourly meter recorded them

GET /api/v1/client/object-storage/{service_id}/usage

Stored bytes and objects over time, as the hourly meter recorded them.

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

Parameters

Name	In	Type	Required	Description
`service_id`	path	integer	yes
`days`	query	integer	no	Default: `30`.

Responses