curl --request POST \
--url https://api.mixpeek.com/v1/annotations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"document_id": "<string>",
"label": "<string>",
"collection_id": "<string>",
"confidence": 0.5,
"reasoning": "<string>",
"payload": {},
"metadata": {},
"retriever_id": "<string>",
"execution_id": "<string>",
"stage_name": "<string>"
}
'import requests
url = "https://api.mixpeek.com/v1/annotations"
payload = {
"document_id": "<string>",
"label": "<string>",
"collection_id": "<string>",
"confidence": 0.5,
"reasoning": "<string>",
"payload": {},
"metadata": {},
"retriever_id": "<string>",
"execution_id": "<string>",
"stage_name": "<string>"
}
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({
document_id: '<string>',
label: '<string>',
collection_id: '<string>',
confidence: 0.5,
reasoning: '<string>',
payload: {},
metadata: {},
retriever_id: '<string>',
execution_id: '<string>',
stage_name: '<string>'
})
};
fetch('https://api.mixpeek.com/v1/annotations', 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/annotations",
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([
'document_id' => '<string>',
'label' => '<string>',
'collection_id' => '<string>',
'confidence' => 0.5,
'reasoning' => '<string>',
'payload' => [
],
'metadata' => [
],
'retriever_id' => '<string>',
'execution_id' => '<string>',
'stage_name' => '<string>'
]),
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/annotations"
payload := strings.NewReader("{\n \"document_id\": \"<string>\",\n \"label\": \"<string>\",\n \"collection_id\": \"<string>\",\n \"confidence\": 0.5,\n \"reasoning\": \"<string>\",\n \"payload\": {},\n \"metadata\": {},\n \"retriever_id\": \"<string>\",\n \"execution_id\": \"<string>\",\n \"stage_name\": \"<string>\"\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/annotations")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"document_id\": \"<string>\",\n \"label\": \"<string>\",\n \"collection_id\": \"<string>\",\n \"confidence\": 0.5,\n \"reasoning\": \"<string>\",\n \"payload\": {},\n \"metadata\": {},\n \"retriever_id\": \"<string>\",\n \"execution_id\": \"<string>\",\n \"stage_name\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/annotations")
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 \"document_id\": \"<string>\",\n \"label\": \"<string>\",\n \"collection_id\": \"<string>\",\n \"confidence\": 0.5,\n \"reasoning\": \"<string>\",\n \"payload\": {},\n \"metadata\": {},\n \"retriever_id\": \"<string>\",\n \"execution_id\": \"<string>\",\n \"stage_name\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"actor_id": "user_eric",
"actor_type": "user",
"annotation_id": "ann_abc123def4567890",
"collection_id": "col_notes",
"confidence": 0.95,
"document_id": "doc_xyz",
"label": "approved",
"namespace_id": "ns_vitae",
"payload": {
"codes_approved": [
"E11.40",
"E11.65"
],
"raf_impact": 0.42
},
"reasoning": "Note clearly documents peripheral neuropathy.",
"retriever_id": "ret_hcc_review"
}{
"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
}Create Annotation
Record a human decision on a document.
curl --request POST \
--url https://api.mixpeek.com/v1/annotations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"document_id": "<string>",
"label": "<string>",
"collection_id": "<string>",
"confidence": 0.5,
"reasoning": "<string>",
"payload": {},
"metadata": {},
"retriever_id": "<string>",
"execution_id": "<string>",
"stage_name": "<string>"
}
'import requests
url = "https://api.mixpeek.com/v1/annotations"
payload = {
"document_id": "<string>",
"label": "<string>",
"collection_id": "<string>",
"confidence": 0.5,
"reasoning": "<string>",
"payload": {},
"metadata": {},
"retriever_id": "<string>",
"execution_id": "<string>",
"stage_name": "<string>"
}
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({
document_id: '<string>',
label: '<string>',
collection_id: '<string>',
confidence: 0.5,
reasoning: '<string>',
payload: {},
metadata: {},
retriever_id: '<string>',
execution_id: '<string>',
stage_name: '<string>'
})
};
fetch('https://api.mixpeek.com/v1/annotations', 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/annotations",
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([
'document_id' => '<string>',
'label' => '<string>',
'collection_id' => '<string>',
'confidence' => 0.5,
'reasoning' => '<string>',
'payload' => [
],
'metadata' => [
],
'retriever_id' => '<string>',
'execution_id' => '<string>',
'stage_name' => '<string>'
]),
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/annotations"
payload := strings.NewReader("{\n \"document_id\": \"<string>\",\n \"label\": \"<string>\",\n \"collection_id\": \"<string>\",\n \"confidence\": 0.5,\n \"reasoning\": \"<string>\",\n \"payload\": {},\n \"metadata\": {},\n \"retriever_id\": \"<string>\",\n \"execution_id\": \"<string>\",\n \"stage_name\": \"<string>\"\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/annotations")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"document_id\": \"<string>\",\n \"label\": \"<string>\",\n \"collection_id\": \"<string>\",\n \"confidence\": 0.5,\n \"reasoning\": \"<string>\",\n \"payload\": {},\n \"metadata\": {},\n \"retriever_id\": \"<string>\",\n \"execution_id\": \"<string>\",\n \"stage_name\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/annotations")
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 \"document_id\": \"<string>\",\n \"label\": \"<string>\",\n \"collection_id\": \"<string>\",\n \"confidence\": 0.5,\n \"reasoning\": \"<string>\",\n \"payload\": {},\n \"metadata\": {},\n \"retriever_id\": \"<string>\",\n \"execution_id\": \"<string>\",\n \"stage_name\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"actor_id": "user_eric",
"actor_type": "user",
"annotation_id": "ann_abc123def4567890",
"collection_id": "col_notes",
"confidence": 0.95,
"document_id": "doc_xyz",
"label": "approved",
"namespace_id": "ns_vitae",
"payload": {
"codes_approved": [
"E11.40",
"E11.65"
],
"raf_impact": 0.42
},
"reasoning": "Note clearly documents peripheral neuropathy.",
"retriever_id": "ret_hcc_review"
}{
"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
Create a new annotation on a document.
Document to annotate.
Decision label (e.g. 'approved', 'rejected', 'deferred').
1 - 100Collection the document belongs to.
Human confidence (0.0–1.0).
0 <= x <= 1Why this decision was made.
5000Structured payload (use-case-specific).
Optional custom metadata to attach to this annotation. Stored and returned as-is, and mirrored onto the mxp_document_annotations signal so it can be read and filtered alongside the annotation.
Response
Successful Response
Single annotation response.
The document this annotation is attached to.
Namespace scope.
Human decision label. Domain-specific — e.g. 'approved', 'rejected', 'deferred', 'infringement', 'safe', 'confirmed_dupe'.
1 - 100Unique annotation identifier.
Collection the document belongs to.
Human confidence in this decision (0.0–1.0).
0 <= x <= 1Why this decision was made. Stored for audit trail.
5000Use-case-specific structured data. E.g. {'codes_approved': ['E11.40'], 'raf_impact': 0.302}
Custom metadata attached by the caller. Stored and returned as-is, kept separate from the structured payload.
Retriever that produced the document being annotated.
Retriever execution ID.
Stage that produced the result (e.g. 'llm_enrich').
Who made the annotation (user ID or API key ID).
Actor type: 'user', 'api_key', or 'system'.
Current version; starts at 1, bumps per edit.
Backward deltas preserving every superseded version.
Show child attributes
Show child attributes
Was this page helpful?

