Skip to main content
GET
Get a document by ID.

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

collection_identifier
string
required

The ID of the collection.

document_id
string
required

The ID of the document to retrieve.

Query Parameters

return_presigned_urls
boolean
default:false

Generate fresh presigned download URLs for all blobs with S3 storage

return_vectors
boolean | null
default:false
return_vector_names
string | null

Pass true for a '_vectors' field listing available vector names (no embedding data). Pass a comma-separated list of vector names (e.g. 'gemini-embedding-2,siglip_v1') to return the float arrays for those specific vectors as top-level fields named after each vector -- matching the true/List[str] contract on the return_vector_names body field of POST .../documents/list. Storage and output names both accepted.

expand
string | null

Comma-separated fields to resolve inline under an 'expanded' key. Reserved lineage keywords: 'parent' (immediate upstream document), 'root_object' (originating bucket object), 'ancestors' (full chain root → parent), 'children' (direct downstream documents, max 100). Any other value is treated as a user field path containing doc* references (supports dot-notation, e.g. 'items.product_id'). Max 50 unique references for non-lineage fields. Depth is limited to 1 (no recursive expansion).

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.

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 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 | null

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 · object[]

Document blobs with presigned URLs when requested

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

Example: