Clarifeye Feedback API
Submit feedback on conversation messages
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/clarifeye-feedback-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Clarifeye Platform Feedback API
description: REST API for the Clarifeye Platform - Document intelligence and AI-powered analysis.
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
- 'null'
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
- 'null'
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:
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
ProjectId:
name: project_id
in: path
required: true
description: UUID of the project
schema:
type: string
format: uuid
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
schemas:
ValidationError:
type: object
additionalProperties:
type: array
items:
type: string
example:
email:
- This field is required.
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
- 'null'
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
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
- 'null'
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
- 'null'
description: Auto-generated suggested action type
suggested_action_data:
type: object
description: Auto-generated suggested action data
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
- 'null'
format: uri
description: URL to next page of results
previous:
type:
- string
- 'null'
format: uri
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
responses:
BadRequest:
description: Bad request - invalid parameters or request body
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/ValidationError'
NotFound:
description: Not found - resource does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Not found.
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.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'Use Authorization: Bearer <token>'
TokenAuth:
type: apiKey
in: header
name: Authorization
description: 'Use Authorization: Token <token>'