Hoot Lens Funnels API

openapi: 3.2.0
info:
  title: Hoot Lens Funnels 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: Funnels
paths:
  /v1/projects/{projectId}/funnels:
    get:
      tags:
      - Funnels
      summary: List funnels
      description: 'Ordered sequences of goals. A site with goals and no funnels also gets suggestions: starter funnels, each with the settings change that creates it.


        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: listFunnels
      parameters:
      - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: The funnels.
          content:
            application/json:
              schema:
                type: object
                properties:
                  funnels:
                    type: array
                    items:
                      $ref: '#/components/schemas/Funnel'
                  suggestions:
                    type: array
                    items:
                      $ref: '#/components/schemas/FunnelSuggestion'
                required:
                - funnels
                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
    post:
      tags:
      - Funnels
      summary: Create a funnel
      description: 'Two to eight steps, each naming an existing goal, used once. Needs an owner or editor; personal access tokens receive 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: createFunnel
      parameters:
      - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FunnelInput'
      responses:
        '201':
          description: The new funnel.
          content:
            application/json:
              schema:
                type: object
                properties:
                  funnel:
                    $ref: '#/components/schemas/Funnel'
                required:
                - funnel
                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: []
      x-hootlens-sign-in-only: true
  /v1/projects/{projectId}/funnels/{funnelId}:
    put:
      tags:
      - Funnels
      summary: Replace a funnel
      description: 'Replaces the funnel''s name and steps. Personal access tokens receive 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: replaceFunnel
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/funnelId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FunnelInput'
      responses:
        '200':
          description: The funnel.
          content:
            application/json:
              schema:
                type: object
                properties:
                  funnel:
                    $ref: '#/components/schemas/Funnel'
                required:
                - funnel
                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: []
      x-hootlens-sign-in-only: true
    delete:
      tags:
      - Funnels
      summary: Delete a funnel
      description: 'Personal access tokens receive 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: deleteFunnel
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/funnelId'
      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: []
      x-hootlens-sign-in-only: true
  /v1/projects/{projectId}/funnels/{funnelId}/stats:
    get:
      tags:
      - Funnels
      summary: Funnel statistics
      description: 'Visits that reached each step in order, with drop-off examples. Cohort filters match the page view where the visit reached step 1. Ranges are limited to 92 days and default to the last 30.


        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: getFunnelStats
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/funnelId'
      - $ref: '#/components/parameters/from'
      - $ref: '#/components/parameters/to'
      - name: pageGroup
        in: query
        required: false
        description: Page group ID of the entry page view.
        schema:
          type: string
          minLength: 1
          maxLength: 300
      - $ref: '#/components/parameters/deviceClass'
      - $ref: '#/components/parameters/locale'
      - name: variant
        in: query
        required: false
        description: Experiment variant of the entry page view.
        schema:
          type: string
          minLength: 1
          maxLength: 100
      - name: pageRevision
        in: query
        required: false
        description: Page revision of the entry page view.
        schema:
          type: string
          minLength: 1
          maxLength: 150
      - name: entryContext
        in: query
        required: false
        description: JSON-serialized source.context from a funnel improvement, preserving the exact known and unknown entry dimensions. Raw release must be absent because funnel entries do not retain it.
        schema:
          type: string
          maxLength: 3000
      - name: expectedGoals
        in: query
        required: false
        description: JSON-serialized source.goalDefinitions from a funnel improvement. A changed ordered goal definition returns 409 instead of silently changing the report.
        schema:
          type: string
          maxLength: 3000
      - name: pageVersion
        in: query
        required: false
        description: Page version of the entry page view.
        schema:
          type: string
          minLength: 1
          maxLength: 100
      responses:
        '200':
          description: The statistics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunnelStats'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
      x-hootlens-scopes:
      - read
