Launch Week 02 wrapped — explore all five launches
Confident AI
Docs
Pricing
Products
LLM Evaluation
LLM Evaluation

Benchmark LLM systems with research-backed metrics.

LLM Observability
LLM Observability

Trace, monitor, and alert on production LLM systems.

AI Red Teaming
AI Red Teaming

Stress-test LLM apps against adversarial attacks.

AI Governance
AI Governance

Enforce AI standards and controls across teams.

Book a DemoSign Up
Book a DemoSign Up

Create Annotation

POSThttps://api.confident-ai.com/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
POST/v1/annotations
curl -X POST "https://api.confident-ai.com/v1/annotations" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "traceUuid": "<TRACE-UUID>",
  "rating": 1,
  "type": "THUMBS_RATING",
  "expectedOutput": "Provide a clear, step-by-step password reset flow.",
  "explanation": "Response acknowledges issue and guides the user through reset steps."
}'
200
{
  "success": true,
  "data": {
    "id": "ANNOTATION-ID"
  },
  "deprecated": false
}

Headers

  • CONFIDENT_API_KEYstringRequired

    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.

  • ratingnumberRequired

    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.

  • typeenum

    This is the annotation typem which defaults to THUMBS_RATING.

    Show 2 enum valuesHide 2 enum values
    • THUMBS_RATING
    • FIVE_STAR_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

    This is true if the annotation was successfully created.

  • dataobject

    This maps to the id of the created annotation.

    Show 1 propertyHide 1 property

    • idstring

      This is the id of the created annotation.

  • deprecatedboolean

    This is true if this endpoint is deprecated.

Built byConfident AI