Upsert documents with BYO vectors
curl --request POST \
--url https://api.mixpeek.com/v1/namespaces/{namespace_id}/documents/upsert \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"documents": [
{
"document_id": "<string>",
"vectors": {},
"payload": {},
"metadata": {},
"root_object_id": "<string>",
"root_bucket_id": "<string>",
"source_object_id": "<string>",
"source_document_id": "<string>",
"source_collection_id": "<string>",
"lineage_path": "<string>",
"lineage_chain": [
{}
],
"content_hash": "<string>"
}
],
"collection_id": "<string>",
"options": {
"write_token": false,
"idempotency_key": "<string>"
}
}
'import requests
url = "https://api.mixpeek.com/v1/namespaces/{namespace_id}/documents/upsert"
payload = {
"documents": [
{
"document_id": "<string>",
"vectors": {},
"payload": {},
"metadata": {},
"root_object_id": "<string>",
"root_bucket_id": "<string>",
"source_object_id": "<string>",
"source_document_id": "<string>",
"source_collection_id": "<string>",
"lineage_path": "<string>",
"lineage_chain": [{}],
"content_hash": "<string>"
}
],
"collection_id": "<string>",
"options": {
"write_token": False,
"idempotency_key": "<string>"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
documents: [
{
document_id: '<string>',
vectors: {},
payload: {},
metadata: {},
root_object_id: '<string>',
root_bucket_id: '<string>',
source_object_id: '<string>',
source_document_id: '<string>',
source_collection_id: '<string>',
lineage_path: '<string>',
lineage_chain: [{}],
content_hash: '<string>'
}
],
collection_id: '<string>',
options: {write_token: false, idempotency_key: '<string>'}
})
};
fetch('https://api.mixpeek.com/v1/namespaces/{namespace_id}/documents/upsert', 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/namespaces/{namespace_id}/documents/upsert",
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([
'documents' => [
[
'document_id' => '<string>',
'vectors' => [
],
'payload' => [
],
'metadata' => [
],
'root_object_id' => '<string>',
'root_bucket_id' => '<string>',
'source_object_id' => '<string>',
'source_document_id' => '<string>',
'source_collection_id' => '<string>',
'lineage_path' => '<string>',
'lineage_chain' => [
[
]
],
'content_hash' => '<string>'
]
],
'collection_id' => '<string>',
'options' => [
'write_token' => false,
'idempotency_key' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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/namespaces/{namespace_id}/documents/upsert"
payload := strings.NewReader("{\n \"documents\": [\n {\n \"document_id\": \"<string>\",\n \"vectors\": {},\n \"payload\": {},\n \"metadata\": {},\n \"root_object_id\": \"<string>\",\n \"root_bucket_id\": \"<string>\",\n \"source_object_id\": \"<string>\",\n \"source_document_id\": \"<string>\",\n \"source_collection_id\": \"<string>\",\n \"lineage_path\": \"<string>\",\n \"lineage_chain\": [\n {}\n ],\n \"content_hash\": \"<string>\"\n }\n ],\n \"collection_id\": \"<string>\",\n \"options\": {\n \"write_token\": false,\n \"idempotency_key\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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/namespaces/{namespace_id}/documents/upsert")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"documents\": [\n {\n \"document_id\": \"<string>\",\n \"vectors\": {},\n \"payload\": {},\n \"metadata\": {},\n \"root_object_id\": \"<string>\",\n \"root_bucket_id\": \"<string>\",\n \"source_object_id\": \"<string>\",\n \"source_document_id\": \"<string>\",\n \"source_collection_id\": \"<string>\",\n \"lineage_path\": \"<string>\",\n \"lineage_chain\": [\n {}\n ],\n \"content_hash\": \"<string>\"\n }\n ],\n \"collection_id\": \"<string>\",\n \"options\": {\n \"write_token\": false,\n \"idempotency_key\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/namespaces/{namespace_id}/documents/upsert")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"documents\": [\n {\n \"document_id\": \"<string>\",\n \"vectors\": {},\n \"payload\": {},\n \"metadata\": {},\n \"root_object_id\": \"<string>\",\n \"root_bucket_id\": \"<string>\",\n \"source_object_id\": \"<string>\",\n \"source_document_id\": \"<string>\",\n \"source_collection_id\": \"<string>\",\n \"lineage_path\": \"<string>\",\n \"lineage_chain\": [\n {}\n ],\n \"content_hash\": \"<string>\"\n }\n ],\n \"collection_id\": \"<string>\",\n \"options\": {\n \"write_token\": false,\n \"idempotency_key\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"inserted": 123,
"document_ids": [
"<string>"
],
"write_token": "<string>",
"dropped_payload_fields": {},
"consistency": {
"retriever_visible": "<string>",
"recommended_header": "<string>",
"write_token_available": false,
"expected_visible_within_ms": 123,
"poll": {},
"next_actions": [
{}
]
}
}{
"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
}BYO vectors
Upsert documents with BYO vectors
Upsert documents with user-provided vectors directly into a namespace. This bypasses the collection/batch/extractor pipeline entirely. Documents go directly to the vector store. Maximum 1000 documents per call.
POST
/
v1
/
namespaces
/
{namespace_id}
/
documents
/
upsert
Upsert documents with BYO vectors
curl --request POST \
--url https://api.mixpeek.com/v1/namespaces/{namespace_id}/documents/upsert \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"documents": [
{
"document_id": "<string>",
"vectors": {},
"payload": {},
"metadata": {},
"root_object_id": "<string>",
"root_bucket_id": "<string>",
"source_object_id": "<string>",
"source_document_id": "<string>",
"source_collection_id": "<string>",
"lineage_path": "<string>",
"lineage_chain": [
{}
],
"content_hash": "<string>"
}
],
"collection_id": "<string>",
"options": {
"write_token": false,
"idempotency_key": "<string>"
}
}
'import requests
url = "https://api.mixpeek.com/v1/namespaces/{namespace_id}/documents/upsert"
payload = {
"documents": [
{
"document_id": "<string>",
"vectors": {},
"payload": {},
"metadata": {},
"root_object_id": "<string>",
"root_bucket_id": "<string>",
"source_object_id": "<string>",
"source_document_id": "<string>",
"source_collection_id": "<string>",
"lineage_path": "<string>",
"lineage_chain": [{}],
"content_hash": "<string>"
}
],
"collection_id": "<string>",
"options": {
"write_token": False,
"idempotency_key": "<string>"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
documents: [
{
document_id: '<string>',
vectors: {},
payload: {},
metadata: {},
root_object_id: '<string>',
root_bucket_id: '<string>',
source_object_id: '<string>',
source_document_id: '<string>',
source_collection_id: '<string>',
lineage_path: '<string>',
lineage_chain: [{}],
content_hash: '<string>'
}
],
collection_id: '<string>',
options: {write_token: false, idempotency_key: '<string>'}
})
};
fetch('https://api.mixpeek.com/v1/namespaces/{namespace_id}/documents/upsert', 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/namespaces/{namespace_id}/documents/upsert",
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([
'documents' => [
[
'document_id' => '<string>',
'vectors' => [
],
'payload' => [
],
'metadata' => [
],
'root_object_id' => '<string>',
'root_bucket_id' => '<string>',
'source_object_id' => '<string>',
'source_document_id' => '<string>',
'source_collection_id' => '<string>',
'lineage_path' => '<string>',
'lineage_chain' => [
[
]
],
'content_hash' => '<string>'
]
],
'collection_id' => '<string>',
'options' => [
'write_token' => false,
'idempotency_key' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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/namespaces/{namespace_id}/documents/upsert"
payload := strings.NewReader("{\n \"documents\": [\n {\n \"document_id\": \"<string>\",\n \"vectors\": {},\n \"payload\": {},\n \"metadata\": {},\n \"root_object_id\": \"<string>\",\n \"root_bucket_id\": \"<string>\",\n \"source_object_id\": \"<string>\",\n \"source_document_id\": \"<string>\",\n \"source_collection_id\": \"<string>\",\n \"lineage_path\": \"<string>\",\n \"lineage_chain\": [\n {}\n ],\n \"content_hash\": \"<string>\"\n }\n ],\n \"collection_id\": \"<string>\",\n \"options\": {\n \"write_token\": false,\n \"idempotency_key\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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/namespaces/{namespace_id}/documents/upsert")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"documents\": [\n {\n \"document_id\": \"<string>\",\n \"vectors\": {},\n \"payload\": {},\n \"metadata\": {},\n \"root_object_id\": \"<string>\",\n \"root_bucket_id\": \"<string>\",\n \"source_object_id\": \"<string>\",\n \"source_document_id\": \"<string>\",\n \"source_collection_id\": \"<string>\",\n \"lineage_path\": \"<string>\",\n \"lineage_chain\": [\n {}\n ],\n \"content_hash\": \"<string>\"\n }\n ],\n \"collection_id\": \"<string>\",\n \"options\": {\n \"write_token\": false,\n \"idempotency_key\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/namespaces/{namespace_id}/documents/upsert")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"documents\": [\n {\n \"document_id\": \"<string>\",\n \"vectors\": {},\n \"payload\": {},\n \"metadata\": {},\n \"root_object_id\": \"<string>\",\n \"root_bucket_id\": \"<string>\",\n \"source_object_id\": \"<string>\",\n \"source_document_id\": \"<string>\",\n \"source_collection_id\": \"<string>\",\n \"lineage_path\": \"<string>\",\n \"lineage_chain\": [\n {}\n ],\n \"content_hash\": \"<string>\"\n }\n ],\n \"collection_id\": \"<string>\",\n \"options\": {\n \"write_token\": false,\n \"idempotency_key\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"inserted": 123,
"document_ids": [
"<string>"
],
"write_token": "<string>",
"dropped_payload_fields": {},
"consistency": {
"retriever_visible": "<string>",
"recommended_header": "<string>",
"write_token_available": false,
"expected_visible_within_ms": 123,
"poll": {},
"next_actions": [
{}
]
}
}{
"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.
Path Parameters
The namespace to upsert documents into.
Example:
"ns_abc123def456"
Body
application/json
Request body for BYO document upsert.
Documents to upsert. Maximum 1000 per call.
Maximum array length:
1000Show child attributes
Show child attributes
Target collection. Documents are tagged with this collection_id so they appear in collection-scoped queries, list, and clustering. When omitted a namespace-level default collection is used.
Optional upsert behavior flags.
Show child attributes
Show child attributes
Response
Successful Response
Response from a BYO document upsert.
Number of documents upserted.
IDs of all upserted documents.
Opaque token for read-your-writes consistency (only when requested).
document_id -> payload field names that were REMOVED before storage because they collide with reserved internal field names. Their values are not stored anywhere and are not readable back. Rename the field (e.g. 'source_type' -> 'my_source_type') or nest it under 'metadata' to keep the value. Empty when nothing was dropped.
Show child attributes
Show child attributes
How and when this write becomes visible to retriever reads.
Show child attributes
Show child attributes
Was this page helpful?