---
title: "Update Object"
method: PUT
path: "/v1/buckets/{bucket_identifier}/objects/{object_identifier}"
tags: ["Bucket Objects"]
---

# Update Object

`PUT /v1/buckets/{bucket_identifier}/objects/{object_identifier}`

This endpoint updates an existing object in the specified bucket.
    The updated object must conform to the bucket's schema. It does not trigger processing.

## Path parameters

- `bucket_identifier` string, required — The unique identifier of the bucket.
- `object_identifier` string, required — The unique identifier of the object.

## Request body

- UpdateObjectRequest — Request model for updating an existing bucket object.
  - `key_prefix` string, nullable — 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[], nullable — List of new or updated blobs for this object
    - `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'
    - `key_prefix` string, nullable — 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'
    - `type` 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'object' | 'array' | 'date' | 'datetime' | 'text' | 'image' | 'audio' | 'video' | 'pdf' | 'excel', required — Supported data types for bucket schema fields. Types fall into two categories: 1. **Metadata Types** (JSON types): - Stored as object metadata - Standard JSON-compatible types - Not processed by extractors (unless explicitly mapped) - Examples: string, number, boolean, date 2. **File Types** (blobs): - Stored as files/blobs - Processed by extractors - Require file content (URL or base64) - Examples: text, image, video, pdf **GIF Special Handling**: GIF files can be declared as either IMAGE or VIDEO type: - As IMAGE: GIF is embedded as a single static image (first frame) - As VIDEO: GIF is decomposed frame-by-frame with embeddings per frame The multimodal extractor detects GIFs via MIME type (image/gif) and routes them based on your schema declaration. Use VIDEO for animated GIFs where frame-level search is needed, IMAGE for static/thumbnail use cases. NOTE: For retriever input schemas that need to accept document references (e.g., "find similar documents"), use RetrieverInputSchemaFieldType instead, which includes all bucket types plus document_reference.
    - `data` union — 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
      - string, uri
      - string
      - integer
      - number
      - boolean
      - object
      - unknown[]
        - unknown
    - `upload_id` string, nullable — 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
    - `metadata` object, nullable — Per-blob metadata. Promoted onto the object root at ingest so it reaches the processed document via field passthrough (BACKE-2540). Precedence: an explicit object-root field wins over a blob metadata key of the same name; across multiple blobs the first blob to set a key wins; system/reserved field names (object_id, collection_id, _internal, ...) are never overwritten. Put shared metadata at the object root directly; use blob metadata for per-blob attributes.
    - `canonicalize_source` boolean, nullable — If set, override object-level default to control source canonicalization for this blob.
    - `force_remirror` boolean, nullable — If set, override object-level default to force re-upload even if an identical blob exists.
  - `metadata` object, nullable — Updated metadata for the object, this will be merged with existing metadata.
  - `skip_duplicates` boolean, nullable — Skip duplicate blobs, if a blob with the same hash already exists, it will be skipped.

## Response `200`

Successful Response

- ObjectResponse — Response model for bucket objects.
  - `object_id` string — Unique identifier for the object
  - `bucket_id` string, required — ID of the bucket this object belongs to
  - `key_prefix` string, nullable — 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.
  - `blobs` BlobModel[] — List of blobs contained in this object
    - `blob_id` string — Unique identifier for the blob
    - `property` string, required — Property name of the blob
    - `key_prefix` string, nullable — 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.
    - `type` 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'object' | 'array' | 'date' | 'datetime' | 'text' | 'image' | 'audio' | 'video' | 'pdf' | 'excel', required — Supported data types for bucket schema fields. Types fall into two categories: 1. **Metadata Types** (JSON types): - Stored as object metadata - Standard JSON-compatible types - Not processed by extractors (unless explicitly mapped) - Examples: string, number, boolean, date 2. **File Types** (blobs): - Stored as files/blobs - Processed by extractors - Require file content (URL or base64) - Examples: text, image, video, pdf **GIF Special Handling**: GIF files can be declared as either IMAGE or VIDEO type: - As IMAGE: GIF is embedded as a single static image (first frame) - As VIDEO: GIF is decomposed frame-by-frame with embeddings per frame The multimodal extractor detects GIFs via MIME type (image/gif) and routes them based on your schema declaration. Use VIDEO for animated GIFs where frame-level search is needed, IMAGE for static/thumbnail use cases. NOTE: For retriever input schemas that need to accept document references (e.g., "find similar documents"), use RetrieverInputSchemaFieldType instead, which includes all bucket types plus document_reference.
    - `properties` object — All blob data and metadata unified (formerly separate 'data' and 'metadata' fields). Contains URLs, dimensions, metadata, and any other blob-specific information.
    - `presigned_url` string, nullable — Canonical top-level presigned URL for this blob. Matches the shape used by `document_blobs[].presigned_url` on document responses. Populated by the API when `?return_presigned_urls=true`. Also mirrored at `properties.presigned_url` for backward compatibility — prefer this top-level field; the nested path will be removed in a future release.
    - `details` BlobDetails — File details for a bucket object, these are automatically generated by the system.
      - `filename` string, nullable
      - `size_bytes` integer, nullable
      - `mime_type` string, nullable
      - `hash` string, nullable
  - `source_details` SourceDetails[] — Lineage/source details for this object; used for downstream references.
    - `type` 'bucket' | 'collection' | 'taxonomy' | 'cluster' | 'direct_upsert' | 'none', required — Source types for any document/point.
    - `source_id` string, required — Identifier of the immediate source entity (e.g., bucket_id, collection_id, taxonomy_id).
  - `edges` EdgeModel[] — Typed, directed relationships from this object to other objects (customer-owned, root-level — never `_internal`). Flows to the document + MVS payload for the `traverse_edge` retriever stage.
    - `type` string, required — Customer-defined edge type (their vocabulary), e.g. 'used_in_ad' or 'uses_footage'. Reciprocal edges use a type and its inverse.
    - `target_object_id` string, required — The endpoint object_id this edge points to (the linked object).
    - `target_collection_id` string, nullable — Optional: narrow which derived documents of the target object a traverse_edge stage should pull (else all documents of the target).
    - `direction` 'out' | 'in' — 'out' = this object → target; 'in' = target → this object. Reciprocal pairs are written on both endpoints so either side can traverse locally.
    - `attributes` object — Free-form customer attributes ON the edge itself, e.g. {'clip_order': 3, 'start_ticks_in': 123, 'start_ticks_out': 456}.
  - `status` 'PENDING' | 'QUEUED' | 'IN_PROGRESS' | 'PROCESSING' | 'COMPLETED' | 'COMPLETED_WITH_ERRORS' | 'FAILED' | 'CANCELED' | 'INTERRUPTED' | 'UNKNOWN' | 'SKIPPED' | 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'SUSPENDED' | 'DEACTIVATED' — Enumeration of task statuses for tracking asynchronous operations. Task statuses indicate the current state of asynchronous operations like batch processing, object ingestion, clustering, and taxonomy execution. Status Categories: Operation Statuses: Track progress of async operations Lifecycle Statuses: Track entity state (buckets, collections, namespaces) Values: PENDING: Task is queued but has not started processing yet IN_PROGRESS: Task is currently being executed PROCESSING: Task is actively processing data (similar to IN_PROGRESS) COMPLETED: Task finished successfully with no errors COMPLETED_WITH_ERRORS: Task finished but some items failed (partial success) FAILED: Task encountered an error and could not complete CANCELED: Task was manually canceled by a user or system UNKNOWN: Task status could not be determined SKIPPED: Task was intentionally skipped DRAFT: Task is in draft state and not yet submitted ACTIVE: Entity is active and operational (for buckets, collections, etc.) ARCHIVED: Entity has been archived SUSPENDED: Entity has been temporarily suspended Terminal Statuses: COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED are terminal statuses. Once a task reaches these states, it will not transition to another state. Partial Success Handling: COMPLETED_WITH_ERRORS indicates that the operation completed but some documents/items failed. The task result includes: - List of successful items - List of failed items with error details - Success rate percentage This allows clients to handle partial success scenarios appropriately. Polling Guidance: - Poll tasks in PENDING, QUEUED, IN_PROGRESS, or PROCESSING states - Stop polling when task reaches COMPLETED, COMPLETED_WITH_ERRORS, FAILED, or CANCELED - Use exponential backoff (1s → 30s) when polling
  - `error` string, nullable — The error message if the object failed to process.
  - `created_at` string, date-time, nullable — Timestamp when the object was created. Automatically populated by the system.
  - `updated_at` string, date-time, nullable — Timestamp when the object was last updated. Automatically populated by the system.
  - `document_count` integer, nullable — Number of documents produced from this object across all collections. Populated on GET requests. Null on list responses (expensive query). Use this to check if an object has already been processed.
  - `consistency` WriteConsistency — How and when a write becomes visible to retriever reads.
    - `retriever_visible` string, required — Visibility model: 'eventual' (BYOV direct upsert — indexed within seconds) or 'after_processing' (managed ingestion — visible after a collection batch processes the object).
    - `recommended_header` string, nullable — Header to send on retriever execute for read-your-writes (BYOV). Set only when a write_token was actually issued; null when no token was minted (visibility is then automatic within expected_visible_within_ms).
    - `write_token_available` boolean — Whether a write_token was issued for read-your-writes.
    - `expected_visible_within_ms` integer, nullable — Typical upper bound for visibility (BYOV indexing). Null when visibility depends on asynchronous processing (managed ingestion).
    - `poll` object, nullable — How to poll for visibility when it depends on async processing: {endpoint, field, ready_when}.
    - `next_actions` object[] — Actionable next steps to reach retriever visibility.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/220a3b263fda/schema)