---
title: "Create Annotation"
method: POST
path: "/v1/annotations"
tags: ["Annotations"]
---

# Create Annotation

`POST /v1/annotations`

Creates a new annotation for a trace, span, or thread in your Confident AI project. Annotations capture human feedback including ratings, expected outputs/outcomes, and explanations.

**Important validation rules:**
- For traces and spans: Use `expectedOutput` (not `expectedOutcome`)
- For threads: Use `expectedOutcome` (not `expectedOutput`)
- Rating must be 0 or 1 for THUMBS_RATING, or 1-5 for FIVE_STAR_RATING
- You must provide either `traceUuid`, `spanUuid`, or `threadId`

## Headers

- `CONFIDENT_API_KEY` string, required

## Request body

- CreateAnnotation — Request schema to create an annotation for a trace, span, or thread.
  - `traceUuid` string — This is the trace UUID to annotate. Exactly one of traceUuid, spanUuid, or threadId must be provided.
  - `spanUuid` string — This is the span UUID to annotate. Exactly one of traceUuid, spanUuid, or threadId must be provided.
  - `threadId` string — This is the thread ID to annotate. Exactly one of traceUuid, spanUuid, or threadId must be provided.
  - `rating` number, required — This is the annotated rating score, which must be 0 or 1 if the annotation is a thumb rating and an integer from 1 to 5 if the annotation is a five star rating.
  - `type` 'THUMBS_RATING' | 'FIVE_STAR_RATING' — This is the annotation typem which defaults to THUMBS_RATING.
  - `expectedOutput` string — This is the expected output for trace/span annotations, which mustn't be provided when annotating a thread.
  - `expectedOutcome` string — This is the expected outcome for thread annotations, which mustn't be provided when annotating a trace or span.
  - `explanation` string — This is an explanation for the annotation.
  - `userId` string — This can be any user ID that you want to associate with the annotation.

## Response `200`

Successfully created annotation

- CreateAnnotationResponse
  - `success` boolean, required — This is true if the annotation was successfully created.
  - `data` object, required — This maps to the id of the created annotation.
    - `id` string, required — This is the id of the created annotation.
  - `deprecated` boolean, required — This is true if this endpoint is deprecated.

---

[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-service-production.skmtc.workers.dev/v1/apis/confident-ai/confident-ai-metrics-api/revisions/95cdde71b65e/schema)