--- title: "Update a document by ID (namespace-scoped)." method: PUT path: "/v1/documents/{document_id}" tags: ["Documents"] --- # Update a document by ID (namespace-scoped). `PUT /v1/documents/{document_id}` Replace a document's fields by ID without specifying a collection. ## Path parameters - `document_id` string, required — The ID of the document to update. ## Request body - DocumentUpdateRequest — Request model for updating a document. ## Response `200` Successful Response - DocumentResponse — 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 native Qdrant 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. - `collection_id` string, required — REQUIRED. ID of the collection this document belongs to. Format: 'col_' prefix + alphanumeric characters. Use for: Collection-scoped queries, filtering. - `document_blobs` BlobURLRef[] — Document blobs with presigned URLs when requested - `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. - `role` 'source' | 'processed' | 'thumbnail' | 'artifact' | 'aux' — 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. - `type` 'video' | 'image' | 'audio' | 'text' | 'pdf' | 'other' — REQUIRED. Media type of the blob content. Determines how the blob should be rendered or processed. Use 'other' for custom or unknown types. - `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. - `filename` string, nullable — OPTIONAL. Original filename or leaf name of the blob. Useful for downloads and display purposes. Example: 'segment_0.mp4', 'thumbnail.jpg' - `size_bytes` integer, nullable — OPTIONAL. Size of the blob in bytes. Useful for progress indicators and storage tracking. - `content_type` string, nullable — OPTIONAL. MIME type of the blob content. Used for proper content-type headers when serving files. Example: 'video/mp4', 'image/jpeg', 'application/pdf' - `checksum` string, nullable — OPTIONAL. Checksum or hash of the blob content for integrity verification. Format: 'algorithm:hash' (e.g., 'sha256:abc123...') - `created_at` string, date-time, nullable — OPTIONAL. Timestamp when the blob was created or uploaded. ISO 8601 format. Useful for tracking blob lifecycle and cleanup. - `source_blob_id` string, nullable — 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. - `presigned_url` string, uri, nullable — 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. - `_internal` InternalPayloadModel — Complete _internal field structure for Qdrant document payloads. All Mixpeek-managed system fields are namespaced under this structure to: - Prevent collision with user-defined fields - Provide clear separation of system vs user data - Enable filtering on internal fields via _internal.field_name paths This structure is stored in Qdrant and returned in API responses. - `internal_id` string, nullable — Organization/tenant identifier for multi-tenancy isolation. - `namespace_id` string, nullable — Namespace identifier within the organization. - `document_id` string, nullable — Document identifier (also at root level for convenience). - `collection_id` string, nullable — Collection identifier (also at root level for convenience). - `created_at` string, nullable — ISO 8601 timestamp when document was created. - `updated_at` string, nullable — ISO 8601 timestamp when document was last updated. - `lineage` InternalLineageModel — Lineage tracking information for document provenance. Tracks the complete processing history from the original bucket object through all transformation stages in the decomposition tree. - `root_object_id` string, nullable — Original object ID from bucket (root of decomposition tree). All documents derived from the same object share this ID. - `root_bucket_id` string, nullable — Bucket ID containing the root object. - `source_type` 'bucket' | 'collection' | 'direct_upsert', nullable — Type of immediate parent source. 'bucket': Document created directly from bucket object (tier 1). 'collection': Document created from another collection (tier 2+). - `source_object_id` string, nullable — Object ID of immediate parent when source_type='bucket'. - `source_document_id` string, nullable — Document ID of immediate parent when source_type='collection'. - `source_collection_id` string, nullable — Collection ID of immediate parent when source_type='collection'. - `path` string, nullable — Materialized lineage path string (e.g., 'bkt_123/col_456/col_789'). - `chain` object[], nullable — Ordered list of processing steps from root object to this document. Each step contains: collection_id, feature_extractor_id, document_id, timestamp. - `processing` InternalProcessingModel — Processing and provenance tracking information. Consolidates all processing-related metadata including source URLs, processing history, and taxonomy enrichment lineage. - `source_url` string, nullable — Original URL before S3 mirroring (for URL-based ingestion). - `object_key_source` string, nullable — S3 key source identifier. - `detected_mime_type` string, nullable — MIME type detected during canonicalization. - `history` object[], nullable — Processing steps history with timestamps and operations. - `taxonomy_lineage` object[], nullable — Taxonomy enrichment entries applied to this document. - `last_health_check` object, nullable — Last health check result (for batch processing). - `source_blobs` object[], nullable — Blobs that constituted the original source object. - `document_blobs` object[], nullable — Blobs generated during document processing (thumbnails, etc.). - `source_details` object[], nullable — Enrichment tracking and source detail entries. - `modality` string, nullable — Content modality (text, image, video, audio, etc.). - `metadata` object, nullable — System metadata including ingestion_status, feature_extractor_config_hash, and other processing-related information. - `mime_type` string, nullable — MIME type of the source content. - `size_bytes` integer, nullable — Size of the source content in bytes. - `content_hash` string, nullable — SHA256 hash of the source content for deduplication. - `_acl` InternalACLModel — Access control list for document-level security (row-level security). Controls which end-user principals can read/write a document. Used with user-scoped API keys (keys with principal_id set). Org-scoped keys bypass ACL entirely. - `owner` string, nullable — Principal ID of the document owner (the creator). - `read` string[], nullable — List of principal IDs that can read this document. - `write` string[], nullable — List of principal IDs that can write/update this document. - `public` boolean, nullable — If true, any user-scoped key can read this document. ## 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/04b379bdbb7c/schema)