Add a bucket

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

namestring required

Display name for the bucket

provider'aws_s3'

Object storage provider

bucketstring required

The bucket name

regionstring nullable

The bucket region

endpoint_urlstring nullable

Custom S3-compatible endpoint (omit for AWS)

prefixstring

Key prefix within the bucket

sse_kms_key_idstring nullable

KMS key id/ARN to encrypt writes with (SSE-KMS); omit for the bucket's default encryption

Response

The attached bucket details

idstring required

The ID of the bucket

created_atstring date-time required

Creation time

updated_atstring date-time required

Last update time

namestring required

Display name

provider'aws_s3' required

Object-storage provider backing a bring-your-own bucket.

bucketstring required

The bucket name

regionstring nullable required

The bucket region

endpoint_urlstring nullable required

Custom S3-compatible endpoint

prefixstring required

Key prefix within the bucket

sse_kms_key_idstring 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_arnstring nullable required

IAM role Mixedbread assumes (auth_type=assume_role); not a secret

external_idstring 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_atstring date-time nullable required

When the bucket was last validated

has_credentialsboolean required

Whether secret credentials are stored (always false for assume-role buckets)

credentials_versioninteger required

Increments on every credential rotation

object'bucket'

The type of the object

v4

Add a bucket

Request body

Response