Patch Document

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

{
  "document_id": "<string>",
  "collection_id": "<string>",
  "root_object_id": "obj_video123",
  "root_bucket_id": "bkt_marketing",
  "source_type": "bucket",
  "source_collection_id": "col_frames",
  "source_document_id": "doc_frame_050",
  "source_object_id": "obj_video_123",
  "lineage_path": "bkt_marketing/col_frames/col_scenes",
  "lineage_chain": [
    {
      "collection_id": "<string>",
      "feature_extractor_id": "<string>",
      "document_id": "doc_frame001",
      "timestamp": "2023-11-07T05:31:56Z"
    }
  ],
  "source_blobs": [
    {}
  ],
  "metadata": {},
  "vector": [
    123
  ],
  "document_blobs": [
    {
      "field": "<string>",
      "url": "<string>",
      "role": "source",
      "type": "other",
      "object_key": "<string>",
      "filename": "segment_0.mp4",
      "size_bytes": 1048576,
      "content_type": "video/mp4",
      "checksum": "sha256:a1b2c3d4e5f6...",
      "created_at": "2023-11-07T05:31:56Z",
      "source_blob_id": "blob_abc123",
      "presigned_url": "<string>"
    }
  ]
}

PATCH

collections

{collection_identifier}

documents

{document_id}

Patch Document

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

{
  "document_id": "<string>",
  "collection_id": "<string>",
  "root_object_id": "obj_video123",
  "root_bucket_id": "bkt_marketing",
  "source_type": "bucket",
  "source_collection_id": "col_frames",
  "source_document_id": "doc_frame_050",
  "source_object_id": "obj_video_123",
  "lineage_path": "bkt_marketing/col_frames/col_scenes",
  "lineage_chain": [
    {
      "collection_id": "<string>",
      "feature_extractor_id": "<string>",
      "document_id": "doc_frame001",
      "timestamp": "2023-11-07T05:31:56Z"
    }
  ],
  "source_blobs": [
    {}
  ],
  "metadata": {},
  "vector": [
    123
  ],
  "document_blobs": [
    {
      "field": "<string>",
      "url": "<string>",
      "role": "source",
      "type": "other",
      "object_key": "<string>",
      "filename": "segment_0.mp4",
      "size_bytes": 1048576,
      "content_type": "video/mp4",
      "checksum": "sha256:a1b2c3d4e5f6...",
      "created_at": "2023-11-07T05:31:56Z",
      "source_blob_id": "blob_abc123",
      "presigned_url": "<string>"
    }
  ]
}

Headers

Authorization

string

required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

X-Namespace

string

required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

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

Response

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.

Key Fields: - document_id: Application ID for queries/references - lineage: Complete processing history and source tracking - User-defined fields: Any fields from source passed via field_passthrough - source_blobs: Which blobs from source object were processed - document_blobs: Artifacts generated by extractor (thumbnails, etc.) - enrichment fields: Flat taxonomy/cluster fields (e.g., taxonomy_*_label, cluster_id)

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.

collection_id

string

required

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

root_object_id

string | null

Denormalized root object identifier for the document.

Example:

"obj_video123"

root_bucket_id

string | null

Denormalized bucket identifier for the document's root object.

Example:

"bkt_marketing"

source_type

enum<string> | null

Immediate parent type that produced this document (bucket or collection).

Available options:

bucket,

collection

Example:

"bucket"

source_collection_id

string | null

Collection identifier of the immediate parent when sourced from a collection.

Example:

"col_frames"

source_document_id

string | null

Document identifier of the immediate parent when sourced from a collection.

Example:

"doc_frame_050"

source_object_id

string | null

Bucket object identifier of the immediate parent when sourced from a bucket.

Example:

"obj_video_123"

lineage_path

string | null

Materialized lineage path for fast lookups (e.g., 'bkt_123/col_frames/col_scenes').

Example:

"bkt_marketing/col_frames/col_scenes"

lineage_chain

LineageStep · object[]

Processing steps from root object to this document. Contains: collection_id, feature_extractor_id, document_id (if intermediate), timestamp. Use for: Visualizing pipeline, debugging, audit trail.

Show child attributes

lineage_chain.collection_id

string

required

Collection ID where this processing step occurred

