Organization API: Customer Portal: Object storage
The 5 Organization API operations for object storage.
Part of Customer Portal.
Operations
Section titled Operations| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/orgs/{org_slug}/portal/object-storage/regions |
The regions where a bucket can be made, with each region's S3 endpoint |
| GET | /api/v1/orgs/{org_slug}/portal/object-storage/services |
List services |
| GET | /api/v1/orgs/{org_slug}/portal/object-storage/{service_id} |
One service with its endpoints and its limits |
| GET | /api/v1/orgs/{org_slug}/portal/object-storage/{service_id}/requests |
Requests to the service per day, for the last days days |
| GET | /api/v1/orgs/{org_slug}/portal/object-storage/{service_id}/usage |
Stored bytes and objects over time, as we measured them each hour |
The regions where a bucket can be made, with each region's S3 endpoint
Section titled The regions where a bucket can be made, with each region's S3 endpointGET /api/v1/orgs/{org_slug}/portal/object-storage/regions
The regions where a bucket can be made, with each region's S3 endpoint.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
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 |
List services
Section titled List servicesGET /api/v1/orgs/{org_slug}/portal/object-storage/services
The Object Storage services the organization sold to the signed-in customer, newest first, with their headline numbers.
Services that ended are left out. service_id is the ID every other route on
this page takes. bucket_prefix is what the customer's bucket names start
with, such as c42-. rates holds the organization's own prices, in currency, and free
the amounts each customer gets free every month.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
Responses
Section titled Responses| 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 PortalServiceItem | |
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 | How often the organization bills this service |
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 | When the organization bills this service next |
items[].billing_model |
string, one of payg, fixed |
payg: billed each month for use above the account's free amounts. fixed: a plan with included storage that is no longer sold |
items[].rates |
PortalRatesOut or null | What the organization charges for this service. Our own prices are what we charge the organization, so the portal never shows them. Null only when the prices cannot be read |
items[].org_service_id |
integer | The service's ID in the organization's own service list, which the billing routes take, such as changing a plan or cancelling. Every other route on this page takes service_id |
items[].currency |
string or null | The currency of rates, such as USD |
items[].free |
PortalFreeOut or null | The free amounts each customer gets every calendar month |
total |
integer |
One service with its endpoints and its limits
Section titled One service with its endpoints and its limitsGET /api/v1/orgs/{org_slug}/portal/object-storage/{service_id}
One service with its endpoints and its limits.
endpoints lists the S3 endpoint of each region the service has a bucket
in, and of its home region. max_buckets is the most buckets one service
can hold, presign_max_seconds the longest a presigned URL can last, and
grace_days how long we keep a deleted bucket's objects after its service
ends. Billing is pay as you go: quota_bytes is null and overage_gb is
0. Answers 404 for a service that is not this customer's Object Storage.
Parameters
Section titled Parameters| Name | In | Type | Required | Description |
|---|---|---|---|---|
service_id |
path | integer | yes | The Object Storage service's ID, from the service list |
org_slug |
path | string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Fields of a 200 response:
| Field | Type | Description |
|---|---|---|
id |
integer | |
service_id |
integer | |
label |
string | |
hostname |
string or null | |
status |
string | |
product_name |
string or null | |
billing_cycle |
string or null | How often the organization bills this service |
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 | When the organization bills this service next |
billing_model |
string, one of payg, fixed |
payg: billed each month for use above the account's free amounts. fixed: a plan with included storage that is no longer sold |
rates |
PortalRatesOut or null | What the organization charges for this service. Our own prices are what we charge the organization, so the portal never shows them. Null only when the prices cannot be read |
rates.storage_gb_month |
string | Per GB stored for a month |
rates.class_a_million |
string | Per million Class A operations |
rates.class_b_million |
string | Per million Class B operations |
rates.egress_gb |
string | Per GB downloaded |
org_service_id |
integer | The service's ID in the organization's own service list, which the billing routes take, such as changing a plan or cancelling. Every other route on this page takes service_id |
currency |
string or null | The currency of rates, such as USD |
free |
PortalFreeOut or null | The free amounts each customer gets every calendar month |
free.storage_gb_month |
string | Free GB-months of storage, as text |
free.class_a |
integer | Free Class A operations |
free.class_b |
integer | Free Class B operations |
endpoints |
array of EndpointOut | |
endpoints[].region |
string | |
endpoints[].endpoint |
string | |
endpoints[].virtual_hosted |
boolean | True when buckets in this region also answer at their own hostname, <bucket>.<endpoint host>. The endpoint has no port in a region that also answers on port 443. |
overage_gb |
number | |
grace_days |
integer | |
max_buckets |
integer | |
presign_max_seconds |
integer |
Requests to the service per day, for the last days days
Section titled Requests to the service per day, for the last days daysGET /api/v1/orgs/{org_slug}/portal/object-storage/{service_id}/requests
Requests to the service per day, for the last days days.
One entry per UTC day, oldest first and ending today, and totals adds
them up. Each entry counts Class A, Class B and free operations, and the
bytes uploaded and downloaded. Every bucket of the service counts, deleted
ones too, and so do requests that name no bucket, such as listing the
buckets. A day with no requests has zeros. Requests made with a presigned
URL count. Requests refused for their signature or permissions, throttled
requests and failed requests do not. The requests of the last hour or so
are not in the counts yet.
Answers 404 for a service that is not this customer's Object Storage and
422 when days is outside 1 to 90.
Parameters
Section titled Parameters| Name | In | Type | Required | Description |
|---|---|---|---|---|
service_id |
path | integer | yes | The Object Storage service's ID, from the service list |
org_slug |
path | string | yes | |
days |
query | integer | no | How many days to return, ending today (UTC): 1 to 90 Default: 30. |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Fields of a 200 response:
| Field | Type | Description |
|---|---|---|
days |
integer | |
series |
array of RequestDay | One entry per day, oldest first, ending today |
series[].date |
string | The UTC day, YYYY-MM-DD |
series[].class_a |
integer | |
series[].class_b |
integer | |
series[].free |
integer | |
series[].bytes_in |
integer | |
series[].bytes_out |
integer | |
totals |
RequestTotals | |
totals.class_a |
integer | Class A operations, such as uploads and listings |
totals.class_b |
integer | Class B operations, such as downloads and HEAD requests |
totals.free |
integer | Free operations: deletes and CORS preflights |
totals.bytes_in |
integer | Bytes uploaded |
totals.bytes_out |
integer | Bytes downloaded |
Stored bytes and objects over time, as we measured them each hour
Section titled Stored bytes and objects over time, as we measured them each hourGET /api/v1/orgs/{org_slug}/portal/object-storage/{service_id}/usage
Stored bytes and objects over time, as we measured them each hour.
series has one point for each measurement. Answers 404 for a service
that is not this customer's Object Storage.
Parameters
Section titled Parameters| Name | In | Type | Required | Description |
|---|---|---|---|---|
service_id |
path | integer | yes | The Object Storage service's ID, from the service list |
org_slug |
path | string | yes | |
days |
query | integer | no | How many days of history to return, 1 to 366 Default: 30. |
Responses
Section titled 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 |