Buckets API

Use these endpoints to manage the buckets in your account. Every request goes to https://gateway.kuberns.cloud and carries your credential as HTTP Basic authentication. The headers, the response formats, and the access levels that every endpoint shares are described once in the API reference.

The examples read your credential from two environment variables. Set them first:

export KUBERNS_ACCESS_KEY_ID="KBS..."
export KUBERNS_SECRET="your-secret-access-key"

Create a bucket

POST /buckets

Creates a bucket in your account. It is ready to use as soon as the call returns.

Access: a read & write credential.

Parameters for "Create a bucket"

Headers

Name	Type	Required	Description
`Authorization`	string	Required	`Basic` followed by your credential. See Authentication.
`Content-Type`	string	Optional	Send `application/json`. The gateway does not check this header.

Body parameters

Name	Type	Required	Description
`name`	string	Required	The name shown in the dashboard. 3 to 40 characters: lowercase letters, numbers, and hyphens, starting and ending with a letter or number. Surrounding spaces are removed and capital letters are changed to lowercase. It must be different from the name of every other bucket you have.

HTTP status codes for "Create a bucket"

Status	When it happens
`201`	The bucket was created.
`400`	`name` is missing or not valid. The message is `Use 3-40 lowercase letters, numbers and hyphens.` This answer has the validation error format, not the usual one.
`400`	You already have a bucket with this name: `You already have a bucket with this name.`
`400`	You already have 50 buckets, the most you can have: `You can have at most 50 buckets.`
`400`	Your account is in a grace period because your storage balance is unpaid: `New uploads are paused because your storage balance is unpaid. Top up your credits to continue.`
`400`	This would be your first bucket and none of your services is running: `Run at least one service to create your first bucket.`
`400`	Storage could not create the bucket. Nothing was created, and you can try again: `Something went wrong. Please try again.`
`401`	The credential is missing or wrong: `Your credentials are missing or not valid.`
`403`	The credential is read-only: `This credential is read-only.`
`403`	Your account is on a free trial, and storage buckets are for paid plans: `Storage buckets are available on paid plans.` This answer has the validation error format, not the usual one.

Code samples for "Create a bucket"

Request example

cURL

curl -u "$KUBERNS_ACCESS_KEY_ID:$KUBERNS_SECRET" \
  -X POST https://gateway.kuberns.cloud/buckets \
  -H "Content-Type: application/json" \
  -d '{"name": "product-assets"}'

Python

import os
 
import requests
 
response = requests.post(
    "https://gateway.kuberns.cloud/buckets",
    auth=(os.environ["KUBERNS_ACCESS_KEY_ID"], os.environ["KUBERNS_SECRET"]),
    json={"name": "product-assets"},
)
response.raise_for_status()
 
print(response.json()["data"]["bucket"])

JavaScript

const credentials = Buffer.from(
  `${process.env.KUBERNS_ACCESS_KEY_ID}:${process.env.KUBERNS_SECRET}`
).toString("base64");
 
