# Client API: Object Storage

> S3-compatible buckets, access keys, objects and usage for Object Storage services.

Source: https://www.coritan.com/docs/api/reference/client/object-storage/

S3-compatible buckets, access keys, objects and usage for Object Storage services.

Base URL: `https://api.coritan.com/api/v1`. Paths below are complete.

To try these requests in the browser, open the [interactive Client API reference](https://api.coritan.com/docs).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/object-storage/regions`](#op-get-api-v1-client-object-storage-regions) | Regions with a gateway to put a bucket in, with each one's endpoint |
| GET | [`/api/v1/client/object-storage/services`](#op-get-api-v1-client-object-storage-services) | The account's object storage services with their headline numbers |
| GET | [`/api/v1/client/object-storage/{service_id}`](#op-get-api-v1-client-object-storage-service-id) | Get service |
| GET | [`/api/v1/client/object-storage/{service_id}/buckets`](#op-get-api-v1-client-object-storage-service-id-buckets) | List buckets |
| POST | [`/api/v1/client/object-storage/{service_id}/buckets`](#op-post-api-v1-client-object-storage-service-id-buckets) | Make a bucket in the chosen region, or the service's home region |
| GET | [`/api/v1/client/object-storage/{service_id}/buckets/{bucket_id}`](#op-get-api-v1-client-object-storage-service-id-buckets-bucket-id) | Get bucket |
| DELETE | [`/api/v1/client/object-storage/{service_id}/buckets/{bucket_id}`](#op-delete-api-v1-client-object-storage-service-id-buckets-bucket-id) | Remove a bucket |
| GET | [`/api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects`](#op-get-api-v1-client-object-storage-service-id-buckets-bucket-id-objects) | One page of the bucket under prefix, folders first |
| DELETE | [`/api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects`](#op-delete-api-v1-client-object-storage-service-id-buckets-bucket-id-objects) | Delete named objects |
| POST | [`/api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects/presign`](#op-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 |
| GET | [`/api/v1/client/object-storage/{service_id}/keys`](#op-get-api-v1-client-object-storage-service-id-keys) | List keys |
| POST | [`/api/v1/client/object-storage/{service_id}/keys`](#op-post-api-v1-client-object-storage-service-id-keys) | Issue a key |
| DELETE | [`/api/v1/client/object-storage/{service_id}/keys/{key_id}`](#op-delete-api-v1-client-object-storage-service-id-keys-key-id) | Revoke key |
| GET | [`/api/v1/client/object-storage/{service_id}/usage`](#op-get-api-v1-client-object-storage-service-id-usage) | Stored bytes and objects over time, as the hourly meter recorded them |

### Regions with a gateway to put a bucket in, with each one's endpoint {#op-get-api-v1-client-object-storage-regions}

`GET /api/v1/client/object-storage/regions`

Regions with a gateway to put a bucket in, with each one's endpoint.

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

#### Responses

| 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 {#op-get-api-v1-client-object-storage-services}

`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

| 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 {#op-get-api-v1-client-object-storage-service-id}

`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

| 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 {#op-get-api-v1-client-object-storage-service-id-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

| 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 {#op-post-api-v1-client-object-storage-service-id-buckets}

`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

| 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 {#op-get-api-v1-client-object-storage-service-id-buckets-bucket-id}

`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

| 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 {#op-delete-api-v1-client-object-storage-service-id-buckets-bucket-id}

`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

| 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 {#op-get-api-v1-client-object-storage-service-id-buckets-bucket-id-objects}

`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

| 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 {#op-delete-api-v1-client-object-storage-service-id-buckets-bucket-id-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

| 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 {#op-post-api-v1-client-object-storage-service-id-buckets-bucket-id-objects-presign}

`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 {#op-get-api-v1-client-object-storage-service-id-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

| 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 {#op-post-api-v1-client-object-storage-service-id-keys}

`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

| 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 {#op-delete-api-v1-client-object-storage-service-id-keys-key-id}

`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

| 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 {#op-get-api-v1-client-object-storage-service-id-usage}

`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

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `quota_bytes` | integer or null |
| `used_bytes` | integer |
| `object_count` | integer |
| `bucket_count` | integer |
| `overage_gb` | number |
| `days` | integer |
| `series` | array of UsagePoint |
| `series[].measured_at` | string |
| `series[].bytes` | integer |
| `series[].objects` | integer |