curl --request POST \
--url https://api.mixpeek.com/v1/collections/{collection_identifier}/documents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"collection_id": "collection_123",
"root_object_id": "<string>",
"root_bucket_id": "<string>",
"source_collection_id": "<string>",
"source_document_id": "<string>",
"source_object_id": "<string>",
"lineage_path": "<string>",
"lineage_chain": [
{
"collection_id": "col_video_frames",
"document_id": "doc_frame123",
"feature_extractor_id": "multimodal_extractor_v1",
"timestamp": "2025-10-18T10:30:00Z"
}
],
"content_hash": "<string>",
"document_schema_version": "<string>",
"metadata": {},
"features": [
{
"feature_extractor_id": "<string>",
"payload": {},
"vectors": {}
}
],
"vectors": {}
}
'import requests
url = "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents"
payload = {
"collection_id": "collection_123",
"root_object_id": "<string>",
"root_bucket_id": "<string>",
"source_collection_id": "<string>",
"source_document_id": "<string>",
"source_object_id": "<string>",
"lineage_path": "<string>",
"lineage_chain": [
{
"collection_id": "col_video_frames",
"document_id": "doc_frame123",
"feature_extractor_id": "multimodal_extractor_v1",
"timestamp": "2025-10-18T10:30:00Z"
}
],
"content_hash": "<string>",
"document_schema_version": "<string>",
"metadata": {},
"features": [
{
"feature_extractor_id": "<string>",
"payload": {},
"vectors": {}
}
],
"vectors": {}
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
collection_id: 'collection_123',
root_object_id: '<string>',
root_bucket_id: '<string>',
source_collection_id: '<string>',
source_document_id: '<string>',
source_object_id: '<string>',
lineage_path: '<string>',
lineage_chain: [
{
collection_id: 'col_video_frames',
document_id: 'doc_frame123',
feature_extractor_id: 'multimodal_extractor_v1',
timestamp: '2025-10-18T10:30:00Z'
}
],
content_hash: '<string>',
document_schema_version: '<string>',
metadata: {},
features: [{feature_extractor_id: '<string>', payload: {}, vectors: {}}],
vectors: {}
})
};
fetch('https://api.mixpeek.com/v1/collections/{collection_identifier}/documents', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'collection_id' => 'collection_123',
'root_object_id' => '<string>',
'root_bucket_id' => '<string>',
'source_collection_id' => '<string>',
'source_document_id' => '<string>',
'source_object_id' => '<string>',
'lineage_path' => '<string>',
'lineage_chain' => [
[
'collection_id' => 'col_video_frames',
'document_id' => 'doc_frame123',
'feature_extractor_id' => 'multimodal_extractor_v1',
'timestamp' => '2025-10-18T10:30:00Z'
]
],
'content_hash' => '<string>',
'document_schema_version' => '<string>',
'metadata' => [
],
'features' => [
[
'feature_extractor_id' => '<string>',
'payload' => [
],
'vectors' => [
]
]
],
'vectors' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents"
payload := strings.NewReader("{\n \"collection_id\": \"collection_123\",\n \"root_object_id\": \"<string>\",\n \"root_bucket_id\": \"<string>\",\n \"source_collection_id\": \"<string>\",\n \"source_document_id\": \"<string>\",\n \"source_object_id\": \"<string>\",\n \"lineage_path\": \"<string>\",\n \"lineage_chain\": [\n {\n \"collection_id\": \"col_video_frames\",\n \"document_id\": \"doc_frame123\",\n \"feature_extractor_id\": \"multimodal_extractor_v1\",\n \"timestamp\": \"2025-10-18T10:30:00Z\"\n }\n ],\n \"content_hash\": \"<string>\",\n \"document_schema_version\": \"<string>\",\n \"metadata\": {},\n \"features\": [\n {\n \"feature_extractor_id\": \"<string>\",\n \"payload\": {},\n \"vectors\": {}\n }\n ],\n \"vectors\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/collections/{collection_identifier}/documents")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"collection_id\": \"collection_123\",\n \"root_object_id\": \"<string>\",\n \"root_bucket_id\": \"<string>\",\n \"source_collection_id\": \"<string>\",\n \"source_document_id\": \"<string>\",\n \"source_object_id\": \"<string>\",\n \"lineage_path\": \"<string>\",\n \"lineage_chain\": [\n {\n \"collection_id\": \"col_video_frames\",\n \"document_id\": \"doc_frame123\",\n \"feature_extractor_id\": \"multimodal_extractor_v1\",\n \"timestamp\": \"2025-10-18T10:30:00Z\"\n }\n ],\n \"content_hash\": \"<string>\",\n \"document_schema_version\": \"<string>\",\n \"metadata\": {},\n \"features\": [\n {\n \"feature_extractor_id\": \"<string>\",\n \"payload\": {},\n \"vectors\": {}\n }\n ],\n \"vectors\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/collections/{collection_identifier}/documents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"collection_id\": \"collection_123\",\n \"root_object_id\": \"<string>\",\n \"root_bucket_id\": \"<string>\",\n \"source_collection_id\": \"<string>\",\n \"source_document_id\": \"<string>\",\n \"source_object_id\": \"<string>\",\n \"lineage_path\": \"<string>\",\n \"lineage_chain\": [\n {\n \"collection_id\": \"col_video_frames\",\n \"document_id\": \"doc_frame123\",\n \"feature_extractor_id\": \"multimodal_extractor_v1\",\n \"timestamp\": \"2025-10-18T10:30:00Z\"\n }\n ],\n \"content_hash\": \"<string>\",\n \"document_schema_version\": \"<string>\",\n \"metadata\": {},\n \"features\": [\n {\n \"feature_extractor_id\": \"<string>\",\n \"payload\": {},\n \"vectors\": {}\n }\n ],\n \"vectors\": {}\n}"
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
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}Create a document.
Create a document by ID.
curl --request POST \
--url https://api.mixpeek.com/v1/collections/{collection_identifier}/documents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"collection_id": "collection_123",
"root_object_id": "<string>",
"root_bucket_id": "<string>",
"source_collection_id": "<string>",
"source_document_id": "<string>",
"source_object_id": "<string>",
"lineage_path": "<string>",
"lineage_chain": [
{
"collection_id": "col_video_frames",
"document_id": "doc_frame123",
"feature_extractor_id": "multimodal_extractor_v1",
"timestamp": "2025-10-18T10:30:00Z"
}
],
"content_hash": "<string>",
"document_schema_version": "<string>",
"metadata": {},
"features": [
{
"feature_extractor_id": "<string>",
"payload": {},
"vectors": {}
}
],
"vectors": {}
}
'import requests
url = "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents"
payload = {
"collection_id": "collection_123",
"root_object_id": "<string>",
"root_bucket_id": "<string>",
"source_collection_id": "<string>",
"source_document_id": "<string>",
"source_object_id": "<string>",
"lineage_path": "<string>",
"lineage_chain": [
{
"collection_id": "col_video_frames",
"document_id": "doc_frame123",
"feature_extractor_id": "multimodal_extractor_v1",
"timestamp": "2025-10-18T10:30:00Z"
}
],
"content_hash": "<string>",
"document_schema_version": "<string>",
"metadata": {},
"features": [
{
"feature_extractor_id": "<string>",
"payload": {},
"vectors": {}
}
],
"vectors": {}
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
collection_id: 'collection_123',
root_object_id: '<string>',
root_bucket_id: '<string>',
source_collection_id: '<string>',
source_document_id: '<string>',
source_object_id: '<string>',
lineage_path: '<string>',
lineage_chain: [
{
collection_id: 'col_video_frames',
document_id: 'doc_frame123',
feature_extractor_id: 'multimodal_extractor_v1',
timestamp: '2025-10-18T10:30:00Z'
}
],
content_hash: '<string>',
document_schema_version: '<string>',
metadata: {},
features: [{feature_extractor_id: '<string>', payload: {}, vectors: {}}],
vectors: {}
})
};
fetch('https://api.mixpeek.com/v1/collections/{collection_identifier}/documents', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'collection_id' => 'collection_123',
'root_object_id' => '<string>',
'root_bucket_id' => '<string>',
'source_collection_id' => '<string>',
'source_document_id' => '<string>',
'source_object_id' => '<string>',
'lineage_path' => '<string>',
'lineage_chain' => [
[
'collection_id' => 'col_video_frames',
'document_id' => 'doc_frame123',
'feature_extractor_id' => 'multimodal_extractor_v1',
'timestamp' => '2025-10-18T10:30:00Z'
]
],
'content_hash' => '<string>',
'document_schema_version' => '<string>',
'metadata' => [
],
'features' => [
[
'feature_extractor_id' => '<string>',
'payload' => [
],
'vectors' => [
]
]
],
'vectors' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/collections/{collection_identifier}/documents"
payload := strings.NewReader("{\n \"collection_id\": \"collection_123\",\n \"root_object_id\": \"<string>\",\n \"root_bucket_id\": \"<string>\",\n \"source_collection_id\": \"<string>\",\n \"source_document_id\": \"<string>\",\n \"source_object_id\": \"<string>\",\n \"lineage_path\": \"<string>\",\n \"lineage_chain\": [\n {\n \"collection_id\": \"col_video_frames\",\n \"document_id\": \"doc_frame123\",\n \"feature_extractor_id\": \"multimodal_extractor_v1\",\n \"timestamp\": \"2025-10-18T10:30:00Z\"\n }\n ],\n \"content_hash\": \"<string>\",\n \"document_schema_version\": \"<string>\",\n \"metadata\": {},\n \"features\": [\n {\n \"feature_extractor_id\": \"<string>\",\n \"payload\": {},\n \"vectors\": {}\n }\n ],\n \"vectors\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/collections/{collection_identifier}/documents")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"collection_id\": \"collection_123\",\n \"root_object_id\": \"<string>\",\n \"root_bucket_id\": \"<string>\",\n \"source_collection_id\": \"<string>\",\n \"source_document_id\": \"<string>\",\n \"source_object_id\": \"<string>\",\n \"lineage_path\": \"<string>\",\n \"lineage_chain\": [\n {\n \"collection_id\": \"col_video_frames\",\n \"document_id\": \"doc_frame123\",\n \"feature_extractor_id\": \"multimodal_extractor_v1\",\n \"timestamp\": \"2025-10-18T10:30:00Z\"\n }\n ],\n \"content_hash\": \"<string>\",\n \"document_schema_version\": \"<string>\",\n \"metadata\": {},\n \"features\": [\n {\n \"feature_extractor_id\": \"<string>\",\n \"payload\": {},\n \"vectors\": {}\n }\n ],\n \"vectors\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/collections/{collection_identifier}/documents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"collection_id\": \"collection_123\",\n \"root_object_id\": \"<string>\",\n \"root_bucket_id\": \"<string>\",\n \"source_collection_id\": \"<string>\",\n \"source_document_id\": \"<string>\",\n \"source_object_id\": \"<string>\",\n \"lineage_path\": \"<string>\",\n \"lineage_chain\": [\n {\n \"collection_id\": \"col_video_frames\",\n \"document_id\": \"doc_frame123\",\n \"feature_extractor_id\": \"multimodal_extractor_v1\",\n \"timestamp\": \"2025-10-18T10:30:00Z\"\n }\n ],\n \"content_hash\": \"<string>\",\n \"document_schema_version\": \"<string>\",\n \"metadata\": {},\n \"features\": [\n {\n \"feature_extractor_id\": \"<string>\",\n \"payload\": {},\n \"vectors\": {}\n }\n ],\n \"vectors\": {}\n}"
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
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"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 header returns 403; an invalid or revoked key returns 401.
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 of the collection.
Body
Request model for creating a document.
ID of the collection the document belongs to. Optional on POST /v1/collections/{collection_id}/documents — the collection is already identified by the URL path, so an omitted body collection_id is filled from the path (a mismatch is still rejected). Required when the request is not path-scoped.
"collection_123"
Optional denormalized root object identifier provided during creation.
Optional denormalized bucket identifier provided during creation.
Optional immediate parent type for the document.
bucket, collection, direct_upsert, signal Optional parent collection identifier when sourced from a collection.
Optional parent document identifier when sourced from a collection.
Optional parent object identifier when sourced directly from a bucket.
Optional materialized lineage path to set during creation.
Processing steps from root object to this document. Recommended for decomposition trees.
Show child attributes
Show child attributes
Optional SHA256 content hash of the source object. Supplying it on a lineage-preserving import lets a later heal/reprocess recognise the cached derivation potency and skip recompute instead of re-spending GPU. Stored at _internal.content_hash.
Optional document schema version (v1 or v2). If not provided, uses system default.
Optional metadata dictionary for user-defined fields and custom attributes.
Features to associate with the document
Show child attributes
Show child attributes
Optional pre-computed vectors to store with the document. Keys are vector index names (e.g. 'text_extractor_v1_embedding'), values are float arrays matching the index dimensions.
Show child attributes
Show child attributes
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
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"
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?

