Bucket Objects

Partially Update Object

Changed on

This endpoint partially updates an existing object in the specified bucket (PATCH operation). Send the object's custom fields flat at the root of the body, for example {"campaign_id": "camp_002"}. Only the fields you send change. key_prefix and skip_duplicates are also accepted. This route has no metadata field. System names such as status, object_id and blobs are reserved and return a 422. It does not trigger processing.

patch/v1/buckets/{bucket_identifier}/objects/{object_identifier}

Request

  • Base URL: https://api.mixpeek.com
  • URL: https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/{object_identifier}
  • Auth: HTTP bearer and API key in header X-Namespace

Path parameters

bucket_identifierstring required

The unique identifier of the bucket.

object_identifierstring required

The unique identifier of the object.

Request body

key_prefixstring nullable

Updated storage key/path prefix of the object

skip_duplicatesboolean nullable

Skip duplicate blobs

Response

Successful Response

object_idstring

Unique identifier for the object

bucket_idstring required

ID of the bucket this object belongs to

key_prefixstring 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.

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

errorstring nullable

The error message if the object failed to process.

created_atstring date-time nullable

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

updated_atstring date-time nullable

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

document_countinteger nullable

Number of documents your collections have produced from this object. The object's own record in its bucket is not counted, so the value stays 0 until a collection has processed the object. Populated on GET requests. Null on list responses (expensive query) and when the count cannot be read in time. Use this to check if an object has already been processed.

Example response

{
  "blobs": [
    {
      "blob_id": "blob_1",
      "data": {
        "num_pages": 5,
        "title": "Service Agreement 2024"
      },
      "key_prefix": "/contract-2024/content.pdf",
      "metadata": {
        "author": "John Doe",
        "department": "Legal"
      },
      "property": "content",
      "type": "PDF"
    }
  ],
  "bucket_id": "bkt_9xy8z7",
  "content_hash": "28a9f5e8...",
  "created_at": "2024-10-21T10:30:00Z",
  "key_prefix": "/contract-2024",
  "metadata": {
    "category": "contracts",
    "year": 2024
  },
  "object_id": "obj_123abc456def",
  "skip_duplicates": false,
  "status": "PENDING",
  "updated_at": "2024-10-21T10:30:00Z"
}

Changes

  • d4b5fad18960Revision changes
    • info

      the response's property default value changed from DRAFT to PENDING for the status

  • 61a175e8eb9aRevision changes
    • warning

      removed the optional property from the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status