Patch Document

Partially update a document by ID (PATCH operation).

In metadata, each key you send is set, keys you omit stay, and a key set to null is removed.

PATCH /v1/collections/{collection_identifier}/documents/{document_id}

Patch Document

cURL

curl --request PATCH \
  --url https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '{}'

200

{
  "_internal": {
    "collection_id": "col_articles",
    "created_at": "2025-10-31T10:00:00Z",
    "document_id": "doc_f8966ff29c18e20c6b45e053",
    "internal_id": "org_abc123",
    "lineage": {
      "chain": [
        {
          "collection_id": "col_articles",
          "feature_extractor_id": "text_extractor_v1",
          "timestamp": "2025-10-31T10:00:00Z"
        }
      ],
      "path": "bkt_content/col_articles",
      "root_bucket_id": "bkt_content",
      "root_object_id": "obj_article_001",
      "source_object_id": "obj_article_001",
      "source_type": "bucket"
    },
    "metadata": {
      "ingestion_status": "COMPLETED"
    },
    "modality": "text",
    "namespace_id": "ns_xyz789",
    "source_blobs": [
      {
        "blob_id": "blob_text_001",
        "blob_property": "content",
        "blob_type": "text"
      }
    ],
    "updated_at": "2025-10-31T10:00:00Z"
  },
  "author": "Dr. Smith",
  "collection_id": "col_articles",
  "description": "Text document with _internal structure",
  "document_id": "doc_f8966ff29c18e20c6b45e053",
  "title": "AI in Healthcare"
}

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 header returns 403; an invalid or revoked key returns 401.

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

collection_identifier · string · required

The ID of the collection.

document_id · string · required

The ID of the document to patch.

Body

application/json

Request model for partially updating a document (PATCH operation).

metadata is an object of key-value pairs. Each key you send is set on the stored metadata. Keys you omit stay as they are. A key whose value is null is removed from the stored metadata. metadata: null returns a 422. PUT and PATCH treat metadata the same way.

Response

200

application/json

Successful Response

Response model for a single document.

This is the standard response format when fetching documents via API endpoints. Contains all document data plus optional presigned URLs for S3 blobs.

The document payload structure follows the native vector store format: - System fields are stored in _internal (lineage, metadata, blobs, etc.) - User fields are at root level (brand_name, thumbnail_url, etc.) - Only document_id and collection_id are Mixpeek IDs at root level - No duplication between root and _internal

Query Parameters Affecting Response: - return_url=true: Adds presigned_url to each document_blobs entry - return_vectors=true: Includes embedding arrays in response

Use Cases: - Display document details in UI - Download source files or generated artifacts - Understand document provenance and processing - Access enrichment fields (flat) for filtering/display

document_id · string · required

REQUIRED. Unique identifier for the document. Format: 'doc_' prefix + alphanumeric characters. Use for: API queries, references, filtering.

Examples:

"doc_f8966ff29c18e20c6b45e053"

"doc_abc123"

collection_id · string · required

REQUIRED. ID of the collection this document belongs to. Format: 'col_' prefix + alphanumeric characters. Use for: Collection-scoped queries, filtering.

Examples:

"col_articles"

"col_video_frames"

vector_hydration_incomplete · boolean | null

OPTIONAL. Present only when return_vectors/return_vector_names was requested on this read. True means fetching the vector(s) errored or timed out before finishing -- an empty or absent vector on THIS response is UNCERTAIN, not a confirmed absence, and should not be treated as proof the vector does not exist. False means hydration ran to completion (present or genuinely absent). On a large/BYO collection with evicted partitions, hydration can time out on most reads before a background page-in warms the index; retrying the same read later, once warm, is the correct response to True here, not re-deriving the vector from source.

document_blobs · BlobURLRef · object[]

Document blobs with presigned URLs when requested

Show child attributes

_internal · InternalPayloadModel · object | null

System-managed internal fields. Contains all Mixpeek-managed metadata including lineage, processing info, timestamps, and blob references. User-defined fields appear at root level alongside document_id and collection_id.

Show child attributes

Example:

{
  "collection_id": "col_articles",
  "created_at": "2025-10-31T10:00:00Z",
  "document_id": "doc_f8966ff29c",
  "internal_id": "org_abc123",
  "lineage": {
    "path": "bkt_content/col_articles",
    "root_bucket_id": "bkt_content",
    "root_object_id": "obj_article_001",
    "source_object_id": "obj_article_001",
    "source_type": "bucket"
  },
  "metadata": { "ingestion_status": "COMPLETED" },
  "modality": "text",
  "namespace_id": "ns_xyz789",
  "updated_at": "2025-10-31T10:00:00Z"
}