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

# Partially Update Object

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

This endpoint partially updates an existing object in the specified bucket (PATCH operation).
    Only provided fields will be updated. At minimum, metadata can always be updated.
    Immutable fields like object_id and timestamps cannot be modified.
    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

- PatchObjectRequest — Request model for partially updating a bucket object (PATCH operation). Task 10: Use extra='allow' to accept any user-defined fields at root level. No nested metadata dict - all fields are flat.
  - `key_prefix` string, nullable — Updated storage key/path prefix of the object
  - `skip_duplicates` boolean, nullable — Skip duplicate blobs

## 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)