Create Bucket
curl --request POST \
--url https://api.mixpeek.com/v1/buckets \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"bucket_name": "product_images",
"bucket_schema": {
"properties": {
"image": {
"description": "Product image blob",
"type": "image"
},
"metadata": {
"description": "Product information",
"properties": {
"title": {
"type": "string"
},
"category": {
"type": "string"
},
"price": {
"type": "float"
}
},
"type": "object"
}
}
},
"description": "Product images with metadata for e-commerce",
"metadata": {
"department": "Sales",
"region": "US"
}
}
'import requests
url = "https://api.mixpeek.com/v1/buckets"
payload = {
"bucket_name": "product_images",
"bucket_schema": { "properties": {
"image": {
"description": "Product image blob",
"type": "image"
},
"metadata": {
"description": "Product information",
"properties": {
"title": { "type": "string" },
"category": { "type": "string" },
"price": { "type": "float" }
},
"type": "object"
}
} },
"description": "Product images with metadata for e-commerce",
"metadata": {
"department": "Sales",
"region": "US"
}
}
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({
bucket_name: 'product_images',
bucket_schema: {
properties: {
image: {description: 'Product image blob', type: 'image'},
metadata: {
description: 'Product information',
properties: {title: {type: 'string'}, category: {type: 'string'}, price: {type: 'float'}},
type: 'object'
}
}
},
description: 'Product images with metadata for e-commerce',
metadata: {department: 'Sales', region: 'US'}
})
};
fetch('https://api.mixpeek.com/v1/buckets', 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",
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([
'bucket_name' => 'product_images',
'bucket_schema' => [
'properties' => [
'image' => [
'description' => 'Product image blob',
'type' => 'image'
],
'metadata' => [
'description' => 'Product information',
'properties' => [
'title' => [
'type' => 'string'
],
'category' => [
'type' => 'string'
],
'price' => [
'type' => 'float'
]
],
'type' => 'object'
]
]
],
'description' => 'Product images with metadata for e-commerce',
'metadata' => [
'department' => 'Sales',
'region' => 'US'
]
]),
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"
payload := strings.NewReader("{\n \"bucket_name\": \"product_images\",\n \"bucket_schema\": {\n \"properties\": {\n \"image\": {\n \"description\": \"Product image blob\",\n \"type\": \"image\"\n },\n \"metadata\": {\n \"description\": \"Product information\",\n \"properties\": {\n \"title\": {\n \"type\": \"string\"\n },\n \"category\": {\n \"type\": \"string\"\n },\n \"price\": {\n \"type\": \"float\"\n }\n },\n \"type\": \"object\"\n }\n }\n },\n \"description\": \"Product images with metadata for e-commerce\",\n \"metadata\": {\n \"department\": \"Sales\",\n \"region\": \"US\"\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")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"bucket_name\": \"product_images\",\n \"bucket_schema\": {\n \"properties\": {\n \"image\": {\n \"description\": \"Product image blob\",\n \"type\": \"image\"\n },\n \"metadata\": {\n \"description\": \"Product information\",\n \"properties\": {\n \"title\": {\n \"type\": \"string\"\n },\n \"category\": {\n \"type\": \"string\"\n },\n \"price\": {\n \"type\": \"float\"\n }\n },\n \"type\": \"object\"\n }\n }\n },\n \"description\": \"Product images with metadata for e-commerce\",\n \"metadata\": {\n \"department\": \"Sales\",\n \"region\": \"US\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/buckets")
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 \"bucket_name\": \"product_images\",\n \"bucket_schema\": {\n \"properties\": {\n \"image\": {\n \"description\": \"Product image blob\",\n \"type\": \"image\"\n },\n \"metadata\": {\n \"description\": \"Product information\",\n \"properties\": {\n \"title\": {\n \"type\": \"string\"\n },\n \"category\": {\n \"type\": \"string\"\n },\n \"price\": {\n \"type\": \"float\"\n }\n },\n \"type\": \"object\"\n }\n }\n },\n \"description\": \"Product images with metadata for e-commerce\",\n \"metadata\": {\n \"department\": \"Sales\",\n \"region\": \"US\"\n }\n}"
response = http.request(request)
puts response.read_body{
"bucket_name": "<string>",
"object_count": 123,
"total_size_bytes": 123,
"bucket_id": "<string>",
"description": "<string>",
"bucket_schema": {
"properties": {}
},
"unique_key": {
"default_policy": "upsert",
"fields": [
"video_id"
]
},
"metadata": {},
"storage_class": "standard",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"last_upload_at": "2023-11-07T05:31:56Z",
"stats_updated_at": "2023-11-07T05:31:56Z",
"status": "ACTIVE",
"is_locked": false,
"batch_stats": {
"total": 0,
"active": 0,
"completed": 0,
"failed": 0
},
"storage_stats": {
"total_size_bytes": 0,
"avg_size_bytes": 0,
"max_size_bytes": 0,
"min_size_bytes": 0
},
"source_adapter": {}
}{
"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
}Buckets
Create Bucket
This endpoint allows you to create a new bucket with a defined schema. A bucket is a collection of objects that conform to the schema. The schema defines the structure and validation rules for objects in the bucket.
POST
/
v1
/
buckets
Create Bucket
curl --request POST \
--url https://api.mixpeek.com/v1/buckets \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"bucket_name": "product_images",
"bucket_schema": {
"properties": {
"image": {
"description": "Product image blob",
"type": "image"
},
"metadata": {
"description": "Product information",
"properties": {
"title": {
"type": "string"
},
"category": {
"type": "string"
},
"price": {
"type": "float"
}
},
"type": "object"
}
}
},
"description": "Product images with metadata for e-commerce",
"metadata": {
"department": "Sales",
"region": "US"
}
}
'import requests
url = "https://api.mixpeek.com/v1/buckets"
payload = {
"bucket_name": "product_images",
"bucket_schema": { "properties": {
"image": {
"description": "Product image blob",
"type": "image"
},
"metadata": {
"description": "Product information",
"properties": {
"title": { "type": "string" },
"category": { "type": "string" },
"price": { "type": "float" }
},
"type": "object"
}
} },
"description": "Product images with metadata for e-commerce",
"metadata": {
"department": "Sales",
"region": "US"
}
}
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({
bucket_name: 'product_images',
bucket_schema: {
properties: {
image: {description: 'Product image blob', type: 'image'},
metadata: {
description: 'Product information',
properties: {title: {type: 'string'}, category: {type: 'string'}, price: {type: 'float'}},
type: 'object'
}
}
},
description: 'Product images with metadata for e-commerce',
metadata: {department: 'Sales', region: 'US'}
})
};
fetch('https://api.mixpeek.com/v1/buckets', 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",
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([
'bucket_name' => 'product_images',
'bucket_schema' => [
'properties' => [
'image' => [
'description' => 'Product image blob',
'type' => 'image'
],
'metadata' => [
'description' => 'Product information',
'properties' => [
'title' => [
'type' => 'string'
],
'category' => [
'type' => 'string'
],
'price' => [
'type' => 'float'
]
],
'type' => 'object'
]
]
],
'description' => 'Product images with metadata for e-commerce',
'metadata' => [
'department' => 'Sales',
'region' => 'US'
]
]),
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"
payload := strings.NewReader("{\n \"bucket_name\": \"product_images\",\n \"bucket_schema\": {\n \"properties\": {\n \"image\": {\n \"description\": \"Product image blob\",\n \"type\": \"image\"\n },\n \"metadata\": {\n \"description\": \"Product information\",\n \"properties\": {\n \"title\": {\n \"type\": \"string\"\n },\n \"category\": {\n \"type\": \"string\"\n },\n \"price\": {\n \"type\": \"float\"\n }\n },\n \"type\": \"object\"\n }\n }\n },\n \"description\": \"Product images with metadata for e-commerce\",\n \"metadata\": {\n \"department\": \"Sales\",\n \"region\": \"US\"\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")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"bucket_name\": \"product_images\",\n \"bucket_schema\": {\n \"properties\": {\n \"image\": {\n \"description\": \"Product image blob\",\n \"type\": \"image\"\n },\n \"metadata\": {\n \"description\": \"Product information\",\n \"properties\": {\n \"title\": {\n \"type\": \"string\"\n },\n \"category\": {\n \"type\": \"string\"\n },\n \"price\": {\n \"type\": \"float\"\n }\n },\n \"type\": \"object\"\n }\n }\n },\n \"description\": \"Product images with metadata for e-commerce\",\n \"metadata\": {\n \"department\": \"Sales\",\n \"region\": \"US\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/buckets")
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 \"bucket_name\": \"product_images\",\n \"bucket_schema\": {\n \"properties\": {\n \"image\": {\n \"description\": \"Product image blob\",\n \"type\": \"image\"\n },\n \"metadata\": {\n \"description\": \"Product information\",\n \"properties\": {\n \"title\": {\n \"type\": \"string\"\n },\n \"category\": {\n \"type\": \"string\"\n },\n \"price\": {\n \"type\": \"float\"\n }\n },\n \"type\": \"object\"\n }\n }\n },\n \"description\": \"Product images with metadata for e-commerce\",\n \"metadata\": {\n \"department\": \"Sales\",\n \"region\": \"US\"\n }\n}"
response = http.request(request)
puts response.read_body{
"bucket_name": "<string>",
"object_count": 123,
"total_size_bytes": 123,
"bucket_id": "<string>",
"description": "<string>",
"bucket_schema": {
"properties": {}
},
"unique_key": {
"default_policy": "upsert",
"fields": [
"video_id"
]
},
"metadata": {},
"storage_class": "standard",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"last_upload_at": "2023-11-07T05:31:56Z",
"stats_updated_at": "2023-11-07T05:31:56Z",
"status": "ACTIVE",
"is_locked": false,
"batch_stats": {
"total": 0,
"active": 0,
"completed": 0,
"failed": 0
},
"storage_stats": {
"total_size_bytes": 0,
"avg_size_bytes": 0,
"max_size_bytes": 0,
"min_size_bytes": 0
},
"source_adapter": {}
}{
"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.
Body
application/json
Request model for creating a new bucket.
REQUIRED: A bucket_schema must be defined to enable data processing and validation.
The bucket_schema tells the system what fields your objects will have, enabling:
- Collections to map your data fields to feature extractors via input_mappings
- Validation of object structure at upload time
- Type-safe data pipelines from bucket → collection → retrieval
Every bucket must have a schema that defines the structure of objects it will contain.
Human-readable name for the bucket
REQUIRED. Schema definition for objects in this bucket. Must include a 'properties' object mapping field names to type definitions. Use Mixpeek types (string, text, image, video, etc.) — NOT JSON Schema types like 'keyword'. Example: {"properties": {"title": {"type": "string"}, "photo": {"type": "image"}}}
Show child attributes
Show child attributes
Description of the bucket
Unique key configuration for this bucket (OPTIONAL). Enables uniqueness enforcement and upsert operations on specified field(s) from the schema. Cannot be changed after bucket creation.
Show child attributes
Show child attributes
Example:
{
"default_policy": "upsert",
"fields": ["video_id"]
}
Additional metadata for the bucket
OPTIONAL object-storage tier for this bucket's objects: standard | nearline | coldline | archive (provider-agnostic). NOTE: applied on write for sync-based ingestion (the primary media path); tiering for direct uploads (POST /objects) and presigned uploads, plus retroactive re-tiering of existing objects, are in progress. Omit for the provider default (standard).
Available options:
standard, nearline, coldline, archive OPTIONAL source connection for this bucket, stored exactly as PATCH /buckets/{bucket_id} stores it (the create path used to accept this field and silently drop it). adapter_type 'bucket' pulls objects from source_bucket_ids (fan-in); adapter_type 'collection' pulls documents from source_collection_id; any other adapter_type is an inbound webhook and is assigned a webhook_url. Bucket and collection sources are checked for dependency cycles at create time (409 names the cycle).
Show child attributes
Show child attributes
Response
Successful Response
Response model for bucket operations.
Human-readable name for the bucket
Number of objects in the bucket
Total size of all objects in the bucket in bytes
Unique identifier for the bucket
Description of the bucket
Schema definition for objects in this bucket
Show child attributes
Show child attributes
Unique key configuration for this bucket (if configured)
Show child attributes
Show child attributes
Example:
{
"default_policy": "upsert",
"fields": ["video_id"]
}
Additional metadata for the bucket
Object-storage tier for this bucket's objects: standard | nearline | coldline | archive. Provider-agnostic (GCS STANDARD/NEARLINE/COLDLINE/ARCHIVE; S3/MinIO STANDARD/STANDARD_IA/GLACIER). NOTE: applied on write for sync-based ingestion (the primary media path); tiering for direct/presigned uploads and retroactive re-tiering of existing objects are in progress. None = provider default.
Available options:
standard, nearline, coldline, archive When the bucket was created
Last modification time of bucket metadata
When the last object was uploaded to this bucket
When bucket stats were last successfully recalculated
Bucket lifecycle status (ACTIVE, ARCHIVED, SUSPENDED, IN_PROGRESS for deleting)
Available options:
PENDING, QUEUED, IN_PROGRESS, PROCESSING, COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED, INTERRUPTED, UNKNOWN, SKIPPED, DRAFT, ACTIVE, ARCHIVED, SUSPENDED, DEACTIVATED Whether the bucket is locked (read-only)
Batch statistics for this bucket (calculated asynchronously, stored in DB)
Show child attributes
Show child attributes
Storage statistics for this bucket (calculated asynchronously, stored in DB)
Show child attributes
Show child attributes
Source adapter configuration for inbound webhook-driven ingestion
Was this page helpful?