Update Form

PUThttps://api.confident-ai.com/v2/annotation-forms/{annotationFormId}

Updates an annotation form and returns it. Sending fields replaces the stored questions: a field sent with its id keeps the answers already recorded against it, and one left out is removed along with them.

PUT/v2/annotation-forms/{annotationFormId}

curl -X PUT "https://api.confident-ai.com/v2/annotation-forms/{annotationFormId}" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Answer quality review",
  "fields": [
    {
      "id": "<ANNOTATION-FORM-FIELD-ID>",
      "label": "How helpful was the answer?",
      "type": "TEXT",
      "description": "Judge only the answer, not the retrieved context.",
      "required": true,
      "order": 0,
      "selectOptions": [
        "Not helpful",
        "Somewhat helpful",
        "Very helpful"
      ],
      "criteriaName": "Helpfulness",
      "criteriaType": "FIVE_STAR_RATING",
      "collectExplanation": true,
      "collectExpectedOutput": false,
      "collectExpectedOutcome": false
    }
  ]
}'

200

{
  "success": true,
  "data": {
    "id": "<ANNOTATION-FORM-ID>",
    "name": "Answer quality review",
    "queueCount": 2,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-16T09:00:00.000Z",
    "fields": [
      {
        "id": "<ANNOTATION-FORM-FIELD-ID>",
        "label": "How helpful was the answer?",
        "type": "TEXT",
        "description": "Judge only the answer, not the retrieved context.",
        "required": true,
        "order": 0,
        "selectOptions": [
          "Not helpful",
          "Somewhat helpful",
          "Very helpful"
        ],
        "criteriaName": "Helpfulness",
        "criteriaType": "FIVE_STAR_RATING",
        "collectExplanation": true,
        "collectExpectedOutput": false,
        "collectExpectedOutcome": false
      }
    ]
  },
  "link": "https://app.confident-ai.com/project/<PROJECT-ID>/project-settings/annotation/<ANNOTATION-FORM-ID>",
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Path parameters

annotationFormIdstringRequired
The id of the annotation form.

Request body

namestring
The name of the form, shown wherever a queue offers it.
fieldslist of objects
The complete list of questions the form should carry. It replaces the stored fields: a field you send with its id keeps its recorded answers, and one you leave out is removed along with them.
Show 12 propertiesHide 12 properties
- idstring
  The id of an existing field to keep, which preserves the answers already recorded against it. Omit it for a new field and Confident AI assigns one.
- labelstringRequired
  The question shown to the annotator.
- typeenumRequired
  The kind of answer a form field collects: TEXT, NUMBER, FLOAT or BOOLEAN for a free answer, SELECT or MULTI_SELECT for a choice from selectOptions, and ANNOTATION_CRITERIA for a rating on the scale named by criteriaType.
  Show 7 enum valuesHide 7 enum values
  - TEXT
  - NUMBER
  - FLOAT
  - BOOLEAN
  - SELECT
  - MULTI_SELECT
  - ANNOTATION_CRITERIA
- descriptionstring | null
  Guidance shown under the question. Send null to clear it.
- requiredboolean
  Whether the annotator must answer this field before completing the item. Defaults to false.
- orderinteger
  The position of the field in the form. Defaults to the order the fields arrive in.
- selectOptionsarray | null
  The choices offered for a SELECT or MULTI_SELECT field. Required, and non-empty, for those two types; null for every other type.
- criteriaNamestring | null
  The criterion an ANNOTATION_CRITERIA field rates, matching a custom annotation option in this project. Null for every other type.
- criteriaTypeenum | null
  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
- collectExplanationboolean
  Whether an ANNOTATION_CRITERIA field also asks the annotator to explain the rating. Defaults to false.
- collectExpectedOutputboolean
  Whether an ANNOTATION_CRITERIA field on a trace or span form also asks for the output that should have been produced. Defaults to false.
- collectExpectedOutcomeboolean
  Whether an ANNOTATION_CRITERIA field on a thread form also asks for the outcome the conversation should have reached. Defaults to false.

Response

Update Form succeeded.

successboolean
Indicates if the request was successful.
dataobject
A form of questions asked of every item in the annotation queues it is attached to.
Show 6 propertiesHide 6 properties
- idstring
  The id of the form, generated by Confident AI.
- namestring
  The name of the form, shown wherever a queue offers it.
- queueCountinteger
  How many annotation queues currently use this form.
- createdAtstring
  When the form was created.
- updatedAtstring
  When the form was last changed.
- fieldslist of objects
  The questions on the form, in the order annotators see them.
  Show 12 propertiesHide 12 properties
  - idstring
    The id of the field, unique within the project.
  - labelstring
    The question shown to the annotator.
  - typeenum
    The kind of answer a form field collects: TEXT, NUMBER, FLOAT or BOOLEAN for a free answer, SELECT or MULTI_SELECT for a choice from selectOptions, and ANNOTATION_CRITERIA for a rating on the scale named by criteriaType.
    Show 7 enum valuesHide 7 enum values
    TEXT
    NUMBER
    FLOAT
    BOOLEAN
    SELECT
    MULTI_SELECT
    ANNOTATION_CRITERIA
  - descriptionstring | null
    Guidance shown under the question. Send null to clear it.
  - requiredboolean
    Whether the annotator must answer this field before completing the item. Defaults to false.
  - orderinteger
    The position of the field in the form. Defaults to the order the fields arrive in.
  - selectOptionsarray | null
    The choices offered for a SELECT or MULTI_SELECT field. Required, and non-empty, for those two types; null for every other type.
  - criteriaNamestring | null
    The criterion an ANNOTATION_CRITERIA field rates, matching a custom annotation option in this project. Null for every other type.
  - criteriaTypeenum | null
    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
  - collectExplanationboolean
    Whether an ANNOTATION_CRITERIA field also asks the annotator to explain the rating. Defaults to false.
  - collectExpectedOutputboolean
    Whether an ANNOTATION_CRITERIA field on a trace or span form also asks for the output that should have been produced. Defaults to false.
  - collectExpectedOutcomeboolean
    Whether an ANNOTATION_CRITERIA field on a thread form also asks for the outcome the conversation should have reached. Defaults to false.
linkstring
This is the URL of the resource on the Confident AI platform.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI