Annotate a batch of dataset examples

Write human annotations to a batch of examples in a dataset.

Idempotency: Writes use upsert semantics — submitting the same annotation config name for the same example overwrites the previous value. Retrying on network failure will not create duplicates.

202 Accepted: The annotations have been accepted and will be written. Visibility in read queries may lag by a short interval. No response body is returned.

Unmatched record IDs: If a record_id does not correspond to an existing example in the dataset, the annotation for that record is silently ignored. No error is returned.

Payload Requirements

• dataset_id is the path parameter for the target dataset.
• annotations is a list of per-example annotation inputs, each identified by record_id.
• Annotation names must match existing annotation configs in the dataset's space.
• Up to 1000 examples may be annotated per request.

Valid example

{
  "annotations": [
    {"record_id": "ex_abc", "values": [{"name": "quality", "score": 0.8}]}
  ]
}

Invalid example (annotation name not found in space)

{
  "annotations": [
    {"record_id": "ex_abc", "values": [{"name": "nonexistent_config"}]}
  ]
}

<Note>This endpoint is in beta, read more here.</Note>

{
  "annotations": [
    {
      "values": [
        {
          "name": "accuracy"
        }
      ]
    }
  ]
}