components:
  schemas:
    FunnelInput:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 60
        steps:
          minItems: 2
          maxItems: 8
          type: array
          items:
            type: object
            properties:
              goalId:
                type: string
                pattern: ^[a-zA-Z0-9_-]{1,80}$
            required:
            - goalId
      required:
      - name
      - steps
    Id:
      type: string
      description: 'An identifier: 1 to 80 letters, digits, underscores or hyphens.'
      pattern: ^[a-zA-Z0-9_-]{1,80}$
    Funnel:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 60
        steps:
          minItems: 2
          maxItems: 8
          type: array
          items:
            type: object
            properties:
              goalId:
                type: string
                pattern: ^[a-zA-Z0-9_-]{1,80}$
            required:
            - goalId
            additionalProperties: false
        id:
          type: string
          pattern: ^[a-zA-Z0-9_-]{1,80}$
        createdAt:
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
      - name
      - steps
      - id
      - createdAt
      additionalProperties: false
    FunnelStats:
      type: object
      properties:
        funnelId:
          type: string
        name:
          type: string
        from:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
        to:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
        effectiveFrom:
          type: integer
          description: 'The window measured: from raised to the latest goal start.'
          minimum: 0
        effectiveTo:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
        sessions:
          type: integer
          description: Visits that reached step 1.
        truncated:
          type: boolean
          description: True when only the newest visits were counted.
        filters:
          type: object
          properties: {}
          additionalProperties: true
        steps:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              goalId:
                type: string
              name:
                type: string
              goalKind:
                type: string
                enum:
                - click
                - page
              description:
                type: string
              since:
                type: integer
                description: Epoch milliseconds.
                minimum: 0
              reached:
                type: integer
              fromPrevious:
                oneOf:
                - type: object
                  properties:
                    rate:
                      oneOf:
                      - type: number
                      - type: 'null'
                    interval:
                      oneOf:
                      - type: array
                        items:
                          type: number
                      - type: 'null'
                  additionalProperties: true
                - type: 'null'
              fromFirst:
                type: object
                properties:
                  rate:
                    oneOf:
                    - type: number
                    - type: 'null'
                  interval:
                    oneOf:
                    - type: array
                      items:
                        type: number
                    - type: 'null'
                additionalProperties: true
              dropOff:
                type: object
                properties:
                  count:
                    type: integer
                  exampleSessionIds:
                    type: array
                    items:
                      type: string
                  examples:
                    type: array
                    items:
                      type: object
                      properties:
                        sessionId:
                          type: string
                        recordingId:
                          type: string
                        at:
                          type: integer
                          description: Epoch milliseconds.
                          minimum: 0
                      additionalProperties: true
                required:
                - count
                additionalProperties: true
            required:
            - index
            - goalId
            - name
            - reached
            additionalProperties: true
        notes:
          type: array
          items:
            type: string
            description: Plain-language limits on these numbers.
      required:
      - funnelId
      - name
      - from
      - to
      - sessions
      - truncated
      - filters
      - steps
      - notes
      additionalProperties: true
    FunnelSuggestion:
      type: object
      properties:
        name:
          type: string
        basis:
          type: string
          enum:
          - homepage
          - visit-order
        steps:
          type: array
          items:
            type: string
            description: Goal names in step order.
        reason:
          type: string
        change:
          type: object
          description: A settings change to pass to the preview route.
          properties: {}
          additionalProperties: true
      required:
      - name
      - basis
      - steps
      - reason
      - change
      additionalProperties: true
    DeviceClass:
      type: string
      enum:
      - desktop
      - tablet
      - mobile
    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
  responses:
    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'
    Conflict:
      description: The request conflicts with the current state of the record.
      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'
    TooManyRequests:
      description: A rate limit or a per-site limit was reached.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: The credential is missing, expired or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    locale:
      name: locale
      in: query
      required: false
      description: Primary language code such as es.
      schema:
        type: string
        pattern: ^[a-z]{2,3}$
    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'
    funnelId:
      name: funnelId
      in: path
      required: true
      description: A funnel ID.
      schema:
        $ref: '#/components/schemas/Id'
    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
  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