Skip to content

Human Feedback REST API

This API supports creating and updating human feedback records for both live chatbot integrations and annotation tools. It requires a bearer token for authentication.

1. Create New Record (Live Chatbot Integration)

1.1 Endpoint

POST <API_HOST>/feedback-record

1.2 Description

Creates a new feedback record with a nested response. Ideal for capturing immediate user feedback in live chatbot scenarios.

1.3 Authentication

Authorization: Bearer <API_KEY>

1.4 Request Body

  • record (object, required) – Contains:
    • feedback_dataset_id (string, required) – The ID of the feedback dataset.
    • field_to_value (object, required) – Maps dataset field names to actual values.
  • response (object, required) – Contains:
    • values (object, required) – Key-value pairs matching question names defined in the dataset.

1.5 Example Request

{
  "record": {
    "field_to_value": {
      "prompt": "Hello",
      "response_1": "Hello! How can I assist you today?",
      "response_2": "Hello! What do you want?"
    },
    "feedback_dataset_id": "datasetABC"
  },
  "response": {
    "values": {
      "question_ranking": [
        "response_2",
        "response_1"
      ]
    }
  }
}

1.6 Responses

  • 200 OK – Successfully created the feedback record.
  • 400 Bad Request – Missing or invalid fields.

1.7 Notes

  • A newly created record has a default status of "submitted".
  • response.values keys match question names in the dataset.
  • record.field_to_value keys match the dataset’s defined fields.

2. Update Feedback Response (Annotation Tool Integration)

2.1 Endpoint

POST <API_HOST>/feedback-response

2.2 Description

Adds or updates a feedback response for an existing record. Useful in annotation tools where multiple annotators can review the same record.

2.3 Authentication

Authorization: Bearer <API_KEY>

2.4 Request Body

  • feedback_record_id (string, required) – ID of the record to update.
  • response (object, required):
    • status (string, required) – Must be "draft", "submitted", or "discarded".
    • values (object, required) – Key-value pairs representing the updated response data.

2.5 Example Request

{
  "feedback_record_id": "record123",
  "response": {
    "status": "submitted",
    "values": {
      "rating": 5,
      "comments": "Great service!"
    }
  }
}

2.6 Responses

  • 200 OK – Successfully updated the feedback response.
  • 400 Bad Request – Missing or invalid fields.

Next Steps