curl --request POST \
--url https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"annotations": [
{
"name": "accuracy",
"score": 0.95
}
]
}
'import requests
url = "https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate"
payload = { "annotations": [
{
"name": "accuracy",
"score": 0.95
}
] }
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({annotations: [{name: 'accuracy', score: 0.95}]})
};
fetch('https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate', 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.arize.com/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate",
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([
'annotations' => [
[
'name' => 'accuracy',
'score' => 0.95
]
]
]),
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://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate"
payload := strings.NewReader("{\n \"annotations\": [\n {\n \"name\": \"accuracy\",\n \"score\": 0.95\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://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"annotations\": [\n {\n \"name\": \"accuracy\",\n \"score\": 0.95\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate")
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 \"annotations\": [\n {\n \"name\": \"accuracy\",\n \"score\": 0.95\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "aqr_001",
"annotation_queue_id": "aq_abc123",
"source_type": "SPANS",
"annotations": [
{
"name": "accuracy",
"label": "correct",
"score": 1,
"annotator": {
"id": "usr_123",
"email": "reviewer@example.com"
}
}
]
}{
"status": 400,
"title": "Invalid request parameters",
"detail": "The 'name' field is required and must be a non-empty string.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#invalid-request"
}{
"status": 401,
"title": "Authentication required",
"detail": "You must be authenticated to access this resource.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#authentication-required"
}{
"status": 403,
"title": "Access forbidden",
"detail": "You do not have permission to access this resource.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#access-forbidden"
}{
"status": 404,
"title": "Resource not found",
"detail": "The requested resource with ID '12345' was not found.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#resource-not-found"
}{
"status": 422,
"title": "Unprocessable Entity",
"detail": "One or more fields failed validation.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity"
}{
"status": 429,
"title": "Rate limit exceeded",
"detail": "You have exceeded the allowed number of requests. Please try again later.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded"
}Annotate a record
Submit annotations for an annotation queue record.
Annotations are upserted into the underlying data source by annotation config name. Omitted annotation configs are left unchanged.
Payload Requirements
annotationsmust contain at least one entry and at most 500.- Each annotation
namemust match an annotation config associated with the queue. - Omit
label,score, ortextto leave the existing value unchanged. Individual fields cannot be set to null; annotations cannot be removed once written.
Response Returns a snapshot of the fields updated by this operation: the record identity and the submitted annotations only. Evaluations and user assignments are not included for performance reasons. Use the list records endpoint to retrieve the full record state.
Valid example
{
"annotations": [
{"name": "accuracy", "label": "correct", "score": 1.0},
{"name": "quality", "text": "Well-structured response"}
]
}
Invalid example (annotation name not in queue)
{
"annotations": [
{"name": "unknown_config", "label": "good"}
]
}
curl --request POST \
--url https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"annotations": [
{
"name": "accuracy",
"score": 0.95
}
]
}
'import requests
url = "https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate"
payload = { "annotations": [
{
"name": "accuracy",
"score": 0.95
}
] }
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({annotations: [{name: 'accuracy', score: 0.95}]})
};
fetch('https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate', 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.arize.com/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate",
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([
'annotations' => [
[
'name' => 'accuracy',
'score' => 0.95
]
]
]),
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://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate"
payload := strings.NewReader("{\n \"annotations\": [\n {\n \"name\": \"accuracy\",\n \"score\": 0.95\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://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"annotations\": [\n {\n \"name\": \"accuracy\",\n \"score\": 0.95\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate")
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 \"annotations\": [\n {\n \"name\": \"accuracy\",\n \"score\": 0.95\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "aqr_001",
"annotation_queue_id": "aq_abc123",
"source_type": "SPANS",
"annotations": [
{
"name": "accuracy",
"label": "correct",
"score": 1,
"annotator": {
"id": "usr_123",
"email": "reviewer@example.com"
}
}
]
}{
"status": 400,
"title": "Invalid request parameters",
"detail": "The 'name' field is required and must be a non-empty string.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#invalid-request"
}{
"status": 401,
"title": "Authentication required",
"detail": "You must be authenticated to access this resource.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#authentication-required"
}{
"status": 403,
"title": "Access forbidden",
"detail": "You do not have permission to access this resource.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#access-forbidden"
}{
"status": 404,
"title": "Resource not found",
"detail": "The requested resource with ID '12345' was not found.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#resource-not-found"
}{
"status": 422,
"title": "Unprocessable Entity",
"detail": "One or more fields failed validation.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity"
}{
"status": 429,
"title": "Rate limit exceeded",
"detail": "You have exceeded the allowed number of requests. Please try again later.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded"
}Authorizations
Most Arize AI endpoints require authentication. For those endpoints that require authentication, include your API key in the request header using the format
Service accounts may instead present an access token issued by an external identity provider (Microsoft Entra ID) when the account admin has configured that provider. Send it in the same header: Authorization: Bearer <access-token>.
Path Parameters
Body
Body containing annotations to submit for an annotation queue record
Annotations to submit for an annotation queue record. Annotations are upserted by annotation config name; omitted configs are left unchanged.
Response
Returns a snapshot of the record fields updated by the annotate operation. Only the submitted annotations are included. Evaluations and user assignments are omitted; use the list records endpoint for the full record state.
A snapshot of the annotation queue record fields that were modified by an annotate operation. Only the record identity fields and the submitted annotations are returned. Evaluations and user assignments are not fetched and are not included in this response for performance reasons; use the list records endpoint to retrieve the full record state.
Was this page helpful?