Client Create Ground Truth
curl --request POST \
--url https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/ground_truths \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"evaluation_instructions": "<string>",
"runs": [
{
"data": {
"Invoice Number": "INV-2025-001",
"Total Amount": 1500
},
"user_defined_id": "invoice-001"
}
]
}
'import requests
url = "https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/ground_truths"
payload = {
"name": "<string>",
"evaluation_instructions": "<string>",
"runs": [
{
"data": {
"Invoice Number": "INV-2025-001",
"Total Amount": 1500
},
"user_defined_id": "invoice-001"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
evaluation_instructions: '<string>',
runs: [
{
data: {'Invoice Number': 'INV-2025-001', 'Total Amount': 1500},
user_defined_id: 'invoice-001'
}
]
})
};
fetch('https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/ground_truths', 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://agents-api.kolena.com/api/v1/client/agents/{agent_id}/ground_truths",
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([
'name' => '<string>',
'evaluation_instructions' => '<string>',
'runs' => [
[
'data' => [
'Invoice Number' => 'INV-2025-001',
'Total Amount' => 1500
],
'user_defined_id' => 'invoice-001'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://agents-api.kolena.com/api/v1/client/agents/{agent_id}/ground_truths"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"evaluation_instructions\": \"<string>\",\n \"runs\": [\n {\n \"data\": {\n \"Invoice Number\": \"INV-2025-001\",\n \"Total Amount\": 1500\n },\n \"user_defined_id\": \"invoice-001\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://agents-api.kolena.com/api/v1/client/agents/{agent_id}/ground_truths")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"evaluation_instructions\": \"<string>\",\n \"runs\": [\n {\n \"data\": {\n \"Invoice Number\": \"INV-2025-001\",\n \"Total Amount\": 1500\n },\n \"user_defined_id\": \"invoice-001\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/ground_truths")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"evaluation_instructions\": \"<string>\",\n \"runs\": [\n {\n \"data\": {\n \"Invoice Number\": \"INV-2025-001\",\n \"Total Amount\": 1500\n },\n \"user_defined_id\": \"invoice-001\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"evaluation_instructions": "Check if the extracted invoice number and total amount match the expected values exactly.",
"id": 1,
"name": "Invoice Processing",
"runs": [
{
"data": {
"Invoice Number": "INV-2025-001",
"Total Amount": 1500
},
"user_defined_id": "invoice-001"
}
],
"version": 2
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Ground Truths
Create Ground Truth
Create a new Ground Truth for an Agent
Client Create Ground Truth
curl --request POST \
--url https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/ground_truths \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"evaluation_instructions": "<string>",
"runs": [
{
"data": {
"Invoice Number": "INV-2025-001",
"Total Amount": 1500
},
"user_defined_id": "invoice-001"
}
]
}
'import requests
url = "https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/ground_truths"
payload = {
"name": "<string>",
"evaluation_instructions": "<string>",
"runs": [
{
"data": {
"Invoice Number": "INV-2025-001",
"Total Amount": 1500
},
"user_defined_id": "invoice-001"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
evaluation_instructions: '<string>',
runs: [
{
data: {'Invoice Number': 'INV-2025-001', 'Total Amount': 1500},
user_defined_id: 'invoice-001'
}
]
})
};
fetch('https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/ground_truths', 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://agents-api.kolena.com/api/v1/client/agents/{agent_id}/ground_truths",
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([
'name' => '<string>',
'evaluation_instructions' => '<string>',
'runs' => [
[
'data' => [
'Invoice Number' => 'INV-2025-001',
'Total Amount' => 1500
],
'user_defined_id' => 'invoice-001'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://agents-api.kolena.com/api/v1/client/agents/{agent_id}/ground_truths"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"evaluation_instructions\": \"<string>\",\n \"runs\": [\n {\n \"data\": {\n \"Invoice Number\": \"INV-2025-001\",\n \"Total Amount\": 1500\n },\n \"user_defined_id\": \"invoice-001\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://agents-api.kolena.com/api/v1/client/agents/{agent_id}/ground_truths")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"evaluation_instructions\": \"<string>\",\n \"runs\": [\n {\n \"data\": {\n \"Invoice Number\": \"INV-2025-001\",\n \"Total Amount\": 1500\n },\n \"user_defined_id\": \"invoice-001\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/ground_truths")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"evaluation_instructions\": \"<string>\",\n \"runs\": [\n {\n \"data\": {\n \"Invoice Number\": \"INV-2025-001\",\n \"Total Amount\": 1500\n },\n \"user_defined_id\": \"invoice-001\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"evaluation_instructions": "Check if the extracted invoice number and total amount match the expected values exactly.",
"id": 1,
"name": "Invoice Processing",
"runs": [
{
"data": {
"Invoice Number": "INV-2025-001",
"Total Amount": 1500
},
"user_defined_id": "invoice-001"
}
],
"version": 2
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Rate Limit: This endpoint is limited to requests per minute per user.
Authorizations
Bearer authentication header of the form Bearer <token>. The <token> represents your API key, which must be acquired from the Kolena platform.
Path Parameters
Body
application/json
Response
Successful Response
The unique ID of the Ground Truth.
The current version number of the Ground Truth.
The name of the Ground Truth.
Instructions used to evaluate Runs against this Ground Truth.
The list of Runs that make up this Ground Truth.
Show child attributes
Show child attributes
Was this page helpful?
