Batch Annotate Queue Items

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

Annotates many items in a queue in one request. Each entry in items carries a queueItemId plus the same body as the single-item annotate endpoint.

annotatorEmail and markAsCompleted set at the top level act as defaults applied to any item that omits them; a per-item value takes precedence.

POST/v1/annotation-queues/{name}/batch-annotate

curl -X POST "https://api.confident-ai.com/v1/annotation-queues/{name}/batch-annotate" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "annotatorEmail": "annotator@yourcompany.com",
  "markAsCompleted": true,
  "items": [
    {
      "queueItemId": "queue-item-uuid-1",
      "rating": 1,
      "type": "THUMBS_RATING",
      "name": "Correctness",
      "explanation": "Matches the expected answer",
      "formResponses": [
        {
          "label": "Clarity",
          "value": "Very clear"
        },
        {
          "label": "Overall",
          "value": 10
        }
      ]
    },
    {
      "queueItemId": "queue-item-uuid-2",
      "rating": 0,
      "type": "THUMBS_RATING",
      "name": "Correctness"
    }
  ]
}'

200

{
  "success": true,
  "data": {
    "results": [
      {
        "queueItemId": "queue-item-uuid-1",
        "success": true,
        "id": "annotation-uuid-1",
        "annotationIds": [
          "annotation-uuid-1"
        ],
        "formResponseIds": [
          "form-response-uuid-1",
          "form-response-uuid-2"
        ]
      },
      {
        "queueItemId": "queue-item-uuid-2",
        "success": false,
        "error": "No matching criterion for annotation 'Correctness' (THUMBS_RATING). Valid criteria: ..."
      }
    ]
  }
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Path parameters

namestringRequired
The name of the annotation queue whose items are being annotated.

Request body

annotatorEmailstring
Default annotator for items that omit it. A per-item annotatorEmail takes precedence. Required (here or per item) whenever an item submits formResponses.
markAsCompletedboolean
Default completion flag for items that omit it (effectively true). A per-item value takes precedence.
itemslist of objectsRequired
The items to annotate. Processed independently (best-effort).
Show 11 propertiesHide 11 properties
- queueItemIdstringRequired
  The id of the queue item to annotate.
- 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

Batch processed; inspect each result's success flag

successboolean
Indicates the batch request was well-formed and processed. Per-item outcomes are in data.results.
dataobject
Show 1 propertyHide 1 property
- resultslist of objects
  Show 6 propertiesHide 6 properties
  - queueItemIdstring
  - successboolean
  - idstring
    First created annotation's id (success only; null when only form responses were submitted).
  - annotationIdslist of strings
    Identifiers of the created annotations (success only).
  - formResponseIdslist of strings
    Identifiers of the created form responses (success only).
  - errorstring
    Why this item failed (failure only).

Built byConfident AI