---
title: "Annotate Queue Item"
method: POST
path: "/v1/annotation-queues/{itemId}/annotate"
tags: ["Annotation Queues"]
---

# Annotate Queue Item

`POST /v1/annotation-queues/{itemId}/annotate`

## Request

- Base URL: `https://api.confident-ai.com`
- URL: `https://api.confident-ai.com/v1/annotation-queues/{itemId}/annotate`
- Auth: none declared
- TypeScript: <https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/docs/v1/annotation-queues/:itemId/annotate/post.ts> (a function with typed inputs; its response is checked against the schema)

Annotates a single queue item, associating the work with the item's trace, span, or thread automatically. Supports both plain queues and queues with an attached form.

Submit criteria ratings (the flat `rating` fields or the `annotations` array) and, for form queues, custom-field answers (`formResponses`). At least one must be present.

**Validation rules:**
- For thread items: Use `expectedOutcome` (not `expectedOutput`).
- For trace/span items: Use `expectedOutput` (not `expectedOutcome`).
- A criterion's `name` must match an available criterion — omit it for the default criterion, otherwise it must match a configured custom criterion or a form criteria field. A mismatched name is rejected.
- Form `formResponses` are addressed by each field's visible label, accepted only for queues with an attached form.
- Set `markAsCompleted: false` to leave the item open (default: true). For form queues, completing enforces the form's required fields.

## Request body

- AnnotateItem: Provide criteria ratings (the flat `rating` fields below, or the `annotations` array) and/or custom form-field answers (`responses`). At least one of these must be present.
  - `rating` integer: Rating value for a single criterion (0-1 for THUMBS_RATING, 1-5 for FIVE_STAR_RATING). Shorthand for a one-entry `annotations` array.
  - `type` 'THUMBS_RATING' | 'FIVE_STAR_RATING': Type of the rating.
  - `name` string: Criterion name. Omit for the default criterion; otherwise it must match a configured custom criterion (or a form criteria field), or the annotation will not appear.
  - `expectedOutcome` string: Expected outcome (for thread items only).
  - `expectedOutput` string: Expected output (for trace/span items only).
  - `explanation` string: Explanation for the rating.
  - `annotations` AnnotateCriteria[]: One entry per criterion. Use instead of the flat fields to rate multiple criteria in a single request.
    - `rating` integer, required: Rating value (0-1 for THUMBS_RATING, 1-5 for FIVE_STAR_RATING).
    - `type` 'THUMBS_RATING' | 'FIVE_STAR_RATING': Type of the rating.
    - `name` string: Criterion name. Omit for the default criterion; otherwise it must match a configured custom criterion or a form criteria field.
    - `explanation` string: Explanation for the rating.
    - `expectedOutput` string: Expected output (for trace/span items only).
    - `expectedOutcome` string: Expected outcome (for thread items only).
  - `formResponses` AnnotateFormResponse[]: Answers to a form's custom fields, addressed by each field's visible label. Accepted only for queues with an attached form, and requires `annotatorEmail`.
    - `label` string, required: The visible label of the custom field being answered. Must be unique within the form and must not be a criteria field's label.
    - `value` union: The answer, shaped to the field type. Null clears the answer.
      - string: Text or single-select fields.
      - number: Number or decimal fields.
      - boolean: Yes/No fields (also accepts the strings "Yes"/"No").
      - string[]: Multi-select fields.
  - `annotatorEmail` string, email: Project member to attribute the work to. Required when submitting `formResponses`, otherwise they will not appear in the platform.
  - `markAsCompleted` boolean: Whether to mark the queue item as completed. For form queues, completing enforces the form's required fields.

## Response `200`

Successfully annotated the queue item

- AnnotateItemResponse
  - `success` boolean, required: Indicates if the queue item was successfully annotated.
  - `data` object, required: Contains the created annotation and form-response identifiers.
    - `id` string, nullable: The first created annotation's id, kept for backward compatibility. Null when only form responses were submitted.
    - `annotationIds` string[]: Identifiers of the created annotations.
    - `formResponseIds` string[]: Identifiers of the created form responses.

## Changes

> 54 revisions in range; 3 not diffed.

- **2026-06-24** `877d6d6d5a76`: 2 breaking, 2 warning, 7 info
  - the response property `data/id` became nullable for the status `200`
  - the response property `data/id` became optional for the status `200`
  - deleted the `header` request parameter `CONFIDENT_API_KEY`
  - deleted the `path` request parameter `itemId`
  - …7 more

[Operation history](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/changes/v1/annotation-queues/:itemId/annotate/post.md)

---

[API](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api.md) - [All operations](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/revisions/95cdde71b65e?raw)