Buckets API

Create, list, resize, and delete object-storage buckets, rotate their keys, and attach a bucket to a container app.

Manage object-storage buckets over the API: create one, check its status and usage, resize its capacity, rotate its access keys, and reveal the show-once credentials. For the dashboard flow and product concepts (naming, capacity, versioning), see Basin.

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Human-friendly name; a DNS-safe slug is derived from it and used as the bucket's physical, tenant-scoped name (never exposed directly — see GET .../credentials).

display_name?string

Optional; defaults to the trimmed name when omitted.

quota_gb*integer

Booked capacity in GiB — the billable unit (object_storage rate).

versioning?boolean

Reserved for S3 object versioning on the bucket. The setting is stored and echoed back, but versioning enforcement on the physical bucket is not yet active — do not rely on it to protect against accidental overwrites or deletes yet.

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets" \  -H "Content-Type: application/json" \  -d '{    "name": "assets",    "quota_gb": 1  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "display_name": "string",
  "quota_gb": 0,
  "versioning": true,
  "used_bytes": 0,
  "object_count": 0,
  "status": "provisioning",
  "status_reason": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets"

{
  "buckets": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "name": "string",
      "display_name": "string",
      "quota_gb": 0,
      "versioning": true,
      "used_bytes": 0,
      "object_count": 0,
      "status": "provisioning",
      "status_reason": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "display_name": "string",
  "quota_gb": 0,
  "versioning": true,
  "used_bytes": 0,
  "object_count": 0,
  "status": "provisioning",
  "status_reason": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

quota_gb*integer

The new booked capacity in GiB.

versioning?boolean

When present, replaces the bucket's stored versioning setting. Omit to leave the current setting unchanged. Reserved: versioning enforcement on the physical bucket is not yet active (see Bucket.versioning).

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "quota_gb": 1  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "display_name": "string",
  "quota_gb": 0,
  "versioning": true,
  "used_bytes": 0,
  "object_count": 0,
  "status": "provisioning",
  "status_reason": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08/regenerate-keys"

{
  "status": "rotating",
  "generation": 0
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08/credentials"

{
  "status": "ready",
  "generation": 0,
  "access_key_id": "string",
  "secret_access_key": "string",
  "endpoint": "https://basin.alawadi.cloud",
  "bucket": "t3f2a1b2c-assets",
  "region": "me-central-1"
}

{
  "status": "provisioning"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Errors use a code and a message

Every failed request returns a JSON body of the shape { "code": "...", "message": "..." }. Codes you will see on these endpoints: 401 UNAUTHORIZED; 403 OBJECT_STORAGE_DISABLED (create only — object storage is not yet enabled on this account); 409 PROJECT_SUSPENDED (the project itself is suspended); 402 INSUFFICIENT_BALANCE or 403 ACCOUNT_SUSPENDED (your billing account has no funds, or is suspended) on create, and on a resize that grows the quota — a shrink is never billing-gated; 404 NOT_FOUND (a bucket you do not own reads as not found, never leaked); 409 INSUFFICIENT_CAPACITY on create or a resize that grows past what your account can book; and 410 ALREADY_REVEALED when GET .../credentials is called a second time for the same key generation.

Create, then poll for ready

POST .../buckets returns immediately with status: "provisioning" — the bucket and its S3 identity provision asynchronously. Poll GET .../buckets/{bucketId} until status is "running", then call GET .../buckets/{bucketId}/credentials to reveal the access key and secret key. That reveal is show-once: the plaintext secret is returned exactly one time per key generation, and every later call for the same generation returns 410 ALREADY_REVEALED. Call regenerate-keys to mint a new, revealable generation.

Browsing objects in the portal or via the API

The dashboard's file browser (and this API) lets you list, upload, download, and delete objects inside an already-"running" bucket without needing an S3 client.

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Query Parameters

prefix?string

Restrict the listing to keys under this prefix (default the bucket root).

cursor?string

Continuation token from a previous page's next_cursor.

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08/objects"

{
  "prefix": "string",
  "folders": [
    "images/",
    "docs/"
  ],
  "objects": [
    {
      "key": "docs/report.pdf",
      "size": 0,
      "last_modified": "2019-08-24T14:15:22Z"
    }
  ],
  "next_cursor": "string"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Empty

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

file*file

key*string

Full destination object key, e.g. docs/report.pdf.

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08/objects" \  -F file="string" \  -F key="string"

{
  "key": "string",
  "size": 0
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Empty

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Query Parameters

key*string

Full object key to delete.

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08/objects?key=string"

Empty

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Empty

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

bucketId*string

UUID of the bucket service.

Query Parameters

key*string

Full object key to download.

Response Body

`application/octet-stream`

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/buckets/497f6eca-6276-4993-bfeb-53cbbbba6f08/objects/content?key=string"

"string"

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Empty

GET .../objects lists one directory level at a time — folders are the "subdirectory" prefixes under prefix, objects are the plain files directly under it. Page through more than 200 entries with cursor. Uploads (POST .../objects, multipart/form-data with file and key fields) are capped at 100 MiB; larger files need an S3 client with your bucket's credentials instead (see Access keys) — a presigned-URL and multipart upload path for bigger files in the browser is on the roadmap. Downloads (GET .../objects/content?key=...) stream through the API. New codes on these four: 409 BUCKET_NOT_READY (the bucket has not finished provisioning yet); 413 OBJECT_TOO_LARGE (upload over 100 MiB); 400 BAD_KEY (an empty, absolute, or ..-traversal key); and 503 OBJECT_STORE_UNAVAILABLE (object storage misconfigured on this deployment).

Attach a bucket to an app

A bucket can be linked into a container app the same way a managed database is: the container receives the bucket's credentials as environment variables, wired via a secret reference, never as plaintext you have to copy and paste.

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

consumer_service_id*string

A generic container in the same project.

provider_service_id*string

The managed database or bucket to link in.

link_type*string

Must match the provider's service type: postgres, mysql, redis, or bucket (http links a plain container's URL instead).

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/service-links" \  -H "Content-Type: application/json" \  -d '{    "consumer_service_id": "23570cdd-ac17-47d2-bcbc-c7128eb2ba97",    "provider_service_id": "17062ceb-e6d9-456f-9abb-e8f6605cc7cc",    "link_type": "http"  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "consumer_service_id": "23570cdd-ac17-47d2-bcbc-c7128eb2ba97",
  "provider_service_id": "17062ceb-e6d9-456f-9abb-e8f6605cc7cc",
  "link_type": "http",
  "injected_env": {
    "property1": "string",
    "property2": "string"
  }
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Set provider_service_id to the bucket and link_type to bucket. The consumer container's environment gains:

Variable	Value
`AWS_ACCESS_KEY_ID`	The bucket's access key
`AWS_SECRET_ACCESS_KEY`	The bucket's secret key
`S3_ENDPOINT`	`https://basin.alawadi.cloud`
`S3_BUCKET`	The full, tenant-prefixed bucket name
`S3_REGION`	`me-central-1`

Buckets created before the region rename inject damm-1 here; it's a permanent alias for me-central-1, so linked apps keep working unchanged.

These variables point at the same S3-compatible endpoint the connect-an-app guide walks through by hand — a service link just wires them in for you instead of you copying values from the credentials reveal. If you rotate the bucket's keys with regenerate-keys, every app currently linked to it is restarted automatically so it picks up the new credentials.

Full reference: Basin overview · Access keys · Connect an app to object storage.

Buckets API

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

200application/json

401application/json

404application/json

200application/json

401application/json

404application/json

200application/json

400application/json

401application/json

404application/json

409application/json

204

401application/json

404application/json

202application/json

401application/json

404application/json

200application/json

202application/json

401application/json

404application/json

410application/json

200application/json

401application/json

403application/json

404application/json

409

503

201application/json

400application/json

401application/json

403application/json

404application/json

409

413

503

204

400application/json

401application/json

403application/json

404application/json

409

503

200application/octet-stream

400application/json

401application/json

403application/json

404application/json

409

503

201application/json

400application/json

401application/json

404application/json

409application/json

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/octet-stream`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`