Skip to main content
POST/storage/buckets/{bucketName}/objects

Upload Object

Uploads one object into the bucket as multipart/form-data.

Fields:

  • file (the bytes).
  • path (where the object goes in the bucket; it may contain slashes).
  • Optional contentType.
  • Optional upsert ("true" replaces an object already at that path).
  • Optional metadata, a flat JSON object of string values stored with the object.

Answers 201 with the stored object.

Needs upload rights on the bucket; in a custom bucket the bucket's storage policy decides, and replacing an existing object with upsert also needs the policy's delete grant.

The upload is audited as data.write.storage.object.created with the bucket, size and content type.

Parameters
bucketName *path

The bucket's name.

It is unique within the project.

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
file *string <binary>

The object's bytes.

Its part's content type is used when contentType is omitted.

path *string

Where the object goes in the bucket.

It may contain slashes to group objects under a prefix.

Example: "users/u_42/avatar.png"
contentTypestring

The object's MIME type.

Omitted, the file part's own content type is used.

The bucket's allowed MIME types apply to it.

Example: "image/png"
upsert"true" | "false"

true replaces an object already at path.

Omitted or any other value, an upload to a path that holds an object is refused.

Example: "true"
metadatastring

A JSON object of string values stored with the object, sent as JSON text.

Custom storage policies can read it as metadata.

Example: "{\"owner\":\"u_42\",\"source\":\"profile-page\"}"
Responses
HTTPK9O CodeDescription
201The object was written.
400K9O_INVALID_FIELD_VALUEThe object violates a bucket constraint (file-size limit, allowed MIME type, or metadata cap) or the metadata is malformed.
401K9O_UNAUTHENTICATEDAuthentication is required.
403K9O_RBAC_DENYThe caller's project role does not permit this object operation.
403K9O_ACCESS_DENIEDThe bucket's storage policy does not allow upload for this caller (context.reason storage_policy_denied). Checked after the role and IAM checks; a bucket with no policy is unaffected.
404K9O_BUCKET_NOT_FOUNDNo bucket with this name exists in the project.
409K9O_ALREADY_EXISTSAn object already exists at this path and upsert is false.
422K9O_MALWARE_DETECTEDThe uploaded object was quarantined by malware scanning and not stored.
Response body (201)
data *object

The stored object.

path *string

The object's path in the bucket, as sent.

Example: "users/u_42/avatar.png"
size *integer

The object's size in bytes.

Example: 48213
lastModified *string <date-time> | null

Null from the platform-managed and customer storage locations, which don't report a write time on upload.

meta *any

Request metadata: cost, timing and correlation ids.

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.from('<collection>').upload()

Showing example in TypeScript

Request example
{
  "file": "string",
  "path": "users/u_42/avatar.png",
  "contentType": "image/png",
  "upsert": "true",
  "metadata": "{\"owner\":\"u_42\",\"source\":\"profile-page\"}"
}
Response example (201)
{
  "data": {
    "path": "users/u_42/avatar.png",
    "size": 48213,
    "lastModified": null
  }
}

More in Storage & Schema