Partially Update Object

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. An object created with a `metadata` object keeps its fields there. Send {"metadata": {"tag": "new"}} to change one of them: the keys you send are set, a key sent as null is removed, and the other keys keep their values. 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}

Partially Update Object

cURL

curl --request PATCH \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/{object_identifier} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "key_prefix": "<string>",
  "skip_duplicates": true
}
'

200

{
  "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"
}

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

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

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Request model for partially updating a bucket object (PATCH operation).

Send the object's custom fields flat at the root of the body. Only the fields you send change. An object created with a metadata object keeps its fields there: a metadata object in the body merges into it (a null value removes a key), see merge_patch_metadata.

key_prefix · string | null

Updated storage key/path prefix of the object

skip_duplicates · boolean | null

Skip duplicate blobs

Response

200

application/json

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.

blobs · BlobModel · object[]

List of blobs contained in this object

Show child attributes

source_details · SourceDetails · object[]

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

Show child attributes

edges · EdgeModel · object[]

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.

Show child attributes

status · enum<string> · default: PENDING

Processing status of the object. A new object is PENDING, which means it has not been processed yet: either no batch including it has been submitted, or it is in a submitted batch that has not finished. The status of the object's batch tells these apart. When a batch run finishes with the object it becomes COMPLETED or FAILED.

Available options: PENDING, QUEUED, IN_PROGRESS, PROCESSING, COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED, INTERRUPTED, UNKNOWN, SKIPPED, DRAFT, ACTIVE, ARCHIVED, SUSPENDED, DEACTIVATED

error · string | null

The error message if the object failed to process.

Example:

"Failed to process object: Object not found"

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.

document_count · integer | null

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 and list responses. Null when the count cannot be read in time or the store did not answer in full. Use this to check if an object has already been processed.

consistency · WriteConsistency · object | null

When and how this object becomes a searchable document. Set on write (create) responses: managed ingestion is visible only after a collection batch processes the object — poll until document_count > 0.

Show child attributes