Hoot Lens Changes API

openapi: 3.2.0
info:
  title: Hoot Lens Changes 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: Changes
paths:
  /v1/projects/{projectId}/changes:
    get:
      tags:
      - Changes
      summary: List change markers
      description: 'Logged changes, newest first. A page group filter also returns markers that name no group, which changed every page.


        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: listChanges
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/from'
      - $ref: '#/components/parameters/to'
      - name: pageGroup
        in: query
        required: false
        description: A page group name, ID, homepage or a path such as /pricing.
        schema:
          type: string
          minLength: 1
          maxLength: 300
      - name: limit
        in: query
        required: false
        description: Most markers to return.
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 200
      responses:
        '200':
          description: The markers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  changes:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChangeMarker'
                required:
                - changes
                additionalProperties: true
        '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
    post:
      tags:
      - Changes
      summary: Log a change
      description: 'Records that something on the site changed at a time, optionally for one page group. A marker made with a personal access token is recorded as made by an agent. At most 60 a minute.


        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: createChange
      parameters:
      - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeInput'
      responses:
        '201':
          description: The new marker.
          content:
            application/json:
              schema:
                type: object
                properties:
                  change:
                    $ref: '#/components/schemas/ChangeMarker'
                required:
                - change
                additionalProperties: true
        '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:
      - annotate
  /v1/projects/{projectId}/changes/{changeId}:
    delete:
      tags:
      - Changes
      summary: Delete a change marker
      description: 'A token may remove only markers an agent logged, never one the owner wrote by hand (403).


        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: deleteChange
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/changeId'
      responses:
        '204':
          description: Deleted.
        '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:
      - annotate
  /v1/projects/{projectId}/changes/{changeId}/impact:
    get:
      tags:
      - Changes
      summary: Impact of a change
      description: 'Before and after comparison around a change: visits, goal conversion rates, snags per 100 page views, scroll reach and element click shares, with a one-sentence summary and caveats. This is not an A/B test.


        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: getChangeImpact
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/changeId'
      - name: days
        in: query
        required: false
        description: Days each side runs at most.
        schema:
          type: integer
          minimum: 1
          maximum: 45
      - $ref: '#/components/parameters/deviceClass'
      - $ref: '#/components/parameters/locale'
      responses:
        '200':
          description: The impact report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImpactReport'
        '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:
    ChangeInput:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 120
        note:
          type: string
          minLength: 1
          maxLength: 1000
        pageGroup:
          type: string
          minLength: 1
          maxLength: 300
        release:
          type: string
          minLength: 1
          maxLength: 100
        at:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        source:
          type: string
          minLength: 1
          maxLength: 60
        kind:
          type: string
          enum:
          - standard
          - measurement
        commit:
          type: object
          properties:
            sha:
              type: string
              pattern: ^[0-9a-fA-F]{7,64}$
            url:
              type: string
              maxLength: 500
              pattern: ^https:\/\/[^\s@]+$
          required:
          - sha
      required:
      - title
    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
    ImpactReport:
      type: object
      properties:
        change:
          $ref: '#/components/schemas/ChangeMarker'
        days:
          type: integer
        filters:
          type: object
          properties:
            deviceClass:
              $ref: '#/components/schemas/DeviceClass'
            locale:
              type: string
          additionalProperties: true
        goals:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
            required:
            - id
            - name
            additionalProperties: true
        measurementOnly:
          type: boolean
          description: 'True when the change only changed counting: goal verdicts are counting-changed and no rise or fall is claimed.'
        groups:
          type: array
          items:
            type: object
            properties:
              group:
                type: string
              name:
                type: string
              before:
                type: object
                properties:
                  window:
                    type: object
                    properties: {}
                    additionalProperties: true
                  visits:
                    type: integer
                additionalProperties: true
              after:
                type: object
                properties:
                  window:
                    type: object
                    properties: {}
                    additionalProperties: true
                  visits:
                    type: integer
                additionalProperties: true
              needMore:
                type: object
                properties:
                  before:
                    type: integer
                  after:
                    type: integer
                additionalProperties: true
              goals:
                type: array
                items:
                  type: object
                  properties: {}
                  additionalProperties: true
              snagsPer100:
                type: object
                properties:
                  before:
                    oneOf:
                    - type: number
                    - type: 'null'
                  after:
                    oneOf:
                    - type: number
                    - type: 'null'
                  snagsBefore:
                    type: integer
                  snagsAfter:
                    type: integer
                additionalProperties: true
              scrollReach:
                type: object
                properties: {}
                additionalProperties: true
              elements:
                type: object
                properties: {}
                additionalProperties: true
            required:
            - group
            - name
            - before
            - after
            additionalProperties: true
        summary:
          type: string
          description: One sentence with the observed numbers and sample sizes.
        caveats:
          type: array
          items:
            type: string
            description: What the numbers cannot say.
        generatedAt:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
      required:
      - change
      - days
      - filters
      - goals
      - groups
      - summary
      - caveats
      - generatedAt
      additionalProperties: true
    Id:
      type: string
      description: 'An identifier: 1 to 80 letters, digits, underscores or hyphens.'
      pattern: ^[a-zA-Z0-9_-]{1,80}$
    ChangeMarker:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        projectId:
          $ref: '#/components/schemas/Id'
        at:
          type: integer
          description: When the change went live, epoch milliseconds.
          minimum: 0
        title:
          type: string
        note:
          type: string
        pageGroup:
          type: string
          description: Absent means the whole site.
        release:
          type: string
        createdBy:
          type: string
          enum:
          - owner
          - agent
        source:
          type: string
          description: 'Free text such as claude-code. Starts with auto: for automatic detections.'
        kind:
          type: string
          enum:
          - standard
          - measurement
          description: measurement for a change that only changes how counting works; its impact report gives no verdict. Absent means standard.
      required:
      - id
      - projectId
      - at
      - title
      - createdBy
      additionalProperties: true
  parameters:
    deviceClass:
      name: deviceClass
      in: query
      required: false
      description: Device class. Viewports are bucketed by device class, never by exact pixel size.
      schema:
        $ref: '#/components/schemas/DeviceClass'
    to:
      name: to
      in: query
      required: false
      description: End of the range, epoch milliseconds. Defaults to now.
      schema:
        type: integer
        minimum: 0
    projectId:
      name: projectId
      in: path
      required: true
      description: The project ID. Project IDs are public identifiers, not secrets.
      schema:
        $ref: '#/components/schemas/Id'
    from:
      name: from
      in: query
      required: false
      description: Start of the range, epoch milliseconds. Counts are daily, so the range covers every UTC day it touches.
      schema:
        type: integer
        minimum: 0
    changeId:
      name: changeId
      in: path
      required: true
      description: A change marker ID.
      schema:
        $ref: '#/components/schemas/Id'
    locale:
      name: locale
      in: query
      required: false
      description: Primary language code such as es.
      schema:
        type: string
        pattern: ^[a-z]{2,3}$
  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