Clarity Highlights API
The highlights API from Clarity — 3 operation(s) for highlights.
The highlights API from Clarity — 3 operation(s) for highlights.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/onclarity-com:onclarity-com-highlights-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a 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: 3.2.0
info:
title: Fast Highlights API
version: 0.1.0
tags:
- name: highlights
paths:
/api/v1/highlights/marks:
get:
tags:
- highlights
summary: List Marks
description: 'Every highlighted entity in one project, with the caller''s own state (``mine``) and who
else highlighted it — what the 🔥 toggles on that project''s pages render from.'
operationId: list_marks_api_v1_highlights_marks_get
security:
- HTTPBearer: []
parameters:
- name: project_id
in: query
required: true
schema:
type: integer
exclusiveMinimum: 0
title: Project Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MarksResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/highlights:
get:
tags:
- highlights
summary: Get Feed
description: 'The Highlights page: everything any admin has highlighted, in every project, newest
highlight first — as cards (title, subtitle, badges, owner, the path that opens it).'
operationId: get_feed_api_v1_highlights_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FeedResponse'
security:
- HTTPBearer: []
put:
tags:
- highlights
summary: Set Highlight
description: 'Highlight or un-highlight one entity for the caller — a row of their own, so no other
admin''s highlight is touched. Idempotent. An unknown entity, one that is deleted or hidden
(when highlighting), or one outside ``project_id`` is a uniform 404 with nothing written.'
operationId: set_highlight_api_v1_highlights_put
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/HighlightToggleRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MarkResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/api/v1/highlights/reason:
patch:
tags:
- highlights
summary: Update Reason
description: Save or clear the caller's reason. Missing highlights/targets are 404, never inserted.
operationId: update_reason_api_v1_highlights_reason_patch
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/HighlightReasonRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MarkResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
MarksResponse:
properties:
marks:
items:
$ref: '#/components/schemas/MarkResponse'
type: array
title: Marks
type: object
required:
- marks
title: MarksResponse
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
FeedItemResponse:
properties:
entity_type:
$ref: '#/components/schemas/HighlightEntityType'
entity_ref:
type: string
title: Entity Ref
description: 'What the product calls the entity: its id, or a mini-app''s slug'
mine:
type: boolean
title: Mine
description: Whether the CALLER has highlighted it (what their 🔥 shows)
count:
type: integer
title: Count
description: How many admins have highlighted it
highlighted_by:
items:
$ref: '#/components/schemas/HighlighterResponse'
type: array
title: Highlighted By
description: Every admin who did, first one first
project:
$ref: '#/components/schemas/ProjectRefResponse'
title:
type: string
title: Title
subtitle:
anyOf:
- type: string
- type: 'null'
title: Subtitle
badges:
items:
type: string
type: array
title: Badges
owner_name:
anyOf:
- type: string
- type: 'null'
title: Owner Name
description: Who made the entity, when known
path:
type: string
title: Path
description: Relative UI path that opens the entity in its project
latest_highlighted_at:
type: string
format: date-time
title: Latest Highlighted At
type: object
required:
- entity_type
- entity_ref
- mine
- count
- highlighted_by
- project
- title
- path
- latest_highlighted_at
title: FeedItemResponse
description: One highlighted entity on the Highlights page.
HighlighterResponse:
properties:
user_id:
type: integer
title: User Id
description: The admin who highlighted it
name:
type: string
title: Name
description: Their display name (full name, else email)
highlighted_at:
type: string
format: date-time
title: Highlighted At
reason:
anyOf:
- type: string
- type: 'null'
title: Reason
type: object
required:
- user_id
- name
- highlighted_at
title: HighlighterResponse
HighlightEntityType:
type: string
enum:
- dashboard
- copilot_conversation
- mini_app
- widget
- collection
- operator
- routine
- source
- notification_v1
- notification_v2
- survey
title: HighlightEntityType
description: 'Which table ``admin_highlights.entity_id`` points into.
Stored as TEXT (no PG enum, no CHECK — the API is the only writer), so a new kind is a
code change: a value here plus its spec in ``entities.py``.'
HighlightReasonRequest:
properties:
entity_type:
$ref: '#/components/schemas/HighlightEntityType'
entity_ref:
type: string
maxLength: 64
minLength: 1
title: Entity Ref
project_id:
type: integer
exclusiveMinimum: 0.0
title: Project Id
reason:
anyOf:
- type: string
maxLength: 500
- type: 'null'
title: Reason
type: object
required:
- entity_type
- entity_ref
- project_id
- reason
title: HighlightReasonRequest
description: Edit only the caller's existing highlight; never create one as a side effect.
FeedResponse:
properties:
items:
items:
$ref: '#/components/schemas/FeedItemResponse'
type: array
title: Items
type: object
required:
- items
title: FeedResponse
HighlightToggleRequest:
properties:
entity_type:
$ref: '#/components/schemas/HighlightEntityType'
entity_ref:
type: string
maxLength: 64
minLength: 1
title: Entity Ref
description: The entity's id, or a mini-app's slug
project_id:
type: integer
exclusiveMinimum: 0.0
title: Project Id
description: The project the entity lives in
highlighted:
type: boolean
title: Highlighted
type: object
required:
- entity_type
- entity_ref
- project_id
- highlighted
title: HighlightToggleRequest
description: 'Highlight or un-highlight one entity for the caller. A toggle on ONE entity rather than a
replace of a set, so two tabs acting on different entities never overwrite each other.'
MarkResponse:
properties:
entity_type:
$ref: '#/components/schemas/HighlightEntityType'
entity_ref:
type: string
title: Entity Ref
description: 'What the product calls the entity: its id, or a mini-app''s slug'
mine:
type: boolean
title: Mine
description: Whether the CALLER has highlighted it (what their 🔥 shows)
count:
type: integer
title: Count
description: How many admins have highlighted it
highlighted_by:
items:
$ref: '#/components/schemas/HighlighterResponse'
type: array
title: Highlighted By
description: Every admin who did, first one first
type: object
required:
- entity_type
- entity_ref
- mine
- count
- highlighted_by
title: MarkResponse
description: Who has highlighted one entity, as the caller sees it.
ProjectRefResponse:
properties:
id:
type: integer
title: Id
name:
type: string
title: Name
type: object
required:
- id
- name
title: ProjectRefResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
HTTPBasic:
type: http
scheme: basic