Update Object

curl --request PUT \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/{object_identifier} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '
{
  "key_prefix": "<string>",
  "blobs": [
    {
      "property": "<string>",
      "type": "string",
      "key_prefix": "campaigns/summer_2025",
      "data": "https://example.com/video.mp4",
      "upload_id": "upl_abc123def456",
      "metadata": {},
      "canonicalize_source": true,
      "force_remirror": true
    }
  ],
  "metadata": {},
  "skip_duplicates": true
}
'

{
  "bucket_id": "<string>",
  "object_id": "<string>",
  "key_prefix": "<string>",
  "content_hash": "<string>",
  "blobs": [
    {
      "property": "<string>",
      "type": "string",
      "blob_id": "<string>",
      "key_prefix": "/videos/video.mp4",
      "properties": {},
      "details": {
        "filename": "<string>",
        "size_bytes": 123,
        "mime_type": "<string>",
        "hash": "<string>",
        "s3_object_key": "<string>"
      }
    }
  ],
  "source_details": [
    {
      "type": "bucket",
      "source_id": "<string>"
    }
  ],
  "status": "DRAFT",
  "error": "Failed to process object: Object not found",
  "skip_duplicates": false,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

PUT

buckets

{bucket_identifier}

objects

{object_identifier}

Update Object

curl --request PUT \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/{object_identifier} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '
{
  "key_prefix": "<string>",
  "blobs": [
    {
      "property": "<string>",
      "type": "string",
      "key_prefix": "campaigns/summer_2025",
      "data": "https://example.com/video.mp4",
      "upload_id": "upl_abc123def456",
      "metadata": {},
      "canonicalize_source": true,
      "force_remirror": true
    }
  ],
  "metadata": {},
  "skip_duplicates": true
}
'

{
  "bucket_id": "<string>",
  "object_id": "<string>",
  "key_prefix": "<string>",
  "content_hash": "<string>",
  "blobs": [
    {
      "property": "<string>",
      "type": "string",
      "blob_id": "<string>",
      "key_prefix": "/videos/video.mp4",
      "properties": {},
      "details": {
        "filename": "<string>",
        "size_bytes": 123,
        "mime_type": "<string>",
        "hash": "<string>",
        "s3_object_key": "<string>"
      }
    }
  ],
  "source_details": [
    {
      "type": "bucket",
      "source_id": "<string>"
    }
  ],
  "status": "DRAFT",
  "error": "Failed to process object: Object not found",
  "skip_duplicates": false,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

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

The unique identifier of the bucket.

object_identifier

string

required

The unique identifier of the object.

Body

application/json

Request model for updating an existing bucket object.

key_prefix

string | null

Updated storage key/path prefix of the object, this will be used to retrieve the object from the storage. It's at the root of the object.

blobs

CreateBlobRequest · object[] | null

List of new or updated blobs for this object

Show child attributes

blobs.property

string

required

REQUIRED. Property name from the bucket schema that this blob belongs to. Must match a field defined in the bucket's schema. Used to validate blob type compatibility and determine storage path. Common values: 'video', 'thumbnail', 'transcript', 'document', 'image'

Required string length: 1 - 100

blobs.type

enum<string>

required

REQUIRED. The schema field type for this blob. Must match the bucket schema definition for the property. Determines validation rules and processing pipeline. Common types: IMAGE, VIDEO, AUDIO, PDF, DOCUMENT, TEXT

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

blobs.key_prefix

string | null

OPTIONAL. Storage path prefix for organizing blobs within the bucket. If not provided, uses default bucket organization. Use for: grouping blobs by campaign, date, category, etc. Example: 'campaigns/summer_2025' or 'products/electronics'

Example:

"campaigns/summer_2025"

blobs.data

EITHER data OR upload_id must be provided (mutually exclusive).

File data in one of several INTERCHANGEABLE formats:

Format 1: URL String (HTTP/HTTPS/S3) - Direct URL to file on the web or in S3 - Examples: 'https://example.com/video.mp4', 's3://bucket/key' - Use for: Public files, existing S3 objects, pre-signed URLs - File is downloaded and uploaded to internal S3 (if canonicalize_source=True)

Format 2: Data URI String (base64) - Self-contained base64 data with MIME type - Format: 'data:<mime_type>;base64,<encoded_data>' - Example: 'data:image/jpeg;base64,/9j/4AAQSkZJRg...' - Use for: Small files (<5MB), mobile uploads, inline test data - MIME type automatically extracted from URI - Data is decoded, validated, and uploaded to S3 automatically

Format 3: Base64 Dictionary - Structured format with explicit metadata - Required keys: 'base64' (encoded data) - Optional keys: 'mime_type', 'filename' - Example: {'base64': '/9j/4AAQ...', 'mime_type': 'image/jpeg', 'filename': 'photo.jpg'} - Use for: When you need explicit MIME type control - Data is decoded, validated, and uploaded to S3 automatically

Format 4: URL Dictionary - Structured format for URL references - Required keys: 'url' - Example: {'url': 'https://example.com/file.jpg'} - Use for: Consistency with other dict formats

Processing: All formats are converted to internal S3 URLs before storage. The engine always receives S3 URLs regardless of input format.

Size Limits (Base64 only): Base64 data: 5MB (free), 10MB (pro), 50MB (enterprise). URLs: No limit (downloaded on-demand). For files exceeding limits, use presigned upload workflow: POST /buckets/{id}/uploads

Validation: - Base64: Encoding validated, MIME type detected, size checked - URLs: Accessibility verified, content-type validated - All: Schema type compatibility enforced

Required string length: 1 - 2083

Example:

"https://example.com/video.mp4"

blobs.upload_id

string | null

EITHER upload_id OR data must be provided. Reference to an existing upload from the presigned URL workflow.

⚠️ PRESIGNED URLS: Use existing POST /buckets/{id}/uploads endpoint! It already handles presigned URL generation, upload tracking, and validation. DO NOT create a new /presigned-upload endpoint - it's redundant.

Workflow: 1. POST /buckets/{id}/uploads → {upload_id, presigned_url} 2. User uploads file to presigned_url 3. POST /uploads/{upload_id}/confirm → Validates upload 4. Use upload_id here to reference the uploaded file

The upload must be in CONFIRMED or ACTIVE status. Format: 'upl_' prefix followed by alphanumeric characters.

Use Cases: - Combine multiple uploads into one object - Upload files in parallel, create object later - Reuse same upload across multiple objects

See: api/buckets/uploads/ for the complete upload system

Example:

"upl_abc123def456"

blobs.metadata

Metadata · object

Metadata for the blob, this will only be applied to the documents that use this blob

blobs.canonicalize_source

boolean | null

If set, override object-level default to control source canonicalization for this blob.

blobs.force_remirror

boolean | null

If set, override object-level default to force re-upload even if an identical blob exists.

metadata

Metadata · object

Updated metadata for the object, this will be merged with existing metadata.

skip_duplicates

boolean | null

Skip duplicate blobs, if a blob with the same hash already exists, it will be skipped.

Response

Successful Response

Response model for bucket objects.

bucket_id

string

required

ID of the bucket this object belongs to

object_id

string

Unique identifier for the object

key_prefix

string | null

Storage key/path of the object, this will be used to retrieve the object from the storage. It is similar to a file path. If not provided, it will be placed in the root of the bucket.

content_hash

string | null

SHA256 hash of the object's content, used for de-duplication.

blobs

BlobModel · object[]

List of blobs contained in this object

Show child attributes

blobs.property

string

required

Property name of the blob

blobs.type

enum<string>

required

The schema field type this blob corresponds to (e.g., IMAGE, PDF, DOCUMENT)

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

blobs.blob_id

string

Unique identifier for the blob

blobs.key_prefix

string | null

Storage key/path of the blob, this will be used to retrieve the blob from the storage. It is similar to a file path. If not provided, it will be placed in the root of the bucket.

Example:

"/videos/video.mp4"

blobs.properties

Properties · object

All blob data and metadata unified (formerly separate 'data' and 'metadata' fields). Contains URLs, dimensions, metadata, and any other blob-specific information.

blobs.details

BlobDetails · object

System-generated file details (filename, size, hash, etc.)

Show child attributes

blobs.details.filename

string | null

blobs.details.size_bytes

integer | null

blobs.details.mime_type

string | null

blobs.details.hash

string | null

blobs.details.s3_object_key

string | null

source_details

SourceDetails · object[]

Lineage/source details for this object; used for downstream references.

Show child attributes

source_details.type

enum<string>

required

Immediate origin type from which this entity was derived.

Available options:

bucket,

collection,

taxonomy,

cluster

source_details.source_id

string

required

Identifier of the immediate source entity (e.g., bucket_id, collection_id, taxonomy_id).

status

enum<string>

default:DRAFT

The current status of the object.

Available options:

PENDING,

IN_PROGRESS,

PROCESSING,

COMPLETED,

COMPLETED_WITH_ERRORS,

FAILED,

CANCELED,

UNKNOWN,

SKIPPED,

DRAFT,

ACTIVE,

ARCHIVED,

SUSPENDED

error

string | null

The error message if the object failed to process.

Example:

"Failed to process object: Object not found"

skip_duplicates

boolean

default:false

Skip duplicate blobs, if a blob with the same hash already exists, it will be skipped.

created_at

string<date-time> | null

Timestamp when the object was created. Automatically populated by the system.

updated_at

string<date-time> | null

Timestamp when the object was last updated. Automatically populated by the system.

Get Object Partially Update Object

⌘I

Health

Organizations

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Templates

Analytics

Resource Search

Inference

Agent Sessions

Tasks

Webhooks

Notifications

Triggers

Update Object

Headers

Path Parameters

Body

Response