Hoot Lens Heatmaps API

openapi: 3.2.0
info:
  title: Hoot Lens Heatmaps API
  version: v1
  summary: Read website interaction evidence and log changes.
  description: 'The Hoot Lens REST API records website interaction evidence for the sites you add and returns it as visits, recordings, heatmaps, goals, funnels and change impact. This document describes the endpoints a person or an agent uses to read that evidence and to log changes. Everything returned is observed behavior with its evidence; the API makes no claims about visitors'' emotions or intent.


    Authentication. Send `Authorization: Bearer `. The credential is either a Firebase ID token (a signed-in person, whose role on each site decides what they may do) or a personal access token (`hl_pat_...`) made in the dashboard. A personal access token carries the scopes `read`, `replay` and `annotate`, belongs to one site, expires in 30, 60 or 90 days, and can do no more than its creator''s current role allows. Operations marked `x-hootlens-sign-in-only` need a signed-in person and answer 403 to a token.


    OAuth. The hosted MCP endpoint (`/mcp`, Streamable HTTP) signs assistants in with OAuth 2.1 authorization code and PKCE (S256), with discovery at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`. Its access tokens (`hl_oat_...`) are bound to the MCP resource and are accepted only there; sending one to any route in this document answers 401. Use a personal access token or a Firebase ID token for these routes.


    Not described here. Collector intake, public tracker configuration, billing, OAuth, sharing links, issues and feedback, invitations, members, access tokens, notifications and the audit log also exist; see docs/API.md for them.


    Site (project) IDs are public. Authorization is enforced by the API on every request. Rate limits answer 429. A caller who is not a member of a site receives 404, so a site''s existence is not revealed.'
  contact:
    name: Parallel Platforms
    url: https://hootlens.com
servers:
- url: https://hootlens-api-368877148687.us-east1.run.app
  description: Production
security:
- bearerAuth: []
tags:
- name: Heatmaps
paths:
  /v1/projects/{projectId}/heatmaps:
    get:
      tags:
      - Heatmaps
      summary: List heatmap cohorts
      description: 'Heatmap cohorts, kept separate by page group, page version, revision and device class.


        Required token scopes are listed in x-hootlens-scopes. A signed-in person needs the matching permission on the site instead (the viewer and editor roles are presets of the permissions).'
      operationId: listHeatmaps
      parameters:
      - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: The cohorts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cohorts:
                    type: array
                    items:
                      $ref: '#/components/schemas/HeatmapCohortSummary'
                required:
                - cohorts
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
      x-hootlens-scopes:
      - read
  /v1/projects/{projectId}/heatmaps/{key}:
    get:
      tags:
      - Heatmaps
      summary: Get a heatmap
      description: 'Click density grid, pointer dwell, most-clicked elements and scroll depth for one cohort.


        Required token scopes are listed in x-hootlens-scopes. A signed-in person needs the matching permission on the site instead (the viewer and editor roles are presets of the permissions).'
      operationId: getHeatmap
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/heatmapKey'
      responses:
        '200':
          description: The heatmap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeatmapAggregate'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
      x-hootlens-scopes:
      - read
  /v1/projects/{projectId}/heatmaps/{key}/clicks:
    get:
      tags:
      - Heatmaps
      summary: Sampled clicks of a heatmap
      description: 'A uniform random sample of the cohort''s clicks, at most 2000. Recording IDs are included only for callers with the replay scope.


        Required token scopes are listed in x-hootlens-scopes. A signed-in person needs the matching permission on the site instead (the viewer and editor roles are presets of the permissions).'
      operationId: getHeatmapClicks
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/heatmapKey'
      - name: limit
        in: query
        required: false
        description: Most clicks to return.
        schema:
          type: integer
          minimum: 1
          maximum: 2000
          default: 2000
      responses:
        '200':
          description: The sampled clicks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeatmapClickSamples'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
      x-hootlens-scopes:
      - read
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: A short message safe to show to a person.
        code:
          type: string
          description: A stable machine-readable code, on some errors.
      required:
      - error
      additionalProperties: true
    DeviceClass:
      type: string
      enum:
      - desktop
      - tablet
      - mobile
    HeatmapCohortSummary:
      type: object
      properties:
        key:
          type: string
          description: Cohort key. URL-encode it to use as a path parameter.
        group:
          type: string
        path:
          type: string
        buildId:
          type: string
        pageVersion:
          type: string
        revision:
          type: string
        variant:
          type: string
        deviceClass:
          $ref: '#/components/schemas/DeviceClass'
        sessions:
          type: integer
        segments:
          type: integer
        clicks:
          type: integer
        lastSeenAt:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
        locales:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              segments:
                type: integer
              clicks:
                type: integer
            additionalProperties: true
        variants:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              segments:
                type: integer
              clicks:
                type: integer
            additionalProperties: true
      required:
      - key
      - path
      - buildId
      - revision
      - variant
      - deviceClass
      - sessions
      - segments
      - clicks
      - lastSeenAt
      additionalProperties: true
    HeatmapClickSamples:
      type: object
      properties:
        key:
          type: string
        total:
          type: integer
          description: Every click in the cohort, including any recorded before sampling began.
        capacity:
          type: integer
        clicks:
          type: array
          items:
            type: object
            properties:
              pageX:
                type: number
              pageY:
                type: number
              kind:
                type: string
                enum:
                - click
                - rage-click
                - dead-click
                - error-click
              timestamp:
                type: integer
                description: Epoch milliseconds.
                minimum: 0
              label:
                type: string
              selector:
                type: string
              referrer:
                type: string
              utmSource:
                type: string
              locale:
                type: string
              variant:
                type: string
              deviceClass:
                $ref: '#/components/schemas/DeviceClass'
              browser:
                type: string
              isNewVisitor:
                type: boolean
              recordingId:
                type: string
                description: Present only with the replay scope.
            required:
            - pageX
            - pageY
            - kind
            - timestamp
            - deviceClass
            additionalProperties: true
      required:
      - key
      - total
      - capacity
      - clicks
      additionalProperties: true
    HeatmapAggregate:
      allOf:
      - $ref: '#/components/schemas/HeatmapCohortSummary'
      - type: object
        properties:
          grid:
            type: object
            properties:
              cellSize:
                type: integer
              cells:
                type: array
                items:
                  type: array
                  items:
                    type: integer
                  minItems: 3
                  maxItems: 3
                description: Each cell is [column, row, count].
            required:
            - cellSize
            - cells
            additionalProperties: true
          docWidth:
            type: integer
          docHeight:
            type: integer
          moves:
            type: object
            properties:
              cellSize:
                type: integer
              cells:
                type: array
                items:
                  type: array
                  items:
                    type: number
                  minItems: 3
                  maxItems: 3
                description: Each cell is [column, row, weight]. Shows pointer position, not attention.
            required:
            - cellSize
            - cells
            additionalProperties: true
          selectors:
            type: array
            items:
              type: object
              properties:
                selector:
                  type: string
                label:
                  type: string
                name:
                  type: string
                  description: The name the team gave this element, when it has one.
                source:
                  type: string
                  description: Source file and line of the most recent click on this element in this cohort, such as `src/components/Pricing.tsx:42`, when the site uses the Hoot Lens build plugin.
                context:
                  $ref: '#/components/schemas/ElementContext'
                interactive:
                  type: boolean
                  enum:
                  - false
                  description: False when the element is not a link, button or other control. Absent otherwise.
                clicks:
                  type: integer
                rageClicks:
                  type: integer
                deadClicks:
                  type: integer
                errorClicks:
                  type: integer
              required:
              - selector
              - clicks
              - rageClicks
              - deadClicks
              - errorClicks
              additionalProperties: true
            description: Most-clicked elements, at most 200.
          scrollDepths:
            type: array
            items:
              type: number
            description: Share of page views reaching each 10% band of the page; index 0 is the top.
          reference:
            type: object
            properties:
              recordingId:
                type: string
              timestamp:
                type: integer
                description: Epoch milliseconds.
                minimum: 0
            additionalProperties: true
        required:
        - grid
        - docWidth
        - docHeight
        - moves
        - selectors
        - scrollDepths
        additionalProperties: true
    ElementContext:
      type: object
      description: Short context recorded with a click. The strict preset records tag and region only.
      properties:
        tag:
          type: string
          description: Tag of the clicked element, such as div, li, p or img.
        region:
          type: string
          description: 'The nearest region: a data-hoot-region, an ancestor data-hoot-id, a section with an id or aria-label, else the nearest landmark tag. At most 60 characters.'
        heading:
          type: string
          description: Text of the nearest h1 to h3 above the element. Full and balanced presets only; at most 60 characters.
        text:
          type: string
          description: The element's own text, shortened. Full and balanced presets only; at most 60 characters.
      additionalProperties: true
    Id:
      type: string
      description: 'An identifier: 1 to 80 letters, digits, underscores or hyphens.'
      pattern: ^[a-zA-Z0-9_-]{1,80}$
  parameters:
    heatmapKey:
      name: key
      in: path
      required: true
      description: A heatmap cohort key as returned by the heatmap list, URL-encoded. It is a JSON array naming the site (project), page group, page version, revision and device class.
      schema:
        type: string
        minLength: 1
        maxLength: 2000
    projectId:
      name: projectId
      in: path
      required: true
      description: The project ID. Project IDs are public identifiers, not secrets.
      schema:
        $ref: '#/components/schemas/Id'
  responses:
    Unauthorized:
      description: The credential is missing, expired or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The site, or the record inside it, does not exist or the caller is not a member (a non-member cannot tell the two apart).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: A rate limit or a per-site limit was reached.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request fields are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The credential or the person's permissions on the site do not permit this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A Firebase ID token, or a personal access token (hl_pat_...) with the scopes read, replay, annotate, configure, conversions:write. OAuth access tokens (hl_oat_...) are for the hosted MCP resource only.
externalDocs:
  description: Full API reference, including endpoints not described here
  url: https://hootlens.com/docs/API.md