Clarity Highlights API

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