---
title: "Add a bucket"
method: POST
path: "/v1/buckets"
tags: ["buckets"]
---

# Add a bucket

`POST /v1/buckets`

Attach a customer-owned storage bucket to the organization.

Access is validated against the bucket (reachability + write/delete probe) before
anything is stored, so an unreachable or unwritable bucket is rejected here.
With `assume_role` credentials (recommended for AWS) the probe performs the actual
STS AssumeRole and nothing secret is persisted — only the role ARN and the
organization's external ID. With `access_key` credentials (S3-compatible
endpoints) the keys are encrypted before they are stored.

Args:
    params: The bucket connection details and credentials.

Returns:
    Bucket: The attached bucket. Credentials are never returned.

## Request body

- BucketCreateParams — Parameters for attaching a customer-owned bucket.
  - `name` string, required — Display name for the bucket
  - `provider` 'aws_s3' — Object storage provider
  - `bucket` string, required — The bucket name
  - `region` string, nullable — The bucket region
  - `endpoint_url` string, nullable — Custom S3-compatible endpoint (omit for AWS)
  - `prefix` string — Key prefix within the bucket
  - `sse_kms_key_id` string, nullable — KMS key id/ARN to encrypt writes with (SSE-KMS); omit for the bucket's default encryption
  - `credentials` union, required — How Mixedbread authenticates against the bucket. `assume_role` is the recommended default for AWS; `access_key` is for S3-compatible providers with a custom endpoint.
    - BucketAssumeRoleCredentials — Cross-account IAM role the platform assumes via STS (recommended for AWS). Nothing secret is stored: the role ARN and the server-generated external id are plain metadata, and access is granted/revoked entirely through the role's trust policy in the customer's account.
      - `type` 'assume_role'
      - `role_arn` string, required — ARN of the IAM role Mixedbread assumes
    - BucketAccessKeyCredentials — AWS-style access key credentials for a customer bucket (write-only, never returned).
      - `type` 'access_key'
      - `access_key_id` string, required — Access key id
      - `secret_access_key` string, required — Secret access key

## Response `201`

The attached bucket details

- Bucket — Service-level representation of a bucket. Credentials are never returned.
  - `id` string, required — The ID of the bucket
  - `created_at` string, date-time, required — Creation time
  - `updated_at` string, date-time, required — Last update time
  - `name` string, required — Display name
  - `provider` 'aws_s3', required — Object-storage provider backing a bring-your-own bucket.
  - `bucket` string, required — The bucket name
  - `region` string, nullable, required — The bucket region
  - `endpoint_url` string, nullable, required — Custom S3-compatible endpoint
  - `prefix` string, required — Key prefix within the bucket
  - `sse_kms_key_id` string, nullable, required — KMS key id/ARN used to encrypt writes (SSE-KMS)
  - `auth_type` 'assume_role' | 'access_key', required — How omni authenticates against a customer bucket. ASSUME_ROLE is the recommended default for AWS: nothing secret is stored, every service assumes the customer's IAM role via STS on use. ACCESS_KEY remains for S3-compatible providers that have no STS.
  - `role_arn` string, nullable, required — IAM role Mixedbread assumes (auth_type=assume_role); not a secret
  - `external_id` string, nullable, required — sts:ExternalId the role's trust policy must require (auth_type=assume_role); not a secret
  - `status` 'pending' | 'active' | 'error', required — Validation lifecycle of a customer bucket.
  - `last_validated_at` string, date-time, nullable, required — When the bucket was last validated
  - `has_credentials` boolean, required — Whether secret credentials are stored (always false for assume-role buckets)
  - `credentials_version` integer, required — Increments on every credential rotation
  - `object` 'bucket' — The type of the object

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/mixedbread/apis/mxbai-omni.md) · [All operations](https://skmtc.net/mixedbread/apis/mxbai-omni/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixedbread/mxbai-omni/revisions/ff7d87258f32/schema)