lineage_chain.feature_extractor_id

string

required

Feature extractor that processed the data in this step

lineage_chain.document_id

string | null

Document ID from this step (for intermediate steps). Allows tracing back through the decomposition tree.

Example:

"doc_frame001"

lineage_chain.timestamp

string<date-time>

When this processing step occurred

source_blobs

Source Blobs · object[]

Lightweight references to source object's blobs (blob_id, blob_property, blob_type). For full details, fetch: GET /buckets/{bucket_id}/objects/{object_id}

metadata

Metadata · object

Unified metadata dictionary containing both user-defined and system metadata (ingestion_status, feature_extractor_config_hash, processing_history, etc.)

vector

number[] | null

Vector embedding for the document (only included when return_vectors=true)

document_blobs

BlobURLRef · object[]

Artifacts generated during feature extraction (thumbnails, processed outputs). When return_url=true, each entry includes a presigned_url field.

Show child attributes

document_blobs.field

string

required

REQUIRED. Stable semantic label for this blob. Use descriptive names like 'video_segment', 'thumbnail', 'source_video', etc. Avoid internal implementation details like array indices. This field is used for programmatic access and should be consistent across documents.

Minimum string length: 1

document_blobs.url

string

required

REQUIRED. Permanent URL to the blob content. S3 URLs (s3://bucket/key) are automatically converted to presigned HTTPS URLs by the API. HTTP/HTTPS URLs are returned as-is. This is the canonical reference to the blob that persists across API calls.

Minimum string length: 1

document_blobs.role

enum<string>

default:source

REQUIRED. Semantic role determining how this blob should be treated. 'source': Original input media from buckets or uploads. 'processed': Derived content created by feature extractors (segments, frames). 'thumbnail': Preview images for UI display. 'artifact': Generated outputs (reports, analysis results). 'aux': Supporting or auxiliary files. Used by UI for grouping and displaying blobs appropriately.

Available options:

source,

processed,

thumbnail,

artifact,

aux

document_blobs.type

enum<string>

default:other

REQUIRED. Media type of the blob content. Determines how the blob should be rendered or processed. Use 'other' for custom or unknown types.

Available options:

video,

image,

audio,

text,

pdf,

other

document_blobs.object_key

string | null

OPTIONAL. S3 object key without bucket prefix. Used internally for S3 operations. Example: 'namespace_123/objects/obj_456/segment_0.mp4' Only applicable for S3 URLs.

document_blobs.filename

string | null

OPTIONAL. Original filename or leaf name of the blob. Useful for downloads and display purposes. Example: 'segment_0.mp4', 'thumbnail.jpg'

Example:

"segment_0.mp4"

document_blobs.size_bytes

integer | null

OPTIONAL. Size of the blob in bytes. Useful for progress indicators and storage tracking.

Required range: x >= 0

Example:

1048576

document_blobs.content_type

string | null

OPTIONAL. MIME type of the blob content. Used for proper content-type headers when serving files. Example: 'video/mp4', 'image/jpeg', 'application/pdf'

Example:

"video/mp4"

document_blobs.checksum

string | null

OPTIONAL. Checksum or hash of the blob content for integrity verification. Format: 'algorithm:hash' (e.g., 'sha256:abc123...')

Example:

"sha256:a1b2c3d4e5f6..."

document_blobs.created_at

string<date-time> | null

OPTIONAL. Timestamp when the blob was created or uploaded. ISO 8601 format. Useful for tracking blob lifecycle and cleanup.

document_blobs.source_blob_id

string | null

OPTIONAL. Cross-reference to the source blob ID from the bucket object. Used for lineage tracking: connects processed blobs back to their original sources. Example: A video segment references the original video blob that it was extracted from.

Example:

"blob_abc123"

document_blobs.presigned_url

string<uri> | null

RESPONSE ONLY. Time-limited HTTPS URL for direct access to the blob. Automatically generated by the API when documents are retrieved. NOT REQUIRED when creating blobs - leave empty, API will populate. Typically expires after 1 hour. Use for immediate media playback or download.

Minimum string length: 1

Update Document List documents.

⌘I

Health

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Analytics

Tasks

Webhooks

Patch Document

Headers

Path Parameters

Body

Response