Create Annotation

POSThttps://api.confident-ai.com/v2/annotations

Records a rating against exactly one trace, span or thread, and returns its id. The target must already exist in your project. A rating on a THUMBS_RATING scale is 0 or 1; on a FIVE_STAR_RATING scale it is 1 to 5.

POST/v2/annotations

curl -X POST "https://api.confident-ai.com/v2/annotations" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "traceUuid": "3f9c2a1e-5b7d-4c8e-9f01-2a3b4c5d6e7f",
  "expectedOutput": "Mount Everest is 8,848 metres tall.",
  "rating": 1,
  "type": "FIVE_STAR_RATING",
  "name": "Helpfulness",
  "explanation": "Answered the question and cited the right source.",
  "userId": "end-user-42",
  "imagesMapping": {}
}'

200

{
  "success": true,
  "data": {
    "id": "<ANNOTATION-ID>"
  },
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Request body

Trace Annotation Requestobject
A rating left on a trace.
Show 8 propertiesHide 8 properties
- traceUuidstringRequired
  The uuid of the trace being annotated.
- expectedOutputstring
  The output the trace should have produced.
- ratingintegerRequired
  The rating to record: 0 or 1 for a THUMBS_RATING, 1 to 5 for a FIVE_STAR_RATING.
- typeenum
  This is the type of annotation, which can be either thumbs rating or five star rating.
  Show 2 enum valuesHide 2 enum values
  - FIVE_STAR_RATING
  - THUMBS_RATING
- namestring
  The criterion this rating is for, matching a custom annotation option in this project. Omit it to rate the built-in criterion.
- explanationstring
  Why the rating was given.
- userIdstring
  The id of the end user this annotation came from, when the rating was collected from your own users rather than your team.
- imagesMappingobject
  Images referenced by [DEEPEVAL:IMAGE:<key>] markers in the text fields, keyed by that marker's key.
OR
Span Annotation Requestobject
A rating left on a span.
Show 8 propertiesHide 8 properties
- spanUuidstringRequired
  The uuid of the span being annotated.
- expectedOutputstring
  The output the span should have produced.
- ratingintegerRequired
  The rating to record: 0 or 1 for a THUMBS_RATING, 1 to 5 for a FIVE_STAR_RATING.
- typeenum
  This is the type of annotation, which can be either thumbs rating or five star rating.
  Show 2 enum valuesHide 2 enum values
  - FIVE_STAR_RATING
  - THUMBS_RATING
- namestring
  The criterion this rating is for, matching a custom annotation option in this project. Omit it to rate the built-in criterion.
- explanationstring
  Why the rating was given.
- userIdstring
  The id of the end user this annotation came from, when the rating was collected from your own users rather than your team.
- imagesMappingobject
  Images referenced by [DEEPEVAL:IMAGE:<key>] markers in the text fields, keyed by that marker's key.
OR
Thread Annotation Requestobject
A rating left on a thread.
Show 8 propertiesHide 8 properties
- threadIdstringRequired
  The id of the thread being annotated.
- expectedOutcomestring
  The outcome the conversation should have reached.
- ratingintegerRequired
  The rating to record: 0 or 1 for a THUMBS_RATING, 1 to 5 for a FIVE_STAR_RATING.
- typeenum
  This is the type of annotation, which can be either thumbs rating or five star rating.
  Show 2 enum valuesHide 2 enum values
  - FIVE_STAR_RATING
  - THUMBS_RATING
- namestring
  The criterion this rating is for, matching a custom annotation option in this project. Omit it to rate the built-in criterion.
- explanationstring
  Why the rating was given.
- userIdstring
  The id of the end user this annotation came from, when the rating was collected from your own users rather than your team.
- imagesMappingobject
  Images referenced by [DEEPEVAL:IMAGE:<key>] markers in the text fields, keyed by that marker's key.

Response

Create Annotation succeeded.

successboolean
Indicates if the request was successful.
dataobject
A reference to an annotation by its id.
Show 1 propertyHide 1 property
- idstring
  The id of the annotation, generated by Confident AI.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI