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": {},
"unsearchable_document_ids": [
"<string>"
],
"consistency": {
"retriever_visible": "<string>",
"recommended_header": "<string>",
"write_token_available": false,
"expected_visible_within_ms": 123,
"poll": {},
"next_actions": [
{}
]
},
"warnings": [
"<string>"
]
}{
"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
}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": {},
"unsearchable_document_ids": [
"<string>"
],
"consistency": {
"retriever_visible": "<string>",
"recommended_header": "<string>",
"write_token_available": false,
"expected_visible_within_ms": 123,
"poll": {},
"next_actions": [
{}
]
},
"warnings": [
"<string>"
]
}{
"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.
Path Parameters
The namespace to upsert documents into.
Example:
"ns_abc123def456"
Body
application/json
Keys this body does not declare are ignored, and the response's warnings name them, until 2026-11-02; from 2026-11-02 they are refused with 422 extra_forbidden naming the accepted keys.
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
document_ids that were stored but carry no vector for the collection's declared index, so a retriever search will not return them until you provide a vector for that index or run the collection's extractor. The documents are readable by list and get; they are only absent from search. Empty when every document is searchable.
How and when this write becomes visible to retriever reads.
Show child attributes
Show child attributes
Advisories about this write that did not fail it: today, that the idempotency replay entry could not be stored, so a retry with the same idempotency_key would write again.
Was this page helpful?