import requests

url = "https://eu.app.clarifeye.ai/api/v1/projects/{project_id}/feedbacks/"

payload = {
    "feedback": "We need to cover the EU refund rules in the knowledge base",
    "is_positive": False,
    "context": { "additional_details": "Several customer calls last week asked about EU refunds and we had nothing to point them to." }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "given_by": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "[email protected]"
  },
  "feedback": "<string>",
  "context": {
    "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "query_id": 123,
    "source": "<string>",
    "user_query": "<string>",
    "additional_details": "<string>"
  },
  "is_positive": true,
  "user_message": "<string>",
  "conversation_title": "<string>",
  "suggested_action_type": "<string>",
  "suggested_action_data": {}
}

{
  "error": "User not found"
}

{
  "error": "Authentication credentials were not provided."
}

{
  "error": "You do not have permission to perform this action."
}

Feedback

Submit feedback

Submit feedback. The simplest form is direct feedback about content: just the feedback text and optional context.additional_details, with no conversation attached. Feedback can also be linked to a playground conversation message, or submitted by an agent through MCP.

Impersonation:

When using impersonation, the feedback is submitted as the impersonated user

Feedback Types

Type	is_positive Value	Description
Thumbs up	`true`	Positive feedback
Thumbs down	`false`	Negative feedback
Neutral	`null`	Neutral or no sentiment

Query ID (conversation feedback only)

The query_id identifies a specific user query and all related responses. It can be obtained from:

The streaming response (each message contains query_id)
The streaming_completed event’s chat_history
The conversation retrieval endpoint

POST

projects

{project_id}

feedbacks

import requests

url = "https://eu.app.clarifeye.ai/api/v1/projects/{project_id}/feedbacks/"

payload = {
    "feedback": "We need to cover the EU refund rules in the knowledge base",
    "is_positive": False,
    "context": { "additional_details": "Several customer calls last week asked about EU refunds and we had nothing to point them to." }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "given_by": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "[email protected]"
  },
  "feedback": "<string>",
  "context": {
    "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "query_id": 123,
    "source": "<string>",
    "user_query": "<string>",
    "additional_details": "<string>"
  },
  "is_positive": true,
  "user_message": "<string>",
  "conversation_title": "<string>",
  "suggested_action_type": "<string>",
  "suggested_action_data": {}
}

{
  "error": "User not found"
}

{
  "error": "Authentication credentials were not provided."
}

{
  "error": "You do not have permission to perform this action."
}

Authorizations

Authorization

string

header

required

Use Authorization: Bearer

Headers

X-Impersonate-Email

string<email>

Email of the user to impersonate. Requires CAN_IMPERSONATE_OTHER_USERS permission. If the target user is not found or does not have access to the project, the request proceeds as the authenticated user. Contact Clarifeye to enable this permission.

Path Parameters

project_id

string<uuid>

required

UUID of the project

Body

application/json

context

Direct feedback · object

required

Feedback about content itself, not linked to a conversation. Just the feedback text plus optional additional details. Agents submitting through MCP set source=MCP and type=direct_feedback; plain API callers can omit both.

Direct feedback
Interaction feedback (MCP)
Conversation feedback

Show child attributes

feedback

string

Text comment (can be empty for quick feedback)

Example:

"We need to cover the EU refund rules in the knowledge base"

is_positive

boolean | null

true: Positive feedback (thumbs up)
false: Negative feedback (thumbs down)
null: Neutral feedback

Example:

true

Response

Feedback submitted successfully

string<uuid>

created_at

string<date-time>

updated_at

string<date-time>

given_by

object

User who submitted the feedback

Show child attributes

status

enum<string>

to_review: Feedback pending review (default)
reviewed: Feedback has been reviewed

Available options:

to_review,

reviewed

feedback

string

Feedback text comment

context

object

Free-form context, echoed back as submitted at creation. Conversation feedback carries conversation_id/query_id/source; MCP interaction feedback carries user_query; direct feedback may carry additional_details.

Show child attributes

is_positive

boolean | null

true: Positive feedback
false: Negative feedback
null: Neutral

user_message

string

The user message that was responded to (computed field)

conversation_title

string

Title of the conversation (computed field)

suggested_action_type

string | null

Auto-generated suggested action type

suggested_action_data

object

Auto-generated suggested action data

List feedback Delete feedback

Concepts

Endpoints

Submit feedback

Feedback Types

Query ID (conversation feedback only)

Authorizations

Headers

Path Parameters

Body

Response