curl --request GET \
--url https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/ancestors \
--header 'Authorization: Bearer <token>' \
--header 'X-Namespace: <api-key>'import requests
url = "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/ancestors"
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {Authorization: 'Bearer <token>', 'X-Namespace': '<api-key>'}
};
fetch('https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/ancestors', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/ancestors",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/ancestors"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/ancestors")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/ancestors")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
response = http.request(request)
puts response.read_body[
{
"_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"
}
]{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}Get document ancestors (lineage chain root → parent).
Return every prior step in this document’s lineage chain, in order from root through immediate parent. Excludes the document itself.
Equivalent to GET /documents/{id}?expand=ancestors but returns just
the ancestor list — convenient for SDKs and the Studio decomposition tree.
curl --request GET \
--url https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/ancestors \
--header 'Authorization: Bearer <token>' \
--header 'X-Namespace: <api-key>'import requests
url = "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/ancestors"
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {Authorization: 'Bearer <token>', 'X-Namespace': '<api-key>'}
};
fetch('https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/ancestors', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/ancestors",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/ancestors"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/ancestors")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/{document_id}/ancestors")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
response = http.request(request)
puts response.read_body[
{
"_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"
}
]{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}Authorizations
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.
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
The ID or name of the collection.
The ID of the document.
Response
Successful Response
REQUIRED. Unique identifier for the document. Format: 'doc_' prefix + alphanumeric characters. Use for: API queries, references, filtering.
"doc_f8966ff29c18e20c6b45e053"
"doc_abc123"
REQUIRED. ID of the collection this document belongs to. Format: 'col_' prefix + alphanumeric characters. Use for: Collection-scoped queries, filtering.
"col_articles"
"col_video_frames"
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.
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 with presigned URLs when requested
Show child attributes
Show child attributes
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
Show child attributes
{
"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"
}
Was this page helpful?