Use buckets from your application

Your application talks to buckets over plain HTTPS. Any HTTP client works, and there is no SDK to install.

The API is not S3-compatible, so the AWS SDKs and S3 tools such as aws s3 do not work with it. Use the requests described in this section.

Before you start

1. Create a bucket in the dashboard. See Create and manage buckets.
2. Create a credential and keep the access key ID and the secret.
3. Put them in environment variables on your server:

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

The address

Every request goes to one address, the same for every account:

https://gateway.kuberns.cloud

Authenticate

Send the credential with HTTP Basic authentication. The access key ID is the username and the secret is the password:

Authorization: Basic base64(<access key ID>:<secret access key>)

Most HTTP clients do this for you. With cURL it is the -u option.

A missing or wrong credential gets 401 Unauthorized. A credential that is valid but not allowed to do what you asked, for example a read-only credential trying to upload, gets 403 Forbidden.

Make your first request

List your buckets:

curl -u "$KUBERNS_ACCESS_KEY_ID:$KUBERNS_SECRET" https://gateway.kuberns.cloud/buckets

A successful answer is JSON with your buckets under data.buckets. Each one has a bucket field, which is the identifier you use in every other request:

{
  "message": "Buckets fetched successfully.",
  "status": 200,
  "data": {
    "buckets": [
      {
        "bucket": "kb-product-assets-3f9a1c2b7d4e",
        "name": "product-assets",
        "status": "ACTIVE",
        "size_bytes": 5242880,
        "object_count": 12
      }
    ]
  }
}

The bucket identifier

In the dashboard a bucket has a name, such as product-assets. In the API you use the identifier, such as kb-product-assets-3f9a1c2b7d4e. It is returned as bucket when you create a bucket or list your buckets. Store it in your configuration rather than looking it up on every request.

Upload, download, and list

Upload a file. The path after the bucket is the file's name, and slashes make folders:

curl -u "$KUBERNS_ACCESS_KEY_ID:$KUBERNS_SECRET" \
  -X PUT "https://gateway.kuberns.cloud/kb-product-assets-3f9a1c2b7d4e/reports/2026/summary.pdf" \
  -H "Content-Type: application/pdf" \
  --data-binary @summary.pdf

Download it:

curl -u "$KUBERNS_ACCESS_KEY_ID:$KUBERNS_SECRET" \
  "https://gateway.kuberns.cloud/kb-product-assets-3f9a1c2b7d4e/reports/2026/summary.pdf" \
  -o summary.pdf

List what is in a bucket:

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

See the API reference for every endpoint, and Code examples for ready-made Python and JavaScript clients.

Two kinds of endpoints

File names

A file's name, also called its key, can be up to 900 characters. Slashes make folders, and a leading slash is ignored. A name cannot contain .. as a path segment, a double slash, a backslash, or control characters. URL-encode names that contain spaces or other special characters. The code examples do this for you.

Uploads

• Send the file as the request body, with a Content-Length. Every normal HTTP client does this for bytes and files.
• Send a Content-Type so the file is served with the right type. It is stored with the file and returned on download.
• Uploading to a name that already exists replaces the file, and the new file is private.
• A single upload request can be up to 5 GB.

Listing and pages

Listing returns at most 100 entries a page by default, and up to 1,000 with limit. When there are more, the answer includes a next_token. Send it back as token to get the next page, and stop when next_token is null. See List files.

Calling from a browser

Keep the credential on your server. If your web page needs to show a private file, have your server ask for a temporary link and hand that link to the page. For a file that everyone should see, make it public and use its permanent link.

When something goes wrong

Check the HTTP status first. See Errors and troubleshooting for each status and what to do.