curl --request POST \
--url https://api.mixpeek.com/v1/retrievers/evaluations/datasets \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"dataset_name": "<string>",
"queries": [
{
"query_id": "<string>",
"query_input": {},
"relevant_documents": [
"<string>"
],
"relevance_scores": {}
}
],
"description": "<string>",
"metadata": {}
}
'import requests
url = "https://api.mixpeek.com/v1/retrievers/evaluations/datasets"
payload = {
"dataset_name": "<string>",
"queries": [
{
"query_id": "<string>",
"query_input": {},
"relevant_documents": ["<string>"],
"relevance_scores": {}
}
],
"description": "<string>",
"metadata": {}
}
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({
dataset_name: '<string>',
queries: [
{
query_id: '<string>',
query_input: {},
relevant_documents: ['<string>'],
relevance_scores: {}
}
],
description: '<string>',
metadata: {}
})
};
fetch('https://api.mixpeek.com/v1/retrievers/evaluations/datasets', 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/retrievers/evaluations/datasets",
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([
'dataset_name' => '<string>',
'queries' => [
[
'query_id' => '<string>',
'query_input' => [
],
'relevant_documents' => [
'<string>'
],
'relevance_scores' => [
]
]
],
'description' => '<string>',
'metadata' => [
]
]),
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/retrievers/evaluations/datasets"
payload := strings.NewReader("{\n \"dataset_name\": \"<string>\",\n \"queries\": [\n {\n \"query_id\": \"<string>\",\n \"query_input\": {},\n \"relevant_documents\": [\n \"<string>\"\n ],\n \"relevance_scores\": {}\n }\n ],\n \"description\": \"<string>\",\n \"metadata\": {}\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/retrievers/evaluations/datasets")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"dataset_name\": \"<string>\",\n \"queries\": [\n {\n \"query_id\": \"<string>\",\n \"query_input\": {},\n \"relevant_documents\": [\n \"<string>\"\n ],\n \"relevance_scores\": {}\n }\n ],\n \"description\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/retrievers/evaluations/datasets")
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 \"dataset_name\": \"<string>\",\n \"queries\": [\n {\n \"query_id\": \"<string>\",\n \"query_input\": {},\n \"relevant_documents\": [\n \"<string>\"\n ],\n \"relevance_scores\": {}\n }\n ],\n \"description\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"dataset_id": "<string>",
"dataset_name": "<string>",
"queries": [
{
"query_id": "<string>",
"query_input": {},
"relevant_documents": [
"<string>"
],
"relevance_scores": {}
}
],
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"namespace_id": "<string>",
"internal_id": "<string>",
"query_count": 123,
"description": "<string>",
"metadata": {}
}{
"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
}Create evaluation dataset
Create a ground truth dataset for evaluating retrievers. Include queries with their relevant documents and optional graded relevance scores.
curl --request POST \
--url https://api.mixpeek.com/v1/retrievers/evaluations/datasets \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"dataset_name": "<string>",
"queries": [
{
"query_id": "<string>",
"query_input": {},
"relevant_documents": [
"<string>"
],
"relevance_scores": {}
}
],
"description": "<string>",
"metadata": {}
}
'import requests
url = "https://api.mixpeek.com/v1/retrievers/evaluations/datasets"
payload = {
"dataset_name": "<string>",
"queries": [
{
"query_id": "<string>",
"query_input": {},
"relevant_documents": ["<string>"],
"relevance_scores": {}
}
],
"description": "<string>",
"metadata": {}
}
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({
dataset_name: '<string>',
queries: [
{
query_id: '<string>',
query_input: {},
relevant_documents: ['<string>'],
relevance_scores: {}
}
],
description: '<string>',
metadata: {}
})
};
fetch('https://api.mixpeek.com/v1/retrievers/evaluations/datasets', 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/retrievers/evaluations/datasets",
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([
'dataset_name' => '<string>',
'queries' => [
[
'query_id' => '<string>',
'query_input' => [
],
'relevant_documents' => [
'<string>'
],
'relevance_scores' => [
]
]
],
'description' => '<string>',
'metadata' => [
]
]),
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/retrievers/evaluations/datasets"
payload := strings.NewReader("{\n \"dataset_name\": \"<string>\",\n \"queries\": [\n {\n \"query_id\": \"<string>\",\n \"query_input\": {},\n \"relevant_documents\": [\n \"<string>\"\n ],\n \"relevance_scores\": {}\n }\n ],\n \"description\": \"<string>\",\n \"metadata\": {}\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/retrievers/evaluations/datasets")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"dataset_name\": \"<string>\",\n \"queries\": [\n {\n \"query_id\": \"<string>\",\n \"query_input\": {},\n \"relevant_documents\": [\n \"<string>\"\n ],\n \"relevance_scores\": {}\n }\n ],\n \"description\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/retrievers/evaluations/datasets")
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 \"dataset_name\": \"<string>\",\n \"queries\": [\n {\n \"query_id\": \"<string>\",\n \"query_input\": {},\n \"relevant_documents\": [\n \"<string>\"\n ],\n \"relevance_scores\": {}\n }\n ],\n \"description\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"dataset_id": "<string>",
"dataset_name": "<string>",
"queries": [
{
"query_id": "<string>",
"query_input": {},
"relevant_documents": [
"<string>"
],
"relevance_scores": {}
}
],
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"namespace_id": "<string>",
"internal_id": "<string>",
"query_count": 123,
"description": "<string>",
"metadata": {}
}{
"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.
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 creating a new evaluation dataset.
Unique name for this dataset
1 - 200List of queries with ground truth relevance labels
1Show child attributes
Show child attributes
Description of what this dataset measures
Additional metadata
Response
Successful Response
Complete evaluation dataset with metadata.
An evaluation dataset is a collection of queries with ground truth relevance labels, used to measure retriever quality.
Unique dataset identifier
Human-readable dataset name
List of queries with ground truth
Show child attributes
Show child attributes
When dataset was created
Last update timestamp
Namespace this dataset belongs to
Internal organization ID
Number of queries in dataset
Dataset description
Additional metadata (e.g., labeling instructions, version info)
Was this page helpful?