const response = await fetch("https://gateway.kuberns.cloud/buckets", {
  method: "POST",
  headers: {
    Authorization: `Basic ${credentials}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "product-assets" }),
});
const body = await response.json();
 
console.log(body.data.bucket);

Response

201 Created

Response

{
  "message": "Bucket created successfully.",
  "status": 201,
  "data": {
    "bucket": "kb-product-assets-3f9a1c2b7d4e",
    "public_id": "05f8ebb3-5e3d-494f-b251-4ef2937f49c9",
    "name": "product-assets",
    "aws_region": "ap-south-1",
    "status": "ACTIVE",
    "status_message": null,
    "size_bytes": 0,
    "object_count": 0,
    "usage_synced_at": "2026-10-17T07:54:12.778541Z",
    "created_at": "2026-10-17T07:54:09.901564Z"
  }
}

Note: Save data.bucket. It is the bucket identifier, and every other request names a bucket by it. It is not the same as name: the identifier ends with a random suffix that keeps it unique.

Response fields for "Create a bucket"

Field	Type	Description
`message`	string	A short sentence describing the result.
`status`	integer	The HTTP status code, repeated in the body.
`data`	object	The bucket that was created.
`data.bucket`	string	The bucket identifier. Use it in every other request.
`data.public_id`	string	The ID that appears in this bucket's address in the dashboard. It is not used in API requests.
`data.name`	string	The name you chose, as the dashboard shows it.
`data.aws_region`	string	The region where the files are stored, for example `ap-south-1` (Mumbai).
`data.status`	string	`ACTIVE` when the bucket is ready to use. Can be one of: `CREATING`, `ACTIVE`, `DELETING`, `FAILED`.
`data.status_message`	string or null	The reason, when the bucket is not `ACTIVE`. `null` otherwise.
`data.size_bytes`	integer	The total size of the files in the bucket, in bytes. Refreshed from time to time, so it can lag a recent upload.
`data.object_count`	integer	The number of files in the bucket. Refreshed together with `size_bytes`.
`data.usage_synced_at`	string or null	When `size_bytes` and `object_count` were last refreshed, as an ISO 8601 time in UTC.
`data.created_at`	string	When the bucket was created, as an ISO 8601 time in UTC.

List buckets

GET /buckets

Returns the buckets you own, newest first, with a summary of your storage. One answer holds up to 50 buckets by default, which is the most buckets you can have, so you get all of them at once unless you ask for smaller pages with limit.

Access: a read-only or read & write credential.

Parameters for "List buckets"

Headers

Name	Type	Required	Description
`Authorization`	string	Required	`Basic` followed by your credential. See Authentication.

Query parameters

Name	Type	Required	Description
`limit`	integer	Optional	The most buckets to return in one answer. Default: `50`. The most is `100`: a larger number is lowered to `100`. A value that is not a whole number, or is less than `1`, is ignored and the default is used.
`page`	string	Optional	The `data.next_page` of the previous answer, to get the next page. It is not a page number. Send it exactly as you received it. Leave it out for the first page. See Pagination.

HTTP status codes for "List buckets"

Status	When it happens
`200`	The buckets are returned. When you have none, `data.buckets` is an empty array.
`400`	`page` is not valid: `That page is not valid. Use the next_page value from the previous response.` This answer has the refusal format described in Response formats.
`401`	The credential is missing or wrong: `Your credentials are missing or not valid.`
`403`	Your account is on a free trial, and storage buckets are for paid plans: `Storage buckets are available on paid plans.` This answer has the validation error format, not the usual one.

Code samples for "List buckets"

Request example

cURL

curl -G -u "$KUBERNS_ACCESS_KEY_ID:$KUBERNS_SECRET" \
  https://gateway.kuberns.cloud/buckets \
  --data-urlencode "limit=1"

Python

import os
 
import requests
 
response = requests.get(
    "https://gateway.kuberns.cloud/buckets",
    auth=(os.environ["KUBERNS_ACCESS_KEY_ID"], os.environ["KUBERNS_SECRET"]),
    params={"limit": 1},
)
response.raise_for_status()
data = response.json()["data"]
 
for bucket in data["buckets"]:
    print(bucket["name"], bucket["bucket"])
 
print("has_next:", data["has_next"])
print("next_page:", data["next_page"])

JavaScript

const credentials = Buffer.from(
  `${process.env.KUBERNS_ACCESS_KEY_ID}:${process.env.KUBERNS_SECRET}`
).toString("base64");
 
const params = new URLSearchParams({ limit: "1" });
const response = await fetch(`https://gateway.kuberns.cloud/buckets?${params}`, {
  headers: { Authorization: `Basic ${credentials}` },
});
if (!response.ok) {
  throw new Error(`List buckets failed with status ${response.status}`);
}
const { data } = await response.json();
 
for (const bucket of data.buckets) {
  console.log(bucket.name, bucket.bucket);
}
 
console.log("has_next:", data.has_next);
console.log("next_page:", data.next_page);

These samples ask for 1 bucket at a time, so that the paging keys show up in the answer. Leave limit out to get up to 50 buckets at once, which is more than you can have.

Response

200 OK

Response

{
  "message": "Buckets fetched successfully.",
  "status": 200,
  "data": {
    "buckets": [
      {
        "bucket": "kb-product-assets-3f9a1c2b7d4e",
        "public_id": "05f8ebb3-5e3d-494f-b251-4ef2937f49c9",
        "name": "product-assets",
        "aws_region": "ap-south-1",
        "status": "ACTIVE",
        "status_message": null,
        "size_bytes": 5242880,
        "object_count": 12,
        "usage_synced_at": "2026-10-17T07:54:12.778541Z",
        "created_at": "2026-10-17T07:54:09.901564Z"
      }
    ],
    "summary": {
      "used_bytes": 5242880,
      "limit_bytes": null,
      "bucket_count": 2,
      "bucket_limit": 50,
      "max_object_size_bytes": 1073741824,
      "create_blocked_reason": null
    },
    "has_next": true,
    "next_page": "MjAyNi0xMC0xN1QwNzo1NDowOS45MDE1NjQrMDA6MDB8MDVmOGViYjMtNWUzZC00OTRmLWIyNTEtNGVmMjkzN2Y0OWM5"
  }
}

Note: This is the first of two pages. You have 2 buckets and the request asked for 1, newest first. data.has_next is true, so there is more, and data.next_page is what you send to get it. data.summary always describes all your buckets, not only the ones on this page.

Warning: size_bytes, object_count, and summary.used_bytes are refreshed from time to time, so they can lag a recent upload or delete. List files always shows the current files.

The paging keys

Key	Where	Example	What it means
`limit`	In your request	`1`	How many buckets you want on this page. Default: `50`. The most is `100`.
`page`	In your request	The `data.next_page` of the previous answer	Which page to return. Leave it out for the first page. It is not a page number.
`data.has_next`	In the answer	`true`	`true` when there is another page after this one. `false` on the last page.
`data.next_page`	In the answer	`"MjAyNi0xMC0x..."`	What to send as `page` to get the next page. `null` on the last page.

Get the next page

Send data.next_page back as page, with the same limit. These samples ask for the first page and then for the second. The cURL sample needs jq.

cURL

FIRST=$(curl -s -G -u "$KUBERNS_ACCESS_KEY_ID:$KUBERNS_SECRET" \
  https://gateway.kuberns.cloud/buckets \
  --data-urlencode "limit=1")
PAGE=$(echo "$FIRST" | jq -r '.data.next_page')
 
curl -G -u "$KUBERNS_ACCESS_KEY_ID:$KUBERNS_SECRET" \
  https://gateway.kuberns.cloud/buckets \
  --data-urlencode "limit=1" \
  --data-urlencode "page=$PAGE"

Python

import os
 
import requests
 
 
def list_page(page=None):
    params = {"limit": 1}
    if page:
        params["page"] = page
 
    response = requests.get(
        "https://gateway.kuberns.cloud/buckets",
        auth=(os.environ["KUBERNS_ACCESS_KEY_ID"], os.environ["KUBERNS_SECRET"]),
        params=params,
    )
    response.raise_for_status()
    return response.json()["data"]
 
 
first = list_page()
second = list_page(first["next_page"])
 
for bucket in second["buckets"]:
    print(bucket["name"], bucket["bucket"])
 
print("has_next:", second["has_next"])

JavaScript

const credentials = Buffer.from(
  `${process.env.KUBERNS_ACCESS_KEY_ID}:${process.env.KUBERNS_SECRET}`
).toString("base64");
 
async function listPage(page) {
  const params = new URLSearchParams({ limit: "1" });
  if (page) {
    params.set("page", page);
  }
 
  const response = await fetch(`https://gateway.kuberns.cloud/buckets?${params}`, {
    headers: { Authorization: `Basic ${credentials}` },
  });
  if (!response.ok) {
    throw new Error(`List buckets failed with status ${response.status}`);
  }
  return (await response.json()).data;
}
 
const first = await listPage();
const second = await listPage(first.next_page);
 
for (const bucket of second.buckets) {
  console.log(bucket.name, bucket.bucket);
}
 
console.log("has_next:", second.has_next);

The second answer has the older bucket. data.has_next is false and data.next_page is null, so this was the last page:

{
  "message": "Buckets fetched successfully.",
  "status": 200,
  "data": {
    "buckets": [
      {
        "bucket": "kb-new-bucket-db7b807736f1",
        "public_id": "ccf3fd3e-b915-435a-8d20-bfd6dcf15b77",
        "name": "new-bucket",
        "aws_region": "ap-south-1",
        "status": "ACTIVE",
        "status_message": null,
        "size_bytes": 0,
        "object_count": 0,
        "usage_synced_at": "2026-10-17T06:46:54.211668Z",
        "created_at": "2026-10-17T06:46:51.309842Z"
      }
    ],
    "summary": {
      "used_bytes": 5242880,
      "limit_bytes": null,
      "bucket_count": 2,
      "bucket_limit": 50,
      "max_object_size_bytes": 1073741824,
      "create_blocked_reason": null
    },
    "has_next": false,
    "next_page": null
  }
}

These samples assume the first answer has data.has_next set to true. To handle any number of pages, use the loop below. See Pagination for more.

Read every page

These samples read every page and print the name and identifier of every bucket. The cURL sample needs jq.

cURL

PAGE=""
 
while true; do
  ANSWER=$(curl -s -G -u "$KUBERNS_ACCESS_KEY_ID:$KUBERNS_SECRET" \
    https://gateway.kuberns.cloud/buckets \
    --data-urlencode "limit=100" \
    --data-urlencode "page=$PAGE")
 
  echo "$ANSWER" | jq -r '.data.buckets[] | "\(.name) \(.bucket)"'
 
  [ "$(echo "$ANSWER" | jq -r '.data.has_next')" = "true" ] || break
  PAGE=$(echo "$ANSWER" | jq -r '.data.next_page')
done

Python

import os
 
import requests
 
page = None
 
while True:
    params = {"limit": 100}
    if page:
        params["page"] = page
 
    response = requests.get(
        "https://gateway.kuberns.cloud/buckets",
        auth=(os.environ["KUBERNS_ACCESS_KEY_ID"], os.environ["KUBERNS_SECRET"]),
        params=params,
    )
    response.raise_for_status()
    data = response.json()["data"]
 
    for bucket in data["buckets"]:
        print(bucket["name"], bucket["bucket"])
 
    if not data["has_next"]:
        break
    page = data["next_page"]

JavaScript

const credentials = Buffer.from(
  `${process.env.KUBERNS_ACCESS_KEY_ID}:${process.env.KUBERNS_SECRET}`
).toString("base64");
 
let page = null;
 
while (true) {
  const params = new URLSearchParams({ limit: "100" });
  if (page) {
    params.set("page", page);
  }
 
  const response = await fetch(`https://gateway.kuberns.cloud/buckets?${params}`, {
    headers: { Authorization: `Basic ${credentials}` },
  });
  if (!response.ok) {
    throw new Error(`List buckets failed with status ${response.status}`);
  }
  const { data } = await response.json();
 
  for (const bucket of data.buckets) {
    console.log(bucket.name, bucket.bucket);
  }
 
  if (!data.has_next) break;
  page = data.next_page;
}

Response fields for "List buckets"

Field	Type	Description
`message`	string	A short sentence describing the result.
`status`	integer	The HTTP status code, repeated in the body.
`data`	object	Your buckets and a summary of your storage.
`data.buckets`	array of objects	The buckets on this page, newest first. Empty when you have none. It includes buckets whose `status` is not `ACTIVE`.
`data.buckets[].bucket`	string	The bucket identifier. Use it in every other request.
`data.buckets[].public_id`	string	The ID that appears in this bucket's address in the dashboard. It is not used in API requests.
`data.buckets[].name`	string	The name you chose, as the dashboard shows it.
`data.buckets[].aws_region`	string	The region where the files are stored, for example `ap-south-1` (Mumbai).
`data.buckets[].status`	string	`ACTIVE` when the bucket is ready to use. Can be one of: `CREATING`, `ACTIVE`, `DELETING`, `FAILED`.
`data.buckets[].status_message`	string or null	The reason, when the bucket is not `ACTIVE`. `null` otherwise.
`data.buckets[].size_bytes`	integer	The total size of the files in the bucket, in bytes. Refreshed from time to time, so it can lag a recent upload.
`data.buckets[].object_count`	integer	The number of files in the bucket. Refreshed together with `size_bytes`.
`data.buckets[].usage_synced_at`	string or null	When `size_bytes` and `object_count` were last refreshed, as an ISO 8601 time in UTC.
`data.buckets[].created_at`	string	When the bucket was created, as an ISO 8601 time in UTC.
`data.summary`	object	A summary of your storage across all your buckets.
`data.summary.used_bytes`	integer	The total size of the files in all your buckets, in bytes. It is the sum of each bucket's `size_bytes`, so it can lag too.
`data.summary.limit_bytes`	integer or null	The most storage you can use, in bytes. It is `null`, because there is no cap on total storage.
`data.summary.bucket_count`	integer	The number of buckets you have.
`data.summary.bucket_limit`	integer	The most buckets you can have.
`data.summary.max_object_size_bytes`	integer	The largest file the dashboard accepts, in bytes.
`data.summary.create_blocked_reason`	string or null	`null` when you can create a bucket. Otherwise the reason you cannot. Can be one of: `New uploads are paused because your storage balance is unpaid. Top up your credits to continue.`, `Run at least one service to create your first bucket.` It does not look at the bucket limit: when `bucket_count` equals `bucket_limit`, creating a bucket fails even if this is `null`.
`data.has_next`	boolean	`true` when there is another page of buckets after this one. `false` on the last page.
`data.next_page`	string or null	Send it as `page` to get the next page. `null` on the last page.

Get a bucket

GET /buckets/{bucket}

Returns one bucket you own, with its status and size.

Access: a read-only or read & write credential.

Parameters for "Get a bucket"

Headers

Name	Type	Required	Description
`Authorization`	string	Required	`Basic` followed by your credential. See Authentication.

Path parameters

Name	Type	Required	Description
`bucket`	string	Required	The bucket identifier: the `data.bucket` value that Create a bucket and List buckets return, for example `kb-product-assets-3f9a1c2b7d4e`. It is not the bucket's name. See The bucket identifier.

HTTP status codes for "Get a bucket"

Status	When it happens
`200`	The bucket is returned.
`401`	The credential is missing or wrong: `Your credentials are missing or not valid.`
`403`	Your account is on a free trial, and storage buckets are for paid plans: `Storage buckets are available on paid plans.` This answer has the validation error format, not the usual one.
`404`	No bucket with this identifier exists in your account. It may be mistyped, deleted, or another account's: `Bucket not found.`

Code samples for "Get a bucket"

Request example

cURL

BUCKET="kb-product-assets-3f9a1c2b7d4e"
 
curl -u "$KUBERNS_ACCESS_KEY_ID:$KUBERNS_SECRET" \
  "https://gateway.kuberns.cloud/buckets/$BUCKET"

Python

import os
 
import requests
 
BUCKET = "kb-product-assets-3f9a1c2b7d4e"
 
response = requests.get(
    f"https://gateway.kuberns.cloud/buckets/{BUCKET}",
    auth=(os.environ["KUBERNS_ACCESS_KEY_ID"], os.environ["KUBERNS_SECRET"]),
)
response.raise_for_status()
 
data = response.json()["data"]
print(data["bucket"], data["status"], data["size_bytes"])

JavaScript

const BUCKET = "kb-product-assets-3f9a1c2b7d4e";
 
const credentials = Buffer.from(
  `${process.env.KUBERNS_ACCESS_KEY_ID}:${process.env.KUBERNS_SECRET}`
).toString("base64");
 
const response = await fetch(`https://gateway.kuberns.cloud/buckets/${BUCKET}`, {
  headers: { Authorization: `Basic ${credentials}` },
});
const body = await response.json();
 
console.log(body.data.bucket, body.data.status, body.data.size_bytes);

Response

200 OK

Response

{
  "message": "Bucket fetched successfully.",
  "status": 200,
  "data": {
    "bucket": "kb-product-assets-3f9a1c2b7d4e",
    "public_id": "05f8ebb3-5e3d-494f-b251-4ef2937f49c9",
    "name": "product-assets",
    "aws_region": "ap-south-1",
    "status": "ACTIVE",
    "status_message": null,
    "size_bytes": 5242880,
    "object_count": 12,
    "usage_synced_at": "2026-10-17T07:54:12.778541Z",
    "created_at": "2026-10-17T07:54:09.901564Z"
  }
}

Response fields for "Get a bucket"

Field	Type	Description
`message`	string	A short sentence describing the result.
`status`	integer	The HTTP status code, repeated in the body.
`data`	object	The bucket.
`data.bucket`	string	The bucket identifier. Use it in every other request.
`data.public_id`	string	The ID that appears in this bucket's address in the dashboard. It is not used in API requests.
`data.name`	string	The name you chose, as the dashboard shows it.
`data.aws_region`	string	The region where the files are stored, for example `ap-south-1` (Mumbai).
`data.status`	string	`ACTIVE` when the bucket is ready to use. Can be one of: `CREATING`, `ACTIVE`, `DELETING`, `FAILED`.
`data.status_message`	string or null	The reason, when the bucket is not `ACTIVE`. `null` otherwise.
`data.size_bytes`	integer	The total size of the files in the bucket, in bytes. Refreshed from time to time, so it can lag a recent upload.
`data.object_count`	integer	The number of files in the bucket. Refreshed together with `size_bytes`.
`data.usage_synced_at`	string or null	When `size_bytes` and `object_count` were last refreshed, as an ISO 8601 time in UTC.
`data.created_at`	string	When the bucket was created, as an ISO 8601 time in UTC.

Delete a bucket

DELETE /buckets/{bucket}

Permanently deletes a bucket and every file in it. The request waits until the deletion is finished, so a bucket with many files takes longer.

Access: a read & write credential.

Warning: This deletes the bucket and every file in it for good. There is no way to restore them. Download anything you need to keep first.

Note: A public file is served from a copy kept at the edge of the content delivery network, for up to about a day. After you delete a bucket, the permanent link of a public file in it can keep opening for that long, even though the file is gone.

Parameters for "Delete a bucket"

Headers

Name	Type	Required	Description
`Authorization`	string	Required	`Basic` followed by your credential. See Authentication.

Path parameters

Name	Type	Required	Description
`bucket`	string	Required	The bucket identifier: the `data.bucket` value that Create a bucket and List buckets return, for example `kb-product-assets-3f9a1c2b7d4e`. It is not the bucket's name. See The bucket identifier.

HTTP status codes for "Delete a bucket"

Status	When it happens
`200`	The bucket and all its files were deleted.
`400`	Storage could not finish the deletion: `Something went wrong. Please try again.` The bucket's `status` is now `DELETING`, and some of its files may already be gone. Send the request again to finish.
`401`	The credential is missing or wrong: `Your credentials are missing or not valid.`
`403`	The credential is read-only: `This credential is read-only.`
`403`	Your account is on a free trial, and storage buckets are for paid plans: `Storage buckets are available on paid plans.` This answer has the validation error format, not the usual one.
`404`	No bucket with this identifier exists in your account. It may be mistyped, already deleted, or another account's: `Bucket not found.`
`502`	The deletion took longer than 15 seconds, or the Kuberns API could not be reached: `Could not reach the platform.` The deletion may or may not have finished. Call Get a bucket: `404` means the bucket is gone, and otherwise send the delete again.

Code samples for "Delete a bucket"

Request example

cURL

BUCKET="kb-product-assets-3f9a1c2b7d4e"
 
curl -u "$KUBERNS_ACCESS_KEY_ID:$KUBERNS_SECRET" \
  -X DELETE "https://gateway.kuberns.cloud/buckets/$BUCKET"

Python

import os
 
import requests
 
BUCKET = "kb-product-assets-3f9a1c2b7d4e"
 
response = requests.delete(
    f"https://gateway.kuberns.cloud/buckets/{BUCKET}",
    auth=(os.environ["KUBERNS_ACCESS_KEY_ID"], os.environ["KUBERNS_SECRET"]),
)
response.raise_for_status()
 
print(response.json()["message"])

JavaScript

const BUCKET = "kb-product-assets-3f9a1c2b7d4e";
 
const credentials = Buffer.from(
  `${process.env.KUBERNS_ACCESS_KEY_ID}:${process.env.KUBERNS_SECRET}`
).toString("base64");
 
const response = await fetch(`https://gateway.kuberns.cloud/buckets/${BUCKET}`, {
  method: "DELETE",
  headers: { Authorization: `Basic ${credentials}` },
});
const body = await response.json();
 
console.log(body.message);

Response

200 OK

Response

{
  "message": "Bucket deleted successfully.",
  "status": 200,
  "data": {}
}

Note: The path must start with /buckets/. A DELETE to /kb-product-assets-3f9a1c2b7d4e on its own answers 403 with Buckets are managed from the Kuberns dashboard, not through this endpoint., and deletes nothing.

Response fields for "Delete a bucket"

Field	Type	Description
`message`	string	A short sentence describing the result.
`status`	integer	The HTTP status code, repeated in the body.
`data`	object	Always empty (`{}`).

Create a folder

POST /buckets/{bucket}/folders

Creates an empty folder in a bucket, so that it shows in the dashboard and in List files before it has any files. Creating a folder first is optional: uploading to reports/2026/summary.pdf creates the folders on its own.

Access: a read & write credential.

Parameters for "Create a folder"

Headers

Name	Type	Required	Description
`Authorization`	string	Required	`Basic` followed by your credential. See Authentication.
`Content-Type`	string	Optional	Send `application/json`. The gateway does not check this header.

Path parameters

Name	Type	Required	Description
`bucket`	string	Required	The bucket identifier: the `data.bucket` value that Create a bucket and List buckets return, for example `kb-product-assets-3f9a1c2b7d4e`. It is not the bucket's name. See The bucket identifier.

Body parameters

Name	Type	Required	Description
`folder_path`	string	Required	The folder to create, for example `invoices` or `reports/2026`. Separate levels with a single `/`. Up to 900 characters. Spaces at the start and end are removed, and so are any `/` at the start. A `/` at the end is optional. Not allowed: an empty path, `//`, a level named `.` or `..`, a backslash (`\`), and control characters such as a tab or a new line.

HTTP status codes for "Create a folder"

Status	When it happens
`201`	The folder was created.
`400`	`folder_path` is missing: `This field is required.` This answer has the validation error format, not the usual one.
`400`	`folder_path` is empty: `This field may not be blank.` This answer has the validation error format, not the usual one.
`400`	`folder_path` is longer than 900 characters: `Ensure this field has no more than 900 characters.` This answer has the validation error format, not the usual one.
`400`	`folder_path` breaks another rule in the parameter description: `That file path is not allowed.`
`400`	Your account is in a grace period because your storage balance is unpaid: `New uploads are paused because your storage balance is unpaid. Top up your credits to continue.`
`400`	Storage could not create the folder. Nothing was created, and you can try again: `Something went wrong. Please try again.`
`401`	The credential is missing or wrong: `Your credentials are missing or not valid.`
`403`	The credential is read-only: `This credential is read-only.`
`403`	Your account is on a free trial, and storage buckets are for paid plans: `Storage buckets are available on paid plans.` This answer has the validation error format, not the usual one.
`404`	No bucket with this identifier exists in your account. It may be mistyped, deleted, or another account's: `Bucket not found.`

Code samples for "Create a folder"

Request example

cURL

BUCKET="kb-product-assets-3f9a1c2b7d4e"
 
curl -u "$KUBERNS_ACCESS_KEY_ID:$KUBERNS_SECRET" \
  -X POST "https://gateway.kuberns.cloud/buckets/$BUCKET/folders" \
  -H "Content-Type: application/json" \
  -d '{"folder_path": "invoices"}'

Python

import os
 
import requests
 
BUCKET = "kb-product-assets-3f9a1c2b7d4e"
 
response = requests.post(
    f"https://gateway.kuberns.cloud/buckets/{BUCKET}/folders",
    auth=(os.environ["KUBERNS_ACCESS_KEY_ID"], os.environ["KUBERNS_SECRET"]),
    json={"folder_path": "invoices"},
)
response.raise_for_status()
 
print(response.json()["message"])

JavaScript

const BUCKET = "kb-product-assets-3f9a1c2b7d4e";
 
const credentials = Buffer.from(
  `${process.env.KUBERNS_ACCESS_KEY_ID}:${process.env.KUBERNS_SECRET}`
).toString("base64");
 
const response = await fetch(
  `https://gateway.kuberns.cloud/buckets/${BUCKET}/folders`,
  {
    method: "POST",
    headers: {
      Authorization: `Basic ${credentials}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ folder_path: "invoices" }),
  }
);
const body = await response.json();
 
console.log(body.message);

Response

201 Created

Response

{
  "message": "Folder invoices/ created successfully.",
  "status": 201,
  "data": {}
}

Note: The message, and List files, write the folder with a / at the end: invoices/.

Response fields for "Create a folder"

Field	Type	Description
`message`	string	A short sentence naming the folder that was created. The folder's name ends with `/`.
`status`	integer	The HTTP status code, repeated in the body.
`data`	object	Always empty (`{}`).