Create Bucket

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Authorization

string

required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings. REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

X-Namespace

string

required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace' REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Body

application/json

Request model for creating a new bucket.

REQUIRED: A bucket_schema must be defined to enable data processing and validation.

The bucket_schema tells the system what fields your objects will have, enabling:

Collections to map your data fields to feature extractors via input_mappings
Validation of object structure at upload time
Type-safe data pipelines from bucket → collection → retrieval

Every bucket must have a schema that defines the structure of objects it will contain.

bucket_name

string

required

Human-readable name for the bucket

bucket_schema

BucketSchema · object

required

Schema definition for objects in this bucket (REQUIRED). Defines the custom fields your objects will have (blob properties, metadata structure, etc.)

Show child attributes

bucket_schema.properties

Properties · object

required

Show child attributes

bucket_schema.properties.{key}

BucketSchemaField · object

Schema field definition for bucket objects.

Show child attributes

bucket_schema.properties.{key}.type

enum<string>

required

Supported data types for bucket schema fields.

Types fall into two categories:

Explicit Types (Type-Safe):
- Provide type guarantees for extractors
- User must pre-classify content
- Compatible with type-specific extractors
Automatic Type (Flexible):
- No type guarantee (runtime detection)
- User doesn't pre-classify content
- Only compatible with multimodal extractors

Available options:

string,

number,

integer,

float,

boolean,

object,

array,

date,

datetime,

json,

file,

text,

image,

audio,

video,

pdf,

document,

spreadsheet,

presentation,

dense_vector,

sparse_vector,

int8_vector,

automatic

bucket_schema.properties.{key}.default

unknown

bucket_schema.properties.{key}.items

unknown

bucket_schema.properties.{key}.properties

Properties · object

bucket_schema.properties.{key}.examples

any[] | null

OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible.

bucket_schema.properties.{key}.description

string | null

bucket_schema.properties.{key}.enum

any[] | null

bucket_schema.properties.{key}.required

boolean | null

default:false

description

string | null

Description of the bucket

unique_key

UniqueKeyConfig · object

Unique key configuration for this bucket (OPTIONAL). Enables uniqueness enforcement and upsert operations on specified field(s) from the schema. Cannot be changed after bucket creation.

Show child attributes

unique_key.fields

string[]

required

Field name(s) from bucket schema to use as unique constraint. REQUIRED - must provide at least one field name.

Single field example: ['video_id'] - Enforces uniqueness on video_id alone. Compound example: ['sensor_id', 'timestamp'] - Uniqueness requires BOTH fields to match.

All specified fields must:

Exist in the bucket schema
Be scalar types (string, integer, float, uuid - NOT objects or arrays)
Have non-null, non-empty values in all uploaded objects
Be 255 characters or less per string field value

Field order doesn't matter (sorted internally for consistency). ['timestamp', 'sensor_id'] is equivalent to ['sensor_id', 'timestamp'].

Minimum array length: 1

unique_key.default_policy

enum<string> | null

Default insertion policy for this bucket when not specified per request. OPTIONAL - if omitted, you must provide ?policy= parameter on each upload request.

Policies:

'insert': Create new object only. Fail with 409 Conflict if unique key already exists. Use when: You want to prevent accidental overwrites (safest option).
'update': Update existing object only. Fail with 404 Not Found if unique key doesn't exist. Use when: You only want to update existing records, never create new ones.
'upsert': Update if exists, create if not (idempotent operation). Use when: You want idempotent ingestion (re-running is safe).

Policy Resolution:

Request-level ?policy= parameter takes precedence (if provided)
Falls back to this default_policy (if configured)
Returns 400 Bad Request if neither is specified

Recommendation: Omit default_policy if you want explicit control on each upload. Set default_policy='upsert' for idempotent pipelines.

Available options:

insert,

update,

upsert

Example:

"insert"

Example:

{
  "default_policy": "upsert",
  "description": "Single field, upsert by default (idempotent video ingestion)",
  "fields": ["video_id"]
}

metadata

Metadata · object

Additional metadata for the bucket

Response

Successful Response

Response model for bucket operations.

bucket_name

string

required

Human-readable name for the bucket

object_count

integer

required

Number of objects in the bucket

total_size_bytes

integer

required

Total size of all objects in the bucket in bytes

bucket_id

string

Unique identifier for the bucket

description

string | null

Description of the bucket

bucket_schema

BucketSchema · object

Schema definition for objects in this bucket

Show child attributes

bucket_schema.properties

Properties · object

required

Show child attributes

bucket_schema.properties.{key}

BucketSchemaField · object

Schema field definition for bucket objects.

Show child attributes

bucket_schema.properties.{key}.type

enum<string>

required

Supported data types for bucket schema fields.

Types fall into two categories:

Explicit Types (Type-Safe):
- Provide type guarantees for extractors
- User must pre-classify content
- Compatible with type-specific extractors
Automatic Type (Flexible):
- No type guarantee (runtime detection)
- User doesn't pre-classify content
- Only compatible with multimodal extractors

Available options:

string,

number,

integer,

float,

boolean,

object,

array,

date,

datetime,

json,

file,

text,

image,

audio,

video,

pdf,

document,

spreadsheet,

presentation,

dense_vector,

sparse_vector,

int8_vector,

automatic

bucket_schema.properties.{key}.default

unknown

bucket_schema.properties.{key}.items

unknown

bucket_schema.properties.{key}.properties

Properties · object

bucket_schema.properties.{key}.examples

any[] | null

OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible.

bucket_schema.properties.{key}.description

string | null

bucket_schema.properties.{key}.enum

any[] | null

bucket_schema.properties.{key}.required

boolean | null

default:false

unique_key

UniqueKeyConfig · object

Unique key configuration for this bucket (if configured)

Show child attributes

unique_key.fields

string[]

required

Field name(s) from bucket schema to use as unique constraint. REQUIRED - must provide at least one field name.

Single field example: ['video_id'] - Enforces uniqueness on video_id alone. Compound example: ['sensor_id', 'timestamp'] - Uniqueness requires BOTH fields to match.

All specified fields must:

Exist in the bucket schema
Be scalar types (string, integer, float, uuid - NOT objects or arrays)
Have non-null, non-empty values in all uploaded objects
Be 255 characters or less per string field value

Field order doesn't matter (sorted internally for consistency). ['timestamp', 'sensor_id'] is equivalent to ['sensor_id', 'timestamp'].

Minimum array length: 1

unique_key.default_policy

enum<string> | null

Default insertion policy for this bucket when not specified per request. OPTIONAL - if omitted, you must provide ?policy= parameter on each upload request.

Policies:

'insert': Create new object only. Fail with 409 Conflict if unique key already exists. Use when: You want to prevent accidental overwrites (safest option).
'update': Update existing object only. Fail with 404 Not Found if unique key doesn't exist. Use when: You only want to update existing records, never create new ones.
'upsert': Update if exists, create if not (idempotent operation). Use when: You want idempotent ingestion (re-running is safe).

Policy Resolution:

Request-level ?policy= parameter takes precedence (if provided)
Falls back to this default_policy (if configured)
Returns 400 Bad Request if neither is specified

Recommendation: Omit default_policy if you want explicit control on each upload. Set default_policy='upsert' for idempotent pipelines.

Available options:

insert,

update,

upsert

Example:

"insert"

Example:

{
  "default_policy": "upsert",
  "description": "Single field, upsert by default (idempotent video ingestion)",
  "fields": ["video_id"]
}

metadata

Metadata · object

Additional metadata for the bucket

created_at

string<date-time> | null

When the bucket was created

updated_at

string<date-time> | null

Last modification time of bucket metadata

last_upload_at

string<date-time> | null

When the last object was uploaded to this bucket

status

enum<string>

default:ACTIVE

Bucket lifecycle status (ACTIVE, ARCHIVED, SUSPENDED, IN_PROGRESS for deleting)

Available options:

PENDING,

IN_PROGRESS,

PROCESSING,

COMPLETED,

COMPLETED_WITH_ERRORS,

FAILED,

CANCELED,

UNKNOWN,

SKIPPED,

DRAFT,

ACTIVE,

ARCHIVED,

SUSPENDED

is_locked

boolean

default:false

Whether the bucket is locked (read-only)

batch_stats

BatchStatistics · object

Batch statistics for this bucket (calculated asynchronously, stored in DB)

Show child attributes

batch_stats.total

integer

default:0

Total number of batches in this bucket

batch_stats.active

integer

default:0

Number of batches that are not completed (DRAFT, PENDING, IN_PROGRESS, PROCESSING)

batch_stats.completed

integer

default:0

Number of completed batches

batch_stats.failed

integer

default:0

Number of failed batches

storage_stats

StorageStatistics · object

Storage statistics for this bucket (calculated asynchronously, stored in DB)

Show child attributes

storage_stats.total_size_bytes

integer

default:0

Total size of all objects/blobs in the bucket in bytes

storage_stats.avg_size_bytes

integer

default:0

Average object size in bytes

storage_stats.max_size_bytes

integer

default:0

Size of the largest object in bytes

storage_stats.min_size_bytes

integer

default:0

Size of the smallest object in bytes

Health

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Analytics

Tasks

Webhooks

Authorizations

Headers

Body

Response