--- title: "Get direct downstream documents (depth=1 children)." method: GET path: "/v1/collections/{collection_identifier}/documents/{document_id}/descendants" tags: ["Collection Documents"] --- # Get direct downstream documents (depth=1 children). `GET /v1/collections/{collection_identifier}/documents/{document_id}/descendants` ## Request - Base URL: `https://api.mixpeek.com` - URL: `https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/descendants` - Auth: HTTP bearer and API key in header `X-Namespace` Return direct downstream documents (depth=1) — every document whose `_internal.lineage.source_document_id` equals this document's ID. Capped at 100 children per request. Equivalent to ``GET /documents/{id}?expand=children`` but returns just the children. Deeper traversal (descendants beyond depth=1) is not yet supported in a single call — walk recursively client-side or filter the namespace by ``from_object`` and post-process. ## Path parameters - `collection_identifier` string, required: The ID or name of the collection. - `document_id` string, required: The ID of the document. ## Response `200` Successful Response - DocumentResponse[] - `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. - `vector_hydration_incomplete` boolean, nullable: OPTIONAL. Present only when return_vectors/return_vector_names was requested on this read. True means this read did not return a vector the store holds: fetching errored or timed out, its partition was not paged in, or the store keeps it only as quantized codes. 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. - `searchable_at` string, nullable: When the document's latest write became searchable on the shard that served this read (ISO 8601, UTC, to the write batch). Null means stored and not searchable yet: the write is acknowledged but this shard has not applied it, or a recovery replay still covers the namespace. A read after the apply returns the time. Computed when the document is read from the shard that serves it, and not stored on the document, so it cannot be used in filters, sorts or facets. - `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. - `unavailable_reason` string, nullable: Why this blob has no presigned URL on this read, when it has none: for a thumbnail removed by storage tiering, the reason it could not be regenerated (for example its source media is gone, or regeneration is busy and a retry will serve it). Absent when the URL is served. - `_internal` InternalPayloadModel: Complete _internal field structure for vector store 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 the vector store 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' | 'signal', 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`: Unprocessable Entity - `429`: Too Many Requests - `500`: Internal Server Error - `503`: Service Unavailable ## Changes - **2026-10-09** `61a175e8eb9a`: 1 warning, 5 info - removed the optional property `detail` from the response with the `422` status - added the non-success response with the status `429` - added the non-success response with the status `503` - added the optional property `success` to the response with the `422` status - …2 more - **2026-10-06** `b75474e978ff`: 1 info - added the optional property `items/searchable_at` to the response with the `200` status - **2026-10-05** `8d925c1cf55f`: 1 info - added the optional property `items/document_blobs/items/unavailable_reason` to the response with the `200` status - **2026-09-29** `a564bf7a060b`: 1 info - added the optional property `items/vector_hydration_incomplete` to the response with the `200` status - **2026-08-21** `1c7f31821424`: 1 warning - added the new `signal` enum value to the `items/_internal/anyOf[subschema #1: InternalPayloadModel]/lineage/anyOf[subschema #1: InternalLineageModel]/source_type/anyOf[subschema #1]/` response property for the response status `200` [Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/collections/:collection_identifier/documents/:document_id/descendants/get.md) --- [API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)