Annotate Queue Item

POSThttps://api.confident-ai.com/v1/annotation-queues/{itemId}/annotate

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.

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

curl -X POST "https://api.confident-ai.com/v1/annotation-queues/{itemId}/annotate" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "rating": 1,
  "type": "THUMBS_RATING",
  "explanation": "Response is accurate and helpful",
  "markAsCompleted": true
}'

200

{
  "success": true,
  "data": {
    "id": "annotation-uuid",
    "annotationIds": [
      "annotation-uuid"
    ],
    "formResponseIds": [
      "form-response-uuid-1",
      "form-response-uuid-2"
    ]
  }
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Path parameters

itemIdstringRequired
The ID of the queue item to annotate.

Request body

ratinginteger
Rating value for a single criterion (0-1 for THUMBS_RATING, 1-5 for FIVE_STAR_RATING). Shorthand for a one-entry annotations array.
typeenum
Type of the rating.
Show 2 enum valuesHide 2 enum values
- THUMBS_RATING
- FIVE_STAR_RATING
namestring
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.
expectedOutcomestring
Expected outcome (for thread items only).
expectedOutputstring
Expected output (for trace/span items only).
explanationstring
Explanation for the rating.
annotationslist of objects
One entry per criterion. Use instead of the flat fields to rate multiple criteria in a single request.
Show 6 propertiesHide 6 properties
- ratingintegerRequired
  Rating value (0-1 for THUMBS_RATING, 1-5 for FIVE_STAR_RATING).
- typeenum
  Type of the rating.
  Show 2 enum valuesHide 2 enum values
  - THUMBS_RATING
  - FIVE_STAR_RATING
- namestring
  Criterion name. Omit for the default criterion; otherwise it must match a configured custom criterion or a form criteria field.
- explanationstring
  Explanation for the rating.
- expectedOutputstring
  Expected output (for trace/span items only).
- expectedOutcomestring
  Expected outcome (for thread items only).
formResponseslist of objects
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.
Show 2 propertiesHide 2 properties
- labelstringRequired
  The visible label of the custom field being answered. Must be unique within the form and must not be a criteria field's label.
- valuestring | number | boolean | list of strings
  The answer, shaped to the field type. Null clears the answer.
  Show 4 variantsHide 4 variants
  - string
    Text or single-select fields.
  - OR
  - number
    Number or decimal fields.
  - OR
  - boolean
    Yes/No fields (also accepts the strings "Yes"/"No").
  - OR
  - list of strings
    Multi-select fields.
annotatorEmailstring
Project member to attribute the work to. Required when submitting formResponses, otherwise they will not appear in the platform.
markAsCompletedboolean
Whether to mark the queue item as completed. For form queues, completing enforces the form's required fields.

Response

Successfully annotated the queue item

successboolean
Indicates if the queue item was successfully annotated.
dataobject
Contains the created annotation and form-response identifiers.
Show 3 propertiesHide 3 properties
- idstring
  The first created annotation's id, kept for backward compatibility. Null when only form responses were submitted.
- annotationIdslist of strings
  Identifiers of the created annotations.
- formResponseIdslist of strings
  Identifiers of the created form responses.

Built byConfident AI