Update Bucket

curl --request PUT \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '
{
  "bucket_name": "<string>",
  "description": "<string>",
  "metadata": {}
}
'

{
  "bucket_name": "<string>",
  "object_count": 123,
  "total_size_bytes": 123,
  "bucket_id": "<string>",
  "description": "<string>",
  "bucket_schema": {
    "properties": {}
  },
  "unique_key": {
    "default_policy": "upsert",
    "description": "Single field, upsert by default (idempotent video ingestion)",
    "fields": [
      "video_id"
    ]
  },
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "last_upload_at": "2023-11-07T05:31:56Z",
  "status": "ACTIVE",
  "is_locked": false,
  "batch_stats": {
    "total": 0,
    "active": 0,
    "completed": 0,
    "failed": 0
  },
  "storage_stats": {
    "total_size_bytes": 0,
    "avg_size_bytes": 0,
    "max_size_bytes": 0,
    "min_size_bytes": 0
  }
}

PUT

buckets

{bucket_identifier}

Update Bucket

curl --request PUT \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '
{
  "bucket_name": "<string>",
  "description": "<string>",
  "metadata": {}
}
'

{
  "bucket_name": "<string>",
  "object_count": 123,
  "total_size_bytes": 123,
  "bucket_id": "<string>",
  "description": "<string>",
  "bucket_schema": {
    "properties": {}
  },
  "unique_key": {
    "default_policy": "upsert",
    "description": "Single field, upsert by default (idempotent video ingestion)",
    "fields": [
      "video_id"
    ]
  },
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "last_upload_at": "2023-11-07T05:31:56Z",
  "status": "ACTIVE",
  "is_locked": false,
  "batch_stats": {
    "total": 0,
    "active": 0,
    "completed": 0,
    "failed": 0
  },
  "storage_stats": {
    "total_size_bytes": 0,
    "avg_size_bytes": 0,
    "max_size_bytes": 0,
    "min_size_bytes": 0
  }
}

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.

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'

Path Parameters

bucket_identifier

string

required

Body

application/json

Request model for updating an existing bucket.

bucket_name

string | null

Human-readable name for the bucket

description

string | null

Description of the bucket

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

Get Bucket List Buckets

⌘I

Health

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Analytics

Tasks

Webhooks

Update Bucket

Headers

Path Parameters

Body

Response