Clarifeye Feedback API
Submit feedback on conversation messages
OpenAPI Specification
openapi: 3.0.3
info:
title: Clarifeye Platform Agent Settings Feedback API
description: 'REST API for the Clarifeye Platform - Document intelligence and AI-powered analysis.
## Authentication
All endpoints require authentication. Include the Authorization header in every request using either format:
- `Authorization: Token <token_key>`
- `Authorization: Bearer <token_key>`
## Impersonation
Certain endpoints support user impersonation for creating or listing data on behalf of other users.
This is useful for integrating external systems that need to attribute actions to specific users.
**Header:** `X-Impersonate-Email`
**Required Permission:** `CAN_IMPERSONATE_OTHER_USERS` (contact Clarifeye to enable this permission)
**Behavior:**
- If the header is provided and the impersonator has the required permission, the action is performed as the target user
- If the target user is not found, the request proceeds as the original authenticated user
- If the target user does not have access to the project, the request proceeds as the original authenticated user
- If the impersonator lacks the `CAN_IMPERSONATE_OTHER_USERS` permission, the header is ignored
'
version: 1.0.0
contact:
name: Clarifeye Support
servers:
- url: https://eu.app.clarifeye.ai/api/v1
description: EU
- url: https://us.app.clarifeye.ai/api/v1
description: US
security:
- BearerAuth: []
- TokenAuth: []
tags:
- name: Feedback
description: Submit feedback on conversation messages
paths:
/projects/{project_id}/feedbacks/:
get:
tags:
- Feedback
summary: List feedback
description: 'Retrieve all feedback for a project with optional filtering.
**Access Control:**
- Admins see all feedback in the project
- Regular users see only feedback they submitted
**Impersonation:**
- When using impersonation, returns feedback submitted by the impersonated user
**Sorting:**
- Results are ordered by most recently updated first (`updated_at` field)
**Note:** For grouped views by conversation, use `/projects/{project_id}/feedbacks/grouped_by_conversation/`
'
operationId: listFeedback
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/ImpersonateEmail'
- name: status
in: query
description: Filter by feedback status
schema:
$ref: '#/components/schemas/FeedbackStatus'
- name: is_positive
in: query
description: Filter by sentiment
schema:
type: boolean
- name: search
in: query
description: Search in feedback text or user email (case-insensitive)
schema:
type: string
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- type: object
properties:
results:
type: array
description: Array of Feedback objects
items:
$ref: '#/components/schemas/Feedback'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
post:
tags:
- Feedback
summary: Submit feedback on a message
description: 'Provide feedback on a specific message in a conversation.
**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
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
'
operationId: submitFeedback
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/ImpersonateEmail'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- context
properties:
feedback:
type: string
description: Text comment (can be empty for quick feedback)
example: This answer was helpful and accurate
context:
type: object
required:
- conversation_id
- query_id
- source
properties:
conversation_id:
type: string
format: uuid
description: ID of the conversation
query_id:
type: integer
description: Query ID of the message to provide feedback on
example: 0
source:
type: string
enum:
- PlaygroundConversation
description: Source of the feedback
is_positive:
type: boolean
nullable: true
description: '- `true`: Positive feedback (thumbs up)
- `false`: Negative feedback (thumbs down)
- `null`: Neutral feedback
'
example: true
responses:
'201':
description: Feedback submitted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Feedback'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/projects/{project_id}/feedbacks/{feedback_id}/:
patch:
tags:
- Feedback
summary: Update feedback status
description: 'Mark feedback as reviewed or update other fields.
**Access Control:**
- Admins can update any feedback
- Regular users can only update feedback they submitted
**Impersonation:**
- When using impersonation, the ownership check is performed against the impersonated user
- This allows updating feedback submitted by the impersonated user
'
operationId: updateFeedback
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: feedback_id
in: path
required: true
description: UUID of the feedback
schema:
type: string
format: uuid
- $ref: '#/components/parameters/ImpersonateEmail'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/FeedbackStatus'
feedback:
type: string
description: Updated feedback text
is_positive:
type: boolean
nullable: true
description: Updated sentiment
responses:
'200':
description: Feedback updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Feedback'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden - user does not own this feedback
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
$ref: '#/components/responses/NotFound'
delete:
tags:
- Feedback
summary: Delete feedback
description: 'Remove feedback.
**Access Control:**
- Admins can delete any feedback
- Regular users can only delete feedback they submitted
**Impersonation:**
- When using impersonation, the ownership check is performed against the impersonated user
- This allows deleting feedback submitted by the impersonated user
'
operationId: deleteFeedback
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: feedback_id
in: path
required: true
description: UUID of the feedback
schema:
type: string
format: uuid
- $ref: '#/components/parameters/ImpersonateEmail'
responses:
'204':
description: Feedback deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden - user does not own this feedback
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
$ref: '#/components/responses/NotFound'
/projects/{project_id}/feedbacks/grouped_by_conversation/:
get:
tags:
- Feedback
summary: Get feedbacks grouped by conversation
description: 'Retrieve feedbacks grouped by their associated playground conversation with unified pagination and sorting.
**Access Control:**
- Admins see all feedback in the project
- Regular users see only feedback they submitted
**Grouping Logic:**
- Feedbacks are grouped by their `conversation` field (FK to PlaygroundConversation)
- Conversation groups and ungrouped feedbacks are returned in a single flat array
- Ungrouped feedbacks appear as single-item groups with `conversation_id: null`
- Each group includes status counts and all associated feedbacks
**Pagination:**
- Paginates across the unified list of conversation groups and ungrouped feedbacks
- Use `limit` and `offset` parameters to page through results
- The `count` field reflects the total number of displayable groups (conversations + ungrouped)
**Status Filtering:**
- `status=to_review`: Groups with ANY unreviewed feedback
- `status=reviewed`: Groups where ALL feedbacks are reviewed
- No status filter: All groups
**Sorting:**
- All groups are sorted together by the most recent feedback update time
- With `status=to_review`: Sorted by the most recent "to_review" feedback update
- With `status=reviewed`: Sorted by the most recent "reviewed" feedback update
- Without status filter: Sorted by the most recent feedback update (any status)
- Feedbacks within each group are ordered by most recently updated first
**Impersonation:**
- When using impersonation, returns feedback submitted by the impersonated user
'
operationId: getGroupedFeedbacks
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/ImpersonateEmail'
- name: status
in: query
description: Filter by conversation status (based on feedback statuses)
schema:
$ref: '#/components/schemas/FeedbackStatus'
- name: search
in: query
description: Search in feedback text or user email (case-insensitive)
schema:
type: string
- name: include_archived
in: query
description: Set to "true" to include feedbacks from archived conversations. Defaults to false.
schema:
type: string
enum:
- 'true'
- 'false'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- type: object
properties:
results:
type: array
description: 'Flat array of conversation groups and ungrouped feedbacks, sorted by last updated feedback.
Ungrouped feedbacks appear as single-item groups with `conversation_id: null`.
'
items:
$ref: '#/components/schemas/ConversationFeedbackGroup'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/projects/{project_id}/feedbacks/mark_conversation_reviewed/:
post:
tags:
- Feedback
summary: Mark all feedbacks in a conversation as reviewed
description: 'Update the status of all feedbacks associated with a specific conversation to "reviewed".
**Access Control:**
- Admins can update all feedbacks in the project
- Regular users can only update feedback they submitted
**Impersonation:**
- When using impersonation, only updates feedback submitted by the impersonated user
'
operationId: markConversationReviewed
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/ImpersonateEmail'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- conversation_id
properties:
conversation_id:
type: string
format: uuid
description: ID of the conversation whose feedbacks should be marked as reviewed
example: 123e4567-e89b-12d3-a456-426614174000
example:
conversation_id: 123e4567-e89b-12d3-a456-426614174000
responses:
'200':
description: Feedbacks updated successfully
content:
application/json:
schema:
type: object
properties:
updated_count:
type: integer
description: Number of feedbacks updated
example: 3
conversation_id:
type: string
format: uuid
description: ID of the conversation whose feedbacks were updated
example: 123e4567-e89b-12d3-a456-426614174000
new_status:
type: string
description: The new status that was applied to the feedbacks
example: reviewed
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/projects/{project_id}/feedbacks/counts/:
get:
tags:
- Feedback
summary: Get feedback counts by status
description: 'Retrieve comprehensive counts of feedbacks split by status, conversation grouping, and ungrouped feedbacks.
**Access Control:**
- Admins see counts for all feedback in the project
- Regular users see counts only for feedback they submitted
**Impersonation:**
- When using impersonation, returns counts for feedback submitted by the impersonated user
'
operationId: getFeedbackCounts
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/ImpersonateEmail'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
to_review:
type: integer
description: Total count of individual feedbacks with status "to_review"
example: 28
reviewed:
type: integer
description: Total count of individual feedbacks with status "reviewed"
example: 45
conversations_to_review:
type: integer
description: Count of conversations with at least one unreviewed feedback
example: 12
conversations_reviewed:
type: integer
description: Count of conversations where ALL feedbacks are reviewed
example: 8
ungrouped_to_review:
type: integer
description: Count of feedbacks without a conversation that are "to_review"
example: 4
ungrouped_reviewed:
type: integer
description: Count of feedbacks without a conversation that are "reviewed"
example: 2
examples:
ungrouped:
summary: Individual feedback counts
value:
to_review: 8
reviewed: 15
grouped:
summary: Conversation counts
value:
to_review: 3
reviewed: 7
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
components:
responses:
BadRequest:
description: Bad request - invalid parameters or request body
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/ValidationError'
Forbidden:
description: Forbidden - insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: You do not have permission to perform this action.
Unauthorized:
description: Unauthorized - missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Authentication credentials were not provided.
NotFound:
description: Not found - resource does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Not found.
parameters:
Limit:
name: limit
in: query
description: Maximum number of results per page
schema:
type: integer
default: 100
minimum: 1
maximum: 1000
Offset:
name: offset
in: query
description: Number of results to skip for pagination
schema:
type: integer
default: 0
minimum: 0
ImpersonateEmail:
name: X-Impersonate-Email
in: header
required: false
description: '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.
'
schema:
type: string
format: email
ProjectId:
name: project_id
in: path
required: true
description: UUID of the project
schema:
type: string
format: uuid
schemas:
ConversationFeedbackGroup:
type: object
description: A group of feedbacks from the same playground conversation
properties:
conversation_id:
type: string
format: uuid
description: ID of the playground conversation
conversation_title:
type: string
description: Title of the conversation
example: Product pricing discussion
conversation_created_at:
type: string
format: date-time
description: When the conversation was created
agent_name:
type: string
nullable: true
description: Name of the agent settings used in this conversation
example: Customer Support Assistant
conversation_is_archived:
type: boolean
description: Whether the associated conversation is archived
default: false
to_review_count:
type: integer
description: Number of feedbacks with status "to_review" in this conversation
example: 3
reviewed_count:
type: integer
description: Number of feedbacks with status "reviewed" in this conversation
example: 1
feedbacks:
type: array
description: All feedbacks from this conversation, ordered by most recently updated first (by `updated_at` field)
items:
$ref: '#/components/schemas/Feedback'
example:
conversation_id: 123e4567-e89b-12d3-a456-426614174000
conversation_title: Product pricing discussion
conversation_created_at: '2026-03-01T10:30:00Z'
agent_name: Customer Support Assistant
conversation_is_archived: false
to_review_count: 3
reviewed_count: 1
feedbacks:
- id: abc-123
status: to_review
feedback: The answer was inaccurate
is_positive: false
- id: abc-124
status: to_review
feedback: This needs more detail
is_positive: false
- id: abc-125
status: to_review
feedback: Missing citation for this claim
is_positive: false
- id: abc-126
status: reviewed
feedback: Great explanation!
is_positive: true
status_summary: mixed
feedback_count: 4
latest_updated_at: '2026-02-26T10:30:00Z'
has_unreviewed: true
ValidationError:
type: object
additionalProperties:
type: array
items:
type: string
example:
email:
- This field is required.
FeedbackStatus:
type: string
enum:
- to_review
- reviewed
description: '- `to_review`: Feedback pending review (default)
- `reviewed`: Feedback has been reviewed
'
PaginatedResponse:
type: object
properties:
count:
type: integer
description: Total number of results
next:
type: string
format: uri
nullable: true
description: URL to next page of results
previous:
type: string
format: uri
nullable: true
description: URL to previous page of results
results:
type: array
items: {}
Error:
type: object
properties:
error:
type: string
description: Error message
example:
error: User not found
Feedback:
type: object
properties:
id:
type: string
format: uuid
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
given_by:
type: object
description: User who submitted the feedback
properties:
id:
type: string
format: uuid
email:
type: string
format: email
status:
$ref: '#/components/schemas/FeedbackStatus'
feedback:
type: string
description: Feedback text comment
context:
type: object
description: Legacy context object (conversation_id is now available as a direct field)
properties:
conversation_id:
type: string
format: uuid
deprecated: true
description: Use the top-level `conversation` field instead
query_id:
type: integer
source:
type: string
is_positive:
type: boolean
nullable: true
description: '- `true`: Positive feedback
- `false`: Negative feedback
- `null`: Neutral
'
user_message:
type: string
description: The user message that was responded to (computed field)
conversation_title:
type: string
description: Title of the conversation (computed field)
suggested_action_type:
type: string
nullable: true
description: Auto-generated suggested action type
suggested_action_data:
type: object
description: Auto-generated suggested action data
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'Use Authorization: Bearer <token>'
TokenAuth:
type: apiKey
in: header
name: Authorization
description: 'Use Authorization: Token <token>'