BucktDocs

Upload file

PUT/v1/buckets/{bucketId}/files/{path}files:writeSDK: files.upload

Streams a single file into a bucket. The path after /files/ becomes the object key — /files/images/logo.png writes to images/logo.png and serves from https://<bucket-domain>/images/logo.png. Uploads to the same path overwrite the existing object.

The response includes the public CDN url so you don't need a follow-up Get file call.

Path parameters

NameTypeDefaultDescription
bucketIdrequiredstring—The destination bucket's ID.
pathrequiredstring—Object key, including any subdirectories (e.g. `images/logo.png`). Becomes the URL path under your custom domain.

Headers

NameTypeDefaultDescription
Content-Typestring"application/octet-stream"MIME type stored on the object. Used when serving the file and when enforcing the bucket's allowedMimeTypes.
X-Buckt-Optimization"none" | "light" | "balanced" | "maximum"—Override the bucket's `optimizationMode` for this upload. Anything other than `none` requires a paid plan.

Request body

The raw file bytes. There's no JSON wrapper — send the file as the request body directly.

Example request

import { Buckt } from "@buckt/sdk";
import { readFile } from "node:fs/promises";

const client = new Buckt({ apiKey: process.env.BUCKT_API_KEY });

const buffer = await readFile("logo.png");
const file = await client.files.upload(
  "bkt_01H8XYZABCDEFGHJKMNPQRSTVW",
  "images/logo.png",
  buffer,
  "image/png",
  { optimization: "balanced" }
);

Responses

{
  "data": {
    "object": "file",
    "id": "images/logo.png",
    "key": "images/logo.png",
    "size": 24531,
    "contentType": "image/png",
    "lastModified": "2026-04-25T11:30:00Z",
    "url": "https://<custom-domain>/images/logo.png"
  },
  "error": null,
  "meta": null
}