> For the complete documentation index, see [llms.txt](https://docs.khotan.com/llms.txt). A markdown version of any page is available at its `index.md` URL. # Buckets `/api/v1` operations for buckets. See [HTTP API](/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.