COconfident-ai
Annotations

Create Annotation

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
post/v1/annotations

Request

Headers

CONFIDENT_API_KEYstring required

The API key of your Confident AI project.

Request body

traceUuidstring

This is the trace UUID to annotate. Exactly one of traceUuid, spanUuid, or threadId must be provided.

spanUuidstring

This is the span UUID to annotate. Exactly one of traceUuid, spanUuid, or threadId must be provided.

threadIdstring

This is the thread ID to annotate. Exactly one of traceUuid, spanUuid, or threadId must be provided.

ratingnumber 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.

expectedOutputstring

This is the expected output for trace/span annotations, which mustn't be provided when annotating a thread.

expectedOutcomestring

This is the expected outcome for thread annotations, which mustn't be provided when annotating a trace or span.

explanationstring

This is an explanation for the annotation.

userIdstring

This can be any user ID that you want to associate with the annotation.

Response

Successfully created annotation

successboolean required

This is true if the annotation was successfully created.

deprecatedboolean required

This is true if this endpoint is deprecated.

Changes

No operation changes recorded.