---
title: "Create or update annotations"
method: POST
path: "/api/v2/llm-obs/v1/annotation-queues/{queue_id}/annotations"
tags: ["LLM Observability"]
---

# Create or update annotations

`POST /api/v2/llm-obs/v1/annotation-queues/{queue_id}/annotations`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/llm-obs/v1/annotation-queues/{queue_id}/annotations`
- Auth: API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`

Create or update annotations on interactions in a queue. Each annotation is matched
by `interaction_id` and the requesting user's identity.
Results and errors in the response are linked to request items by `interaction_id`.
Errors for individual items are returned in the `errors` field without blocking the rest of the batch.

## Path parameters

- `queue_id` string, required

## Request body

- LLMObsAnnotationsRequest: Request to create or update annotations on interactions in an annotation queue.
  - `data` LLMObsAnnotationsDataRequest, required: Data object for creating or updating annotations.
    - `attributes` LLMObsAnnotationsDataAttributesRequest, required: Attributes for creating or updating annotations.
      - `annotations` LLMObsUpsertAnnotationItem[], required: List of annotations to create or update. Must contain at least one item.
        - `interaction_id` string, required: ID of the interaction to annotate.
        - `label_values` LLMObsAnnotationLabelValue[], required: Label values for this annotation. Each entry references a label schema by ID and provides the corresponding value validated against the schema type constraints.
          - `assessment` 'pass' | 'fail': Assessment result for a label value.
          - `label_schema_id` string, required: ID of the label schema this value corresponds to.
          - `reasoning` string: Free text reasoning for this label value.
          - `value` union, required: The value for this label. Must comply with the label schema type constraints.
            - number, double: A scalar numeric value.
            - string: A scalar string value.
            - string[]: For categorical-type labels allowing multiple selections.
            - boolean: A scalar boolean value.
    - `type` 'annotations', required: Resource type for LLM Observability annotations.

## Response `200`

OK — annotations created or updated. Per-item errors are listed in `errors`.

- LLMObsAnnotationsResponse: Response containing the created or updated annotations.
  - `data` LLMObsAnnotationsDataResponse, required: Data object for the annotations response.
    - `attributes` LLMObsAnnotationsDataAttributesResponse, required: Attributes of the annotations response.
      - `annotations` LLMObsAnnotationItemResponse[], required: Successfully created or updated annotations.
        - `created_at` string, date-time, required: Timestamp when the annotation was created.
        - `created_by` string, required: Identifier of the user who created the annotation.
        - `id` string, required: Unique identifier of the annotation.
        - `interaction_id` string, required: Identifier of the interaction this annotation belongs to.
        - `label_values` LLMObsAnnotationLabelValueResponse[], required: Label values for this annotation. Each entry references a label schema by ID and provides the corresponding value.
          - `assessment` 'pass' | 'fail': Assessment result for a label value.
          - `label_schema_id` string, required: ID of the label schema this value corresponds to.
          - `name_when_saved` string: Name of the label schema at the time the annotation was created.
          - `reasoning` string: Free text reasoning for this label value.
          - `type` 'score' | 'categorical' | 'boolean' | 'text': Type of a label in an annotation queue label schema.
          - `value` union, required: The value for this label. Must comply with the label schema type constraints.
            - number, double: A scalar numeric value.
            - string: A scalar string value.
            - string[]: For categorical-type labels allowing multiple selections.
            - boolean: A scalar boolean value.
        - `modified_at` string, date-time, required: Timestamp when the annotation was last modified.
        - `modified_by` string, required: Identifier of the user who last modified the annotation.
      - `errors` LLMObsAnnotationError[]: Partial errors for annotations that could not be processed.
        - `annotation_id` string: ID of the annotation that failed, if applicable.
        - `error` string, required: Error message.
        - `interaction_id` string, required: ID of the interaction that failed.
    - `id` string, required: The annotation queue ID.
    - `type` 'annotations', required: Resource type for LLM Observability annotations.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found — the queue does not exist.
- `429`: Too many requests

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/da68bf029e4c?raw)