Skip to main content
POST/storage/buckets

Create Bucket

Creates a bucket in the project.

Requires PROJECT_ADMIN.

mode is the bucket's access preset:

  • private (default): authenticated access by role tier and the IAM buckets:<verb> ceiling.
  • public: private's rules, plus anonymous read of objects at GET /@{projectSlug}/storage/public/{bucketName}/{path}. That path answers 302 to a short-lived presigned URL and is rate limited per client IP (429 K9O_RATE_LIMITED). Never anonymous list, upload or delete.
  • custom: the bucket's storage policy, policy.buckets.<bucket> declared in a migration, decides each object action for every caller, PROJECT_ADMIN included. An action the policy does not grant is denied. Managing the bucket and authoring its policy never go through it, so an admin can always change the policy or switch the mode back.

Setting or changing the mode is its own IAM action, buckets:set_mode (PROJECT_ADMIN by default; a buckets:update widening does not include it), and is audited (data.write.storage.bucket.mode_changed). public needs confirmPublic: true; custom needs the bucket to have a storage policy already.

The legacy public boolean is an alias of mode (true = public, false = private) under the same rules.

Responses carry both, with public derived from mode.

Parameters
projectSlug *path

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

It is unique within the org.

Request body
name *string

The bucket name, unique in the project: 3 to 63 lowercase letters, digits and hyphens, not starting or ending with a hyphen.

The k9o- prefix is reserved.

mode"private" | "public" | "custom"

Who can reach the bucket's objects.

Default private. public lets anyone read objects without signing in and needs confirmPublic: true. custom hands the decision to the bucket's storage policy, which must already exist.

confirmPublicboolean

Must be true to create a public bucket.

publicboolean

Older form of mode: true is public, false is private.

Send mode instead; the two must agree when both are sent.

fileSizeLimitinteger

The largest object an upload may write, in bytes.

Omit it for no bucket limit.

allowedMimeTypesany

MIME types an upload may have, at most 64.

An empty array or null allows any type.

One of: string[]
or: null
versioningboolean

Keep earlier versions of an object when it is overwritten.

Default false.

deleteAfterDaysinteger

Delete objects this many days after they were last uploaded (an overwrite starts the count again).

From that point the object reads as not found, and it is removed from the bucket within a few hours.

Only objects uploaded through the platform are deleted: an object written straight into a customer storage location, or uploaded before per-object records began, is kept.

Nothing is deleted while the project is under a legal hold.

On a customer storage location, setting it first tests that the platform can write and delete there.

Omit it to keep objects until deleted.

byosBindingIdstring

The storage location (byos_...) to keep the bucket's objects in.

Omit it for platform-managed storage.

Responses
HTTPK9O CodeDescription
201Created
400K9O_INVALID_FIELD_VALUEAn invalid field: for mode, confirmPublic is missing for a public bucket (reason confirm_public_required), a custom bucket has no storage policy yet (custom_mode_requires_policy), or mode and the legacy public flag disagree (mode_public_conflict).
403K9O_ACCESS_DENIEDThe caller does not have permission to create storage buckets for this project.
403K9O_IAM_POLICY_DENIEDThe bound IAM policy ceiling denies buckets:set_mode: setting or changing a bucket's mode is its own action, PROJECT_ADMIN-only by default; a policy that widens buckets:update does not widen it.
409K9O_ALREADY_EXISTSA bucket with this name already exists in the project.
409K9O_STATE_CONFLICTTurning on deleteAfterDays for a bucket on a customer storage location needs the platform to write and delete there, and the test failed (reason location_write_check_failed or location_delete_check_failed). Nothing was changed.
Response body (201)
data *object

A storage bucket and its settings.

name *string

The bucket name, unique in the project.

mode *"private" | "public" | "custom"

Who can reach the bucket's objects. private: project roles and IAM policies only. public: as private, plus anyone may read (not list, write or delete) objects without signing in. custom: the bucket's storage policy decides; the bucket must already have one.

public *boolean

True when mode is public.

Derived from mode.

fileSizeLimit *any

The largest object an upload may write, in bytes; null when the bucket sets no limit.

One of: integer
or: null
allowedMimeTypes *string[]

MIME types an upload may have.

Empty means any type.

versioning *boolean

Whether earlier versions of an overwritten object are kept.

deleteAfterDays *any

Objects are deleted this many days after they were last uploaded: from that point they read as not found, and they are removed from the bucket within a few hours.

Null keeps them until deleted.

Only objects uploaded through the platform are deleted: one written straight into a customer storage location, or uploaded before per-object records began, is kept.

One of: integer
or: null
createdAt *string <date-time>

When the bucket was created.

updatedAt *string <date-time>

When the bucket's settings last changed.

system *boolean

True for a bucket the platform creates and writes (k9o-audit-anchors, k9o-extension-assets).

A system bucket can't be deleted, its objects can't be written or deleted through the API, and only its storage location can change.

byosBindingId *any

The storage location (byos_...) the bucket's objects are kept in; null for platform-managed storage.

One of: string
or: null
meta *any

Request metadata: cost, timing and correlation ids.

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.storage.createBucket({
  name: 'My Resource',
  public: true,
  fileSizeLimit: 0,
  allowedMimeTypes: ['string']
})

Showing example in TypeScript

Request example
{
  "name": "My Resource",
  "public": true,
  "fileSizeLimit": 0,
  "allowedMimeTypes": [
    "string"
  ]
}
Response example (201)
{
  "data": {
    "name": "string",
    "mode": "private",
    "public": false,
    "fileSizeLimit": 0,
    "allowedMimeTypes": [
      "string"
    ],
    "versioning": false,
    "deleteAfterDays": 0,
    "createdAt": "string",
    "updatedAt": "string",
    "system": false,
    "byosBindingId": "string"
  }
}

More in Storage & Schema