Create an annotation queue

curl --request POST \
  --url https://api.arize.com/v2/annotation-queues \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Quality Review Queue",
  "space_id": "spc_xyz789",
  "annotation_config_ids": [
    "ac_abc123"
  ],
  "annotator_emails": [
    "annotator1@example.com"
  ],
  "assignment_method": "ALL"
}
'

import requests

url = "https://api.arize.com/v2/annotation-queues"

payload = {
    "name": "Quality Review Queue",
    "space_id": "spc_xyz789",
    "annotation_config_ids": ["ac_abc123"],
    "annotator_emails": ["annotator1@example.com"],
    "assignment_method": "ALL"
}
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: 'Quality Review Queue',
    space_id: 'spc_xyz789',
    annotation_config_ids: ['ac_abc123'],
    annotator_emails: ['annotator1@example.com'],
    assignment_method: 'ALL'
  })
};

fetch('https://api.arize.com/v2/annotation-queues', 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",
  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' => 'Quality Review Queue',
    'space_id' => 'spc_xyz789',
    'annotation_config_ids' => [
        'ac_abc123'
    ],
    'annotator_emails' => [
        'annotator1@example.com'
    ],
    'assignment_method' => 'ALL'
  ]),
  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"

	payload := strings.NewReader("{\n  \"name\": \"Quality Review Queue\",\n  \"space_id\": \"spc_xyz789\",\n  \"annotation_config_ids\": [\n    \"ac_abc123\"\n  ],\n  \"annotator_emails\": [\n    \"annotator1@example.com\"\n  ],\n  \"assignment_method\": \"ALL\"\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")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Quality Review Queue\",\n  \"space_id\": \"spc_xyz789\",\n  \"annotation_config_ids\": [\n    \"ac_abc123\"\n  ],\n  \"annotator_emails\": [\n    \"annotator1@example.com\"\n  ],\n  \"assignment_method\": \"ALL\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.arize.com/v2/annotation-queues")

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\": \"Quality Review Queue\",\n  \"space_id\": \"spc_xyz789\",\n  \"annotation_config_ids\": [\n    \"ac_abc123\"\n  ],\n  \"annotator_emails\": [\n    \"annotator1@example.com\"\n  ],\n  \"assignment_method\": \"ALL\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "aq_abc123",
  "name": "Quality Review Queue",
  "space_id": "spc_xyz789",
  "instructions": "Review each response for accuracy and helpfulness",
  "annotation_configs": [
    {
      "id": "ac_001",
      "name": "accuracy",
      "type": "CONTINUOUS",
      "space_id": "spc_xyz789",
      "minimum_score": 0,
      "maximum_score": 10,
      "optimization_direction": "MAXIMIZE",
      "created_at": "2024-01-10T08:00:00Z"
    },
    {
      "id": "ac_002",
      "name": "sentiment",
      "type": "CATEGORICAL",
      "space_id": "spc_xyz789",
      "values": [
        {
          "label": "positive",
          "score": 1
        },
        {
          "label": "neutral",
          "score": 0
        },
        {
          "label": "negative",
          "score": -1
        }
      ],
      "optimization_direction": "MAXIMIZE",
      "created_at": "2024-01-10T08:00:00Z"
    }
  ],
  "annotators": [
    {
      "id": "usr_001",
      "email": "reviewer@example.com"
    },
    {
      "id": "usr_002",
      "email": "annotator@example.com"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z"
}

{
  "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": 409,
  "title": "Resource conflict",
  "detail": "A resource with the given identifier already exists.",
  "instance": "/resource",
  "type": "https://arize.com/docs/ax/rest-reference/errors#resource-conflict"
}

{
  "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"
}

Annotation Queues

Create an annotation queue

Create a new annotation queue.

Payload Requirements

The annotation queue name must be unique within the given space (among active queues).
At least one annotation_config_id is required, and all configs must belong to the specified space.
Do not include system-managed fields on input: id, created_at, updated_at.
If assignment_method is not provided, it defaults to "all".

Valid example

{
  "name": "Quality Review Queue",
  "space_id": "spc_xyz789",
  "annotation_config_ids": ["ac_abc123"],
  "annotator_emails": ["reviewer@example.com"],
  "assignment_method": "all"
}

Valid example with records

{
  "name": "Quality Review Queue",
  "space_id": "spc_xyz789",
  "annotation_config_ids": ["ac_abc123"],
  "annotator_emails": ["reviewer@example.com"],
  "records": [
    {"record_type": "SPAN", "project_id": "prj_abc", "start_time": "2024-01-15T00:00:00Z", "end_time": "2024-01-16T00:00:00Z", "span_ids": ["span_001"]},
    {"record_type": "EXAMPLE", "dataset_id": "ds_xyz", "example_ids": ["ex_001", "ex_002"]}
  ]
}

Invalid example (missing required annotation_config_ids)

{
  "name": "My Queue",
  "space_id": "spc_xyz789"
}

This endpoint is in beta, read more here.

POST

annotation-queues

Create an annotation queue

curl --request POST \
  --url https://api.arize.com/v2/annotation-queues \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Quality Review Queue",
  "space_id": "spc_xyz789",
  "annotation_config_ids": [
    "ac_abc123"
  ],
  "annotator_emails": [
    "annotator1@example.com"
  ],
  "assignment_method": "ALL"
}
'

import requests

url = "https://api.arize.com/v2/annotation-queues"

payload = {
    "name": "Quality Review Queue",
    "space_id": "spc_xyz789",
    "annotation_config_ids": ["ac_abc123"],
    "annotator_emails": ["annotator1@example.com"],
    "assignment_method": "ALL"
}
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: 'Quality Review Queue',
    space_id: 'spc_xyz789',
    annotation_config_ids: ['ac_abc123'],
    annotator_emails: ['annotator1@example.com'],
    assignment_method: 'ALL'
  })
};

fetch('https://api.arize.com/v2/annotation-queues', 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",
  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' => 'Quality Review Queue',
    'space_id' => 'spc_xyz789',
    'annotation_config_ids' => [
        'ac_abc123'
    ],
    'annotator_emails' => [
        'annotator1@example.com'
    ],
    'assignment_method' => 'ALL'
  ]),
  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"

	payload := strings.NewReader("{\n  \"name\": \"Quality Review Queue\",\n  \"space_id\": \"spc_xyz789\",\n  \"annotation_config_ids\": [\n    \"ac_abc123\"\n  ],\n  \"annotator_emails\": [\n    \"annotator1@example.com\"\n  ],\n  \"assignment_method\": \"ALL\"\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")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Quality Review Queue\",\n  \"space_id\": \"spc_xyz789\",\n  \"annotation_config_ids\": [\n    \"ac_abc123\"\n  ],\n  \"annotator_emails\": [\n    \"annotator1@example.com\"\n  ],\n  \"assignment_method\": \"ALL\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.arize.com/v2/annotation-queues")

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\": \"Quality Review Queue\",\n  \"space_id\": \"spc_xyz789\",\n  \"annotation_config_ids\": [\n    \"ac_abc123\"\n  ],\n  \"annotator_emails\": [\n    \"annotator1@example.com\"\n  ],\n  \"assignment_method\": \"ALL\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "aq_abc123",
  "name": "Quality Review Queue",
  "space_id": "spc_xyz789",
  "instructions": "Review each response for accuracy and helpfulness",
  "annotation_configs": [
    {
      "id": "ac_001",
      "name": "accuracy",
      "type": "CONTINUOUS",
      "space_id": "spc_xyz789",
      "minimum_score": 0,
      "maximum_score": 10,
      "optimization_direction": "MAXIMIZE",
      "created_at": "2024-01-10T08:00:00Z"
    },
    {
      "id": "ac_002",
      "name": "sentiment",
      "type": "CATEGORICAL",
      "space_id": "spc_xyz789",
      "values": [
        {
          "label": "positive",
          "score": 1
        },
        {
          "label": "neutral",
          "score": 0
        },
        {
          "label": "negative",
          "score": -1
        }
      ],
      "optimization_direction": "MAXIMIZE",
      "created_at": "2024-01-10T08:00:00Z"
    }
  ],
  "annotators": [
    {
      "id": "usr_001",
      "email": "reviewer@example.com"
    },
    {
      "id": "usr_002",
      "email": "annotator@example.com"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z"
}

{
  "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": 409,
  "title": "Resource conflict",
  "detail": "A resource with the given identifier already exists.",
  "instance": "/resource",
  "type": "https://arize.com/docs/ax/rest-reference/errors#resource-conflict"
}

{
  "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

Authorization

string

header

required

Most Arize AI endpoints require authentication. For those endpoints that require authentication, include your API key in the request header using the format

Body

application/json

Body containing annotation queue creation parameters

name

string

required

The name of the annotation queue. Must be unique within the space for active queues.

Maximum string length: 255

Example:

"Quality Review Queue"

space_id

string

required

The space ID that the annotation queue belongs to

Example:

"spc_xyz789"

annotation_config_ids

string[]

required

IDs of annotation configs to associate with this queue. All configs must belong to the same space.

Minimum array length: 1

Example:

["ac_abc123", "ac_def456"]

annotator_emails

string<email>[]

required

Email addresses of annotators to assign to the queue. Emails are resolved to user IDs server-side.

Minimum array length: 1

An email address

Example:

[
  "annotator1@example.com",
  "annotator2@example.com"
]

instructions

string

Instructions for annotators working on this queue

Maximum string length: 5000

Example:

"Review each response for accuracy and helpfulness"

assignment_method

enum<string>

default:ALL

How records are assigned to annotators. Defaults to ALL when omitted.

Available options:

ALL,

RANDOM

record_sources

object[]

Record sources to add to the annotation queue on creation. At most 2 record sources (projects or datasets) may be provided in a single create request. Additional records from other sources can be added after creation.

Maximum array length: 2

Option 1
Option 2
Option 3

Show child attributes

Response

An annotation queue object

string

required

The unique identifier for the annotation queue

Example:

"aq_abc123"

name

string

required

The name of the annotation queue

Example:

"Quality Review Queue"

space_id

string

required

The space id the annotation queue belongs to

Example:

"spc_xyz789"

annotators

object[]

required

Users assigned as annotators to this queue

Show child attributes

created_at

string<date-time>

required

The timestamp for when the annotation queue was created

Example:

"2024-01-15T10:30:00Z"

updated_at

string<date-time>

required

The timestamp for when the annotation queue was last updated

Example:

"2024-01-20T14:45:00Z"

instructions

string | null

The instructions for the annotation queue

Example:

"Review each response for accuracy and helpfulness"

annotation_configs

object[]

The annotation configs associated with this queue

Option 1
Option 2
Option 3

Show child attributes

List annotation queues Get an annotation queue

⌘I

API reference

API clients

Create an annotation queue

Authorizations

Body

Response