Clarifeye Signals API
Submit signals about the project's content for domain experts to review
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-signals-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 API — Public Signals API
description: 'Forward-facing, supported REST API for new integrators of the Clarifeye Platform.
Covers the curated public surface: authentication, knowledge management
(documents), users & teams, signals, and tool execution. New integrations
should target these endpoints.
## Authentication
All endpoints require authentication. Include the Authorization header in every request using either format:
- `Authorization: Token `
- `Authorization: Bearer `'
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: Signals
description: Submit signals about the project's content for domain experts to review
paths:
/projects/{project_id}/signals/:
get:
tags:
- Signals
summary: List signals
description: 'Retrieve all signals for a project with optional filtering.
**Access Control:**
- Admins see all signals in the project
- Regular users see only signals they submitted
**Sorting:**
- Results are ordered by most recently updated first (`updated_at` field)
**Note:** For grouped views by conversation, use `/projects/{project_id}/signals/grouped_by_conversation/`'
operationId: listSignals
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: status
in: query
description: Filter by signal status
schema:
$ref: '#/components/schemas/SignalStatus'
- name: is_positive
in: query
description: Filter by sentiment
schema:
type: boolean
- name: search
in: query
description: Search in signal 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 signal objects
items:
$ref: '#/components/schemas/Signal'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
post:
tags:
- Signals
summary: Submit a signal
description: 'Submit a signal about the project''s content: the signal text itself,
plus optional `context.additional_details` with extra context for the
reviewer. The signal shows up in the review UI for domain experts.
## Signal Types
| Type | is_positive Value | Description |
|------|-------------------|-------------|
| Thumbs up | `true` | Positive signal |
| Thumbs down | `false` | Negative signal |
| Neutral | `null` | Neutral or no sentiment |'
operationId: submitSignal
parameters:
- $ref: '#/components/parameters/ProjectId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- context
properties:
feedback:
type: string
description: The signal text
example: We need to cover the EU refund rules in the knowledge base
context:
type: object
additionalProperties: true
properties:
additional_details:
type: string
description: 'Optional extra context provided alongside the signal.
Displayed in the review UI.'
is_positive:
type:
- boolean
- 'null'
description: '- `true`: Positive signal (thumbs up)
- `false`: Negative signal (thumbs down)
- `null`: Neutral signal
'
example: false
example:
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.
responses:
'201':
description: Signal submitted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Signal'
example:
id: 8f14e45f-ceea-467f-a8d9-23ad7f6b3a90
created_at: '2026-06-11T09:30:00Z'
updated_at: '2026-06-11T09:30:00Z'
given_by:
id: 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed
email: expert@example.com
status: to_review
feedback: We need to cover the EU refund rules in the knowledge base
context:
additional_details: Several customer calls last week asked about EU refunds and we had nothing to point them to.
is_positive: false
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/projects/{project_id}/signals/{signal_id}/:
patch:
tags:
- Signals
summary: Update signal status
description: 'Mark a signal as reviewed or update other fields.
**Access Control:**
- Admins can update any signal
- Regular users can only update signals they submitted'
operationId: updateSignal
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: signal_id
in: path
required: true
description: UUID of the signal
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/SignalStatus'
feedback:
type: string
description: Updated signal text
is_positive:
type:
- boolean
- 'null'
description: Updated sentiment
responses:
'200':
description: Signal updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Signal'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden - user does not own this signal
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'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
schemas:
ValidationError:
type: object
additionalProperties:
type: array
items:
type: string
example:
email:
- This field is required.
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: {}
Signal:
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 signal
properties:
id:
type: string
format: uuid
email:
type: string
format: email
status:
$ref: '#/components/schemas/SignalStatus'
feedback:
type: string
description: Signal text comment
context:
type: object
additionalProperties: true
description: Free-form context, echoed back as submitted at creation
properties:
additional_details:
type: string
description: Extra context provided alongside the signal
is_positive:
type:
- boolean
- 'null'
description: '- `true`: Positive signal
- `false`: Negative signal
- `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
SignalStatus:
type: string
enum:
- to_review
- reviewed
description: '- `to_review`: Signal pending review (default)
- `reviewed`: Signal has been reviewed
'
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>'