Create Objects in Batch
curl --request POST \
--url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/batch \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"objects": [
{
"blobs": [
{
"data": "https://example.com/contract-2024.pdf",
"key_prefix": "/contract-2024/content.pdf",
"metadata": {
"author": "John Doe",
"department": "Legal",
"num_pages": 5
},
"property": "content",
"type": "pdf"
}
],
"category": "contracts",
"key_prefix": "/documents",
"review_status": "draft",
"title": "Service Agreement 2024",
"year": 2024
}
]
}
'import requests
url = "https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/batch"
payload = { "objects": [
{
"blobs": [
{
"data": "https://example.com/contract-2024.pdf",
"key_prefix": "/contract-2024/content.pdf",
"metadata": {
"author": "John Doe",
"department": "Legal",
"num_pages": 5
},
"property": "content",
"type": "pdf"
}
],
"category": "contracts",
"key_prefix": "/documents",
"review_status": "draft",
"title": "Service Agreement 2024",
"year": 2024
}
] }
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({
objects: [
{
blobs: [
{
data: 'https://example.com/contract-2024.pdf',
key_prefix: '/contract-2024/content.pdf',
metadata: {author: 'John Doe', department: 'Legal', num_pages: 5},
property: 'content',
type: 'pdf'
}
],
category: 'contracts',
key_prefix: '/documents',
review_status: 'draft',
title: 'Service Agreement 2024',
year: 2024
}
]
})
};
fetch('https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/batch', 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/buckets/{bucket_identifier}/objects/batch",
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([
'objects' => [
[
'blobs' => [
[
'data' => 'https://example.com/contract-2024.pdf',
'key_prefix' => '/contract-2024/content.pdf',
'metadata' => [
'author' => 'John Doe',
'department' => 'Legal',
'num_pages' => 5
],
'property' => 'content',
'type' => 'pdf'
]
],
'category' => 'contracts',
'key_prefix' => '/documents',
'review_status' => 'draft',
'title' => 'Service Agreement 2024',
'year' => 2024
]
]
]),
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/buckets/{bucket_identifier}/objects/batch"
payload := strings.NewReader("{\n \"objects\": [\n {\n \"blobs\": [\n {\n \"data\": \"https://example.com/contract-2024.pdf\",\n \"key_prefix\": \"/contract-2024/content.pdf\",\n \"metadata\": {\n \"author\": \"John Doe\",\n \"department\": \"Legal\",\n \"num_pages\": 5\n },\n \"property\": \"content\",\n \"type\": \"pdf\"\n }\n ],\n \"category\": \"contracts\",\n \"key_prefix\": \"/documents\",\n \"review_status\": \"draft\",\n \"title\": \"Service Agreement 2024\",\n \"year\": 2024\n }\n ]\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/buckets/{bucket_identifier}/objects/batch")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"objects\": [\n {\n \"blobs\": [\n {\n \"data\": \"https://example.com/contract-2024.pdf\",\n \"key_prefix\": \"/contract-2024/content.pdf\",\n \"metadata\": {\n \"author\": \"John Doe\",\n \"department\": \"Legal\",\n \"num_pages\": 5\n },\n \"property\": \"content\",\n \"type\": \"pdf\"\n }\n ],\n \"category\": \"contracts\",\n \"key_prefix\": \"/documents\",\n \"review_status\": \"draft\",\n \"title\": \"Service Agreement 2024\",\n \"year\": 2024\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/batch")
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 \"objects\": [\n {\n \"blobs\": [\n {\n \"data\": \"https://example.com/contract-2024.pdf\",\n \"key_prefix\": \"/contract-2024/content.pdf\",\n \"metadata\": {\n \"author\": \"John Doe\",\n \"department\": \"Legal\",\n \"num_pages\": 5\n },\n \"property\": \"content\",\n \"type\": \"pdf\"\n }\n ],\n \"category\": \"contracts\",\n \"key_prefix\": \"/documents\",\n \"review_status\": \"draft\",\n \"title\": \"Service Agreement 2024\",\n \"year\": 2024\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"failed": [
{
"error": "Schema validation failed: Missing required field 'title'",
"error_type": "ValidationError",
"object_index": 15
}
],
"failed_count": 1,
"succeeded": [
{
"bucket_id": "bkt_9xy8z7",
"object_id": "obj_123abc",
"status": "PENDING"
}
],
"succeeded_count": 99,
"total_requested": 100
}{
"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
}Objects
Create Objects in Batch
This endpoint creates multiple new objects in the specified bucket as a batch. Each object must conform to the bucket’s schema.
Processing: By default, objects are created in PENDING status, which
means not processed yet, and are processed when a batch that includes them
is submitted. An object stays PENDING until that batch run finishes with it;
the batch status shows whether it has been submitted. Set the auto_process=true query parameter
to automatically create a processing batch and submit it (zero-touch
workflow). Sending auto_process in the JSON body, at the top level or in
an object, returns 422, unless the bucket schema declares a field with that
name inside objects.
Partial Success: This endpoint uses partial success - valid objects are created even if some fail validation. Failed objects are returned separately with error details, allowing you to fix and retry only the failed ones.
Response: Returns both succeeded and failed objects. The batch succeeds (200 OK) as long
as at least one object is created. Check the failed array for objects that need attention.
If EVERY object in the batch failed, the response is 422 instead of 200 — the body shape is
identical (succeeded: [], failed: [...]), only the status code signals total failure.
unique_key buckets: not supported here yet. If the bucket declares a unique_key
policy, this endpoint rejects the whole request (422) instead of silently creating
duplicates — use POST /v1/buckets/{bucket_id}/objects (singular) per object instead,
which enforces it.
POST
/
v1
/
buckets
/
{bucket_identifier}
/
objects
/
batch
Create Objects in Batch
curl --request POST \
--url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/batch \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"objects": [
{
"blobs": [
{
"data": "https://example.com/contract-2024.pdf",
"key_prefix": "/contract-2024/content.pdf",
"metadata": {
"author": "John Doe",
"department": "Legal",
"num_pages": 5
},
"property": "content",
"type": "pdf"
}
],
"category": "contracts",
"key_prefix": "/documents",
"review_status": "draft",
"title": "Service Agreement 2024",
"year": 2024
}
]
}
'import requests
url = "https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/batch"
payload = { "objects": [
{
"blobs": [
{
"data": "https://example.com/contract-2024.pdf",
"key_prefix": "/contract-2024/content.pdf",
"metadata": {
"author": "John Doe",
"department": "Legal",
"num_pages": 5
},
"property": "content",
"type": "pdf"
}
],
"category": "contracts",
"key_prefix": "/documents",
"review_status": "draft",
"title": "Service Agreement 2024",
"year": 2024
}
] }
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({
objects: [
{
blobs: [
{
data: 'https://example.com/contract-2024.pdf',
key_prefix: '/contract-2024/content.pdf',
metadata: {author: 'John Doe', department: 'Legal', num_pages: 5},
property: 'content',
type: 'pdf'
}
],
category: 'contracts',
key_prefix: '/documents',
review_status: 'draft',
title: 'Service Agreement 2024',
year: 2024
}
]
})
};
fetch('https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/batch', 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/buckets/{bucket_identifier}/objects/batch",
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([
'objects' => [
[
'blobs' => [
[
'data' => 'https://example.com/contract-2024.pdf',
'key_prefix' => '/contract-2024/content.pdf',
'metadata' => [
'author' => 'John Doe',
'department' => 'Legal',
'num_pages' => 5
],
'property' => 'content',
'type' => 'pdf'
]
],
'category' => 'contracts',
'key_prefix' => '/documents',
'review_status' => 'draft',
'title' => 'Service Agreement 2024',
'year' => 2024
]
]
]),
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/buckets/{bucket_identifier}/objects/batch"
payload := strings.NewReader("{\n \"objects\": [\n {\n \"blobs\": [\n {\n \"data\": \"https://example.com/contract-2024.pdf\",\n \"key_prefix\": \"/contract-2024/content.pdf\",\n \"metadata\": {\n \"author\": \"John Doe\",\n \"department\": \"Legal\",\n \"num_pages\": 5\n },\n \"property\": \"content\",\n \"type\": \"pdf\"\n }\n ],\n \"category\": \"contracts\",\n \"key_prefix\": \"/documents\",\n \"review_status\": \"draft\",\n \"title\": \"Service Agreement 2024\",\n \"year\": 2024\n }\n ]\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/buckets/{bucket_identifier}/objects/batch")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"objects\": [\n {\n \"blobs\": [\n {\n \"data\": \"https://example.com/contract-2024.pdf\",\n \"key_prefix\": \"/contract-2024/content.pdf\",\n \"metadata\": {\n \"author\": \"John Doe\",\n \"department\": \"Legal\",\n \"num_pages\": 5\n },\n \"property\": \"content\",\n \"type\": \"pdf\"\n }\n ],\n \"category\": \"contracts\",\n \"key_prefix\": \"/documents\",\n \"review_status\": \"draft\",\n \"title\": \"Service Agreement 2024\",\n \"year\": 2024\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/buckets/{bucket_identifier}/objects/batch")
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 \"objects\": [\n {\n \"blobs\": [\n {\n \"data\": \"https://example.com/contract-2024.pdf\",\n \"key_prefix\": \"/contract-2024/content.pdf\",\n \"metadata\": {\n \"author\": \"John Doe\",\n \"department\": \"Legal\",\n \"num_pages\": 5\n },\n \"property\": \"content\",\n \"type\": \"pdf\"\n }\n ],\n \"category\": \"contracts\",\n \"key_prefix\": \"/documents\",\n \"review_status\": \"draft\",\n \"title\": \"Service Agreement 2024\",\n \"year\": 2024\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"failed": [
{
"error": "Schema validation failed: Missing required field 'title'",
"error_type": "ValidationError",
"object_index": 15
}
],
"failed_count": 1,
"succeeded": [
{
"bucket_id": "bkt_9xy8z7",
"object_id": "obj_123abc",
"status": "PENDING"
}
],
"succeeded_count": 99,
"total_requested": 100
}{
"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 unique identifier of the bucket.
Query Parameters
Automatically create a batch and submit it for processing. When true, all successfully created objects will be immediately queued for processing without requiring separate batch calls. Ideal for onboarding and bulk upload workflows.
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 model for creating multiple bucket objects in a batch.
List of objects to be created in this batch (max 100).
Maximum array length:
100Show child attributes
Show child attributes
Response
Successful Response
Response model for batch object creation with partial success support.
This endpoint uses partial success: valid objects are created even if some fail. Failed objects are tracked separately so users can fix and retry them.
Objects for the requests that succeeded, in request order. A row with replayed true is an existing object returned for a reused idempotency_key or a skip_duplicates match.
Show child attributes
Show child attributes
List of objects that failed to create with error details
Show child attributes
Show child attributes
Total number of objects in the batch request
Number of objects successfully created
Number of objects that failed
Was this page helpful?