Buckets

/api/v1 operations for buckets. See HTTP API for authentication, the error envelope, and rate limits.

Operations

GET /api/v1/buckets

List buckets

Returns the organization's non-deleted storage buckets. Responses never include a credential; issue one with the credentials operation.

Auth: API key required.

Operation ID: listBuckets

Responses:

• 200 — The organization's storage buckets.
• 401 — Authentication is missing or invalid.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan buckets list

POST /api/v1/buckets

Create a bucket

Provisions a Khotan-managed storage bucket synchronously and responds 201 with the persisted record whether setup ends ready or failed; branch on the returned status. A bucket is a private folder subtree in your organization's file storage, reached through the Files API with a scoped key. Supply an idempotencyKey to make retries safe — a retry carrying the same key returns the original bucket instead of creating a second one; without a key, every call creates a new bucket.

Auth: API key required.

Operation ID: createBucket

Request body (application/json, required):

• name (string, required)
• idempotencyKey (string, optional)

Responses:

• 201 — The persisted bucket record, ready or failed.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan buckets create

GET /api/v1/buckets/{bucketId}

Get a bucket

Returns one storage bucket's record, including status and failure state when present. Responses never include a credential; issue one with the credentials operation.

Auth: API key required.

Operation ID: getBucket

Path parameters:

• bucketId (string, required)

Responses:

• 200 — The bucket record.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan buckets get

DELETE /api/v1/buckets/{bucketId}

Delete a bucket

Empties the bucket's folder subtree (deleting its objects), revokes its scoped credentials, then soft-deletes the record — the same semantics as deleting from the dashboard. Deletion is permanent. Returns 403 resource_protected when the bucket has deletion protection enabled; protection can only be removed from the dashboard.

Auth: API key required.

Operation ID: deleteBucket

Path parameters:

• bucketId (string, required)

Responses:

• 200 — The storage was deleted.
• 401 — Authentication is missing or invalid.
• 403 — The storage is protected from deletion (code resource_protected). Remove protection from the dashboard before deleting via the API.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan buckets delete

PUT /api/v1/buckets/{bucketId}/tags

Set a bucket's tags

Replaces a bucket's tag list with the submitted list and returns the stored list. Tags are normalized to lowercase slugs, so Live is stored as live. Send an empty list to remove every tag. Requires an API key whose role is owner or developer.

Auth: API key required.

Operation ID: setBucketTags

Path parameters:

• bucketId (string, required)

Request body (application/json, required):

• tags (string[], required) — Full tag list; it replaces the stored list. Each tag is trimmed, lowercased, and has whitespace runs replaced with "-", and repeats are removed. After that, each tag is 1-32 lowercase letters, digits, or single hyphens, with at most 10 tags. Presets: test, live, uat, dev, demo, deprecated.

Responses:

• 200 — The stored tag list, after normalization.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan buckets tags set

POST /api/v1/buckets/{bucketId}/credentials

Issue bucket credentials

Issues a folder-scoped API key for the bucket and returns its secret once. The key acts only through the Files API and only within the bucket's folder subtree — send it as Authorization: Bearer against the Files API. Each call rotates the credential: any previously issued key for this bucket is revoked. The secret is shown once and is not retrievable afterward. The response filesApiBaseUrl already includes /api/v1 — append paths such as /files/... directly; do not append another /api/v1.

Auth: API key required.

Operation ID: issueBucketCredentials

Path parameters:

• bucketId (string, required)

Responses:

• 200 — The issued bucket credential (secret shown once).
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan buckets credentials

DELETE /api/v1/buckets/{bucketId}/credentials

Revoke bucket credentials

Revokes the bucket's live folder-scoped API key and clears the stored secret without minting a replacement. Subsequent Files API calls with the revoked key fail authentication. Issue a new key with POST /api/v1/buckets/{bucketId}/credentials when one is needed again.

Auth: API key required.

Operation ID: revokeBucketCredentials

Path parameters:

• bucketId (string, required)

Responses:

• 200 — The bucket credential was revoked.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.