Hoot Lens Install API

openapi: 3.2.0
info:
  title: Hoot Lens Install 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: Install
paths:
  /v1/projects/{projectId}/install-snippet:
    get:
      tags:
      - Install
      summary: Install snippet
      description: 'The exact tag and steps for a platform. The site (project) ID is public and the snippet holds no secret.


        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: getInstallSnippet
      parameters:
      - $ref: '#/components/parameters/projectId'
      - name: platform
        in: query
        required: false
        description: Site platform. Defaults to html, the raw tag.
        schema:
          type: string
          enum:
          - gtm
          - wordpress
          - shopify
          - nextjs
          - remix
          - nuxt
          - sveltekit
          - astro
          - angular
          - gatsby
          - vite
          - webflow
          - squarespace
          - wix
          - html
      - name: variant
        in: query
        required: false
        description: 'For nextjs: app (App Router) or pages (Pages Router).'
        schema:
          type: string
          enum:
          - app
          - pages
      responses:
        '200':
          description: The snippet and steps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallSnippet'
        '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
  /v1/projects/{projectId}/install-status:
    get:
      tags:
      - Install
      summary: Install status
      description: 'When the tag last fetched its configuration and last delivered data, and why recent batches were refused. Reasons never carry page content.


        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: getInstallStatus
      parameters:
      - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: The install status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallStatus'
        '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
    InstallStatus:
      type: object
      properties:
        projectId:
          $ref: '#/components/schemas/Id'
        lastConfigFetchAt:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
        lastConfigOrigin:
          type: string
        lastCollectAt:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
        lastCollectOrigin:
          type: string
        trackerVersion:
          type: string
        recentRejections:
          type: array
          items:
            type: object
            properties:
              reason:
                type: string
              detail:
                type: string
              origin:
                type: string
              at:
                type: integer
                description: Epoch milliseconds.
                minimum: 0
              count:
                type: integer
            required:
            - reason
            - at
            - count
            additionalProperties: true
      required:
      - projectId
      - recentRejections
      additionalProperties: true
    Id:
      type: string
      description: 'An identifier: 1 to 80 letters, digits, underscores or hyphens.'
      pattern: ^[a-zA-Z0-9_-]{1,80}$
    InstallSnippet:
      type: object
      properties:
        projectId:
          $ref: '#/components/schemas/Id'
        platform:
          type: string
        label:
          type: string
        where:
          type: string
        tag:
          type: string
          description: The script tag.
        variants:
          type: array
          items:
            type: object
            properties: {}
            additionalProperties: true
        variant:
          type: string
        steps:
          type: array
          items:
            type: string
        blocks:
          type: array
          items:
            type: object
            properties:
              file:
                type: string
              code:
                type: string
            additionalProperties: true
        allowedOrigins:
          type: array
          items:
            type: string
        verify:
          type: array
          items:
            type: string
        platforms:
          type: array
          items:
            type: string
      required:
      - projectId
      - platform
      - tag
      - steps
      - blocks
      additionalProperties: true
  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'
  parameters:
    projectId:
      name: projectId
      in: path
      required: true
      description: The project ID. Project IDs are public identifiers, not secrets.
      schema:
        $ref: '#/components/schemas/Id'
  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