curl --request PUT \
--url https://api.mixpeek.com/v1/buckets/{bucket_identifier} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"bucket_name": "<string>",
"description": "<string>",
"metadata": {},
"bucket_schema": {
"properties": {}
},
"destination": {
"connection_id": "<string>",
"prefix": ""
},
"ingest_filter": {
"retriever_id": "ret_ab12cd34ef56",
"retriever_version": 1,
"action": "keep",
"on_error": "keep",
"timeout_seconds": 30
},
"unique_key": {
"default_policy": "upsert",
"fields": [
"video_id"
]
}
}
'import requests
url = "https://api.mixpeek.com/v1/buckets/{bucket_identifier}"
payload = {
"bucket_name": "<string>",
"description": "<string>",
"metadata": {},
"bucket_schema": { "properties": {} },
"destination": {
"connection_id": "<string>",
"prefix": ""
},
"ingest_filter": {
"retriever_id": "ret_ab12cd34ef56",
"retriever_version": 1,
"action": "keep",
"on_error": "keep",
"timeout_seconds": 30
},
"unique_key": {
"default_policy": "upsert",
"fields": ["video_id"]
}
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
bucket_name: '<string>',
description: '<string>',
metadata: {},
bucket_schema: {properties: {}},
destination: {connection_id: '<string>', prefix: ''},
ingest_filter: {
retriever_id: 'ret_ab12cd34ef56',
retriever_version: 1,
action: 'keep',
on_error: 'keep',
timeout_seconds: 30
},
unique_key: {default_policy: 'upsert', fields: ['video_id']}
})
};
fetch('https://api.mixpeek.com/v1/buckets/{bucket_identifier}', 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}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'bucket_name' => '<string>',
'description' => '<string>',
'metadata' => [
],
'bucket_schema' => [
'properties' => [
]
],
'destination' => [
'connection_id' => '<string>',
'prefix' => ''
],
'ingest_filter' => [
'retriever_id' => 'ret_ab12cd34ef56',
'retriever_version' => 1,
'action' => 'keep',
'on_error' => 'keep',
'timeout_seconds' => 30
],
'unique_key' => [
'default_policy' => 'upsert',
'fields' => [
'video_id'
]
]
]),
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}"
payload := strings.NewReader("{\n \"bucket_name\": \"<string>\",\n \"description\": \"<string>\",\n \"metadata\": {},\n \"bucket_schema\": {\n \"properties\": {}\n },\n \"destination\": {\n \"connection_id\": \"<string>\",\n \"prefix\": \"\"\n },\n \"ingest_filter\": {\n \"retriever_id\": \"ret_ab12cd34ef56\",\n \"retriever_version\": 1,\n \"action\": \"keep\",\n \"on_error\": \"keep\",\n \"timeout_seconds\": 30\n },\n \"unique_key\": {\n \"default_policy\": \"upsert\",\n \"fields\": [\n \"video_id\"\n ]\n }\n}")
req, _ := http.NewRequest("PUT", 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.put("https://api.mixpeek.com/v1/buckets/{bucket_identifier}")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"bucket_name\": \"<string>\",\n \"description\": \"<string>\",\n \"metadata\": {},\n \"bucket_schema\": {\n \"properties\": {}\n },\n \"destination\": {\n \"connection_id\": \"<string>\",\n \"prefix\": \"\"\n },\n \"ingest_filter\": {\n \"retriever_id\": \"ret_ab12cd34ef56\",\n \"retriever_version\": 1,\n \"action\": \"keep\",\n \"on_error\": \"keep\",\n \"timeout_seconds\": 30\n },\n \"unique_key\": {\n \"default_policy\": \"upsert\",\n \"fields\": [\n \"video_id\"\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/buckets/{bucket_identifier}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"bucket_name\": \"<string>\",\n \"description\": \"<string>\",\n \"metadata\": {},\n \"bucket_schema\": {\n \"properties\": {}\n },\n \"destination\": {\n \"connection_id\": \"<string>\",\n \"prefix\": \"\"\n },\n \"ingest_filter\": {\n \"retriever_id\": \"ret_ab12cd34ef56\",\n \"retriever_version\": 1,\n \"action\": \"keep\",\n \"on_error\": \"keep\",\n \"timeout_seconds\": 30\n },\n \"unique_key\": {\n \"default_policy\": \"upsert\",\n \"fields\": [\n \"video_id\"\n ]\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",
"destination": {
"connection_id": "<string>",
"prefix": ""
},
"ingest_filter": {
"retriever_id": "ret_ab12cd34ef56",
"retriever_version": 1,
"action": "keep",
"on_error": "keep",
"timeout_seconds": 30
},
"failed_object_count": 0,
"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
}{
"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
}Update Bucket
This endpoint allows you to update an existing bucket. You can update the bucket’s name, description, and metadata.
curl --request PUT \
--url https://api.mixpeek.com/v1/buckets/{bucket_identifier} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"bucket_name": "<string>",
"description": "<string>",
"metadata": {},
"bucket_schema": {
"properties": {}
},
"destination": {
"connection_id": "<string>",
"prefix": ""
},
"ingest_filter": {
"retriever_id": "ret_ab12cd34ef56",
"retriever_version": 1,
"action": "keep",
"on_error": "keep",
"timeout_seconds": 30
},
"unique_key": {
"default_policy": "upsert",
"fields": [
"video_id"
]
}
}
'import requests
url = "https://api.mixpeek.com/v1/buckets/{bucket_identifier}"
payload = {
"bucket_name": "<string>",
"description": "<string>",
"metadata": {},
"bucket_schema": { "properties": {} },
"destination": {
"connection_id": "<string>",
"prefix": ""
},
"ingest_filter": {
"retriever_id": "ret_ab12cd34ef56",
"retriever_version": 1,
"action": "keep",
"on_error": "keep",
"timeout_seconds": 30
},
"unique_key": {
"default_policy": "upsert",
"fields": ["video_id"]
}
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
bucket_name: '<string>',
description: '<string>',
metadata: {},
bucket_schema: {properties: {}},
destination: {connection_id: '<string>', prefix: ''},
ingest_filter: {
retriever_id: 'ret_ab12cd34ef56',
retriever_version: 1,
action: 'keep',
on_error: 'keep',
timeout_seconds: 30
},
unique_key: {default_policy: 'upsert', fields: ['video_id']}
})
};
fetch('https://api.mixpeek.com/v1/buckets/{bucket_identifier}', 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}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'bucket_name' => '<string>',
'description' => '<string>',
'metadata' => [
],
'bucket_schema' => [
'properties' => [
]
],
'destination' => [
'connection_id' => '<string>',
'prefix' => ''
],
'ingest_filter' => [
'retriever_id' => 'ret_ab12cd34ef56',
'retriever_version' => 1,
'action' => 'keep',
'on_error' => 'keep',
'timeout_seconds' => 30
],
'unique_key' => [
'default_policy' => 'upsert',
'fields' => [
'video_id'
]
]
]),
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}"
payload := strings.NewReader("{\n \"bucket_name\": \"<string>\",\n \"description\": \"<string>\",\n \"metadata\": {},\n \"bucket_schema\": {\n \"properties\": {}\n },\n \"destination\": {\n \"connection_id\": \"<string>\",\n \"prefix\": \"\"\n },\n \"ingest_filter\": {\n \"retriever_id\": \"ret_ab12cd34ef56\",\n \"retriever_version\": 1,\n \"action\": \"keep\",\n \"on_error\": \"keep\",\n \"timeout_seconds\": 30\n },\n \"unique_key\": {\n \"default_policy\": \"upsert\",\n \"fields\": [\n \"video_id\"\n ]\n }\n}")
req, _ := http.NewRequest("PUT", 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.put("https://api.mixpeek.com/v1/buckets/{bucket_identifier}")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"bucket_name\": \"<string>\",\n \"description\": \"<string>\",\n \"metadata\": {},\n \"bucket_schema\": {\n \"properties\": {}\n },\n \"destination\": {\n \"connection_id\": \"<string>\",\n \"prefix\": \"\"\n },\n \"ingest_filter\": {\n \"retriever_id\": \"ret_ab12cd34ef56\",\n \"retriever_version\": 1,\n \"action\": \"keep\",\n \"on_error\": \"keep\",\n \"timeout_seconds\": 30\n },\n \"unique_key\": {\n \"default_policy\": \"upsert\",\n \"fields\": [\n \"video_id\"\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/buckets/{bucket_identifier}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"bucket_name\": \"<string>\",\n \"description\": \"<string>\",\n \"metadata\": {},\n \"bucket_schema\": {\n \"properties\": {}\n },\n \"destination\": {\n \"connection_id\": \"<string>\",\n \"prefix\": \"\"\n },\n \"ingest_filter\": {\n \"retriever_id\": \"ret_ab12cd34ef56\",\n \"retriever_version\": 1,\n \"action\": \"keep\",\n \"on_error\": \"keep\",\n \"timeout_seconds\": 30\n },\n \"unique_key\": {\n \"default_policy\": \"upsert\",\n \"fields\": [\n \"video_id\"\n ]\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",
"destination": {
"connection_id": "<string>",
"prefix": ""
},
"ingest_filter": {
"retriever_id": "ret_ab12cd34ef56",
"retriever_version": 1,
"action": "keep",
"on_error": "keep",
"timeout_seconds": 30
},
"failed_object_count": 0,
"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
}{
"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
Query Parameters
Body
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 updating an existing bucket.
Human-readable name for the bucket
Description of the bucket
Additional metadata for the bucket
Schema definition for objects in this bucket
Show child attributes
Show child attributes
Object-storage tier: standard | nearline | coldline | archive. 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.
standard, nearline, coldline, archive Write this bucket's extraction outputs to your own storage instead of Mixpeek's: a storage connection with write access and a prefix. None keeps outputs in Mixpeek's storage.
Show child attributes
Show child attributes
Set, replace or remove (null) the bucket's ingest filter: a pinned saved retriever every candidate object a sync brings in runs through before it is committed. The version is pinned on write; omit retriever_version to pin the retriever's current version.
Show child attributes
Show child attributes
Change the bucket's unique key default_policy. fields must repeat the bucket's existing unique key fields: the key itself is fixed at creation, because every stored object is registered under it. Send default_policy: null to clear the default so each upload or object create must pass ?policy=. Rejected with 422 on a bucket created without a unique_key, or when fields differ from the stored key.
Show child attributes
Show child attributes
{
"default_policy": "upsert",
"fields": ["video_id"]
}
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
{
"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_IR; archive is refused on S3, whose archive classes need a restore before a read). 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.
standard, nearline, coldline, archive Write this bucket's extraction outputs to your own storage instead of Mixpeek's: a storage connection with write access and a prefix. None keeps outputs in Mixpeek's storage.
Show child attributes
Show child attributes
A pinned saved retriever every candidate object a sync brings in (an RTSP segment, a connector file) runs through before it is committed. A sync's own ingest_filter wins over its bucket's. Kept objects carry the filter's record (execution id included) in their ingest_filter field; dropped ones are never stored and are counted on the sync job by reason. None means no filter.
Show child attributes
Show child attributes
Objects that permanently failed to become documents. They stay lifecycle_state=active and are counted in object_count, so without this a bucket where nothing can process reads as healthy.
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)
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?