Create Annotation

(v2)

POST

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.",
  "fieldType": "TEXT",
  "value": true,
  "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
An annotation 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.
- fieldTypeenum
  The kind of value an annotation holds: TEXT, NUMBER, FLOAT or BOOLEAN for a free value, CHOICE or MULTIPLE_CHOICE for a choice from the options in the field's config, and THUMBS_RATING or FIVE_STAR_RATING for a rating.
  Show 8 enum valuesHide 8 enum values
  - TEXT
  - NUMBER
  - FLOAT
  - BOOLEAN
  - CHOICE
  - MULTIPLE_CHOICE
  - FIVE_STAR_RATING
  - THUMBS_RATING
- valuestring | number | boolean | list of stringsRequired
  The annotated value, in the shape its fieldType expects: a boolean for THUMBS_RATING (true is thumbs up) and BOOLEAN, a whole number from 1 to 5 for FIVE_STAR_RATING, a number for NUMBER or FLOAT, a string for TEXT and CHOICE, and a list of strings for MULTIPLE_CHOICE.
  Show 4 variantsHide 4 variants
  - string
  - OR
  - number
  - OR
  - boolean
  - OR
  - list of strings
- namestring
  A name for what this annotation is for. Omit it for the default annotation.
- explanationstring
  Why the annotation was given.
- userIdstring
  The id of the end user this annotation came from, when it 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
An annotation 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.
- fieldTypeenum
  The kind of value an annotation holds: TEXT, NUMBER, FLOAT or BOOLEAN for a free value, CHOICE or MULTIPLE_CHOICE for a choice from the options in the field's config, and THUMBS_RATING or FIVE_STAR_RATING for a rating.
  Show 8 enum valuesHide 8 enum values
  - TEXT
  - NUMBER
  - FLOAT
  - BOOLEAN
  - CHOICE
  - MULTIPLE_CHOICE
  - FIVE_STAR_RATING
  - THUMBS_RATING
- valuestring | number | boolean | list of stringsRequired
  The annotated value, in the shape its fieldType expects: a boolean for THUMBS_RATING (true is thumbs up) and BOOLEAN, a whole number from 1 to 5 for FIVE_STAR_RATING, a number for NUMBER or FLOAT, a string for TEXT and CHOICE, and a list of strings for MULTIPLE_CHOICE.
  Show 4 variantsHide 4 variants
  - string
  - OR
  - number
  - OR
  - boolean
  - OR
  - list of strings
- namestring
  A name for what this annotation is for. Omit it for the default annotation.
- explanationstring
  Why the annotation was given.
- userIdstring
  The id of the end user this annotation came from, when it 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
An annotation 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.
- fieldTypeenum
  The kind of value an annotation holds: TEXT, NUMBER, FLOAT or BOOLEAN for a free value, CHOICE or MULTIPLE_CHOICE for a choice from the options in the field's config, and THUMBS_RATING or FIVE_STAR_RATING for a rating.
  Show 8 enum valuesHide 8 enum values
  - TEXT
  - NUMBER
  - FLOAT
  - BOOLEAN
  - CHOICE
  - MULTIPLE_CHOICE
  - FIVE_STAR_RATING
  - THUMBS_RATING
- valuestring | number | boolean | list of stringsRequired
  The annotated value, in the shape its fieldType expects: a boolean for THUMBS_RATING (true is thumbs up) and BOOLEAN, a whole number from 1 to 5 for FIVE_STAR_RATING, a number for NUMBER or FLOAT, a string for TEXT and CHOICE, and a list of strings for MULTIPLE_CHOICE.
  Show 4 variantsHide 4 variants
  - string
  - OR
  - number
  - OR
  - boolean
  - OR
  - list of strings
- namestring
  A name for what this annotation is for. Omit it for the default annotation.
- explanationstring
  Why the annotation was given.
- userIdstring
  The id of the end user this annotation came from, when it 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