Hoot Lens Conversions API

openapi: 3.2.0
info:
  title: Hoot Lens Conversions 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: Conversions
paths:
  /v1/projects/{projectId}/conversions:
    post:
      tags:
      - Conversions
      summary: Report a completed business outcome
      description: 'Reports an outcome after the integration confirms success. Only an existing admitted recording and matching visit can be correlated. The same opaque receipt ID and content retry safely; changed content returns 409. Browser reports cannot satisfy a server-reported goal. Test, internal, automated, and ineligible visits do not count. Amounts use integer currency minor units, remain separate by currency, and never create a payment. A goal counts only visits admitted under its current definition.


        A project-scoped personal access token with conversions:write is required. Firebase sign-in and OAuth credentials cannot report conversions.'
      operationId: recordConversion
      parameters:
      - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServerConversionInput'
      responses:
        '200':
          description: The immutable receipt result. counted distinguishes a counted goal outcome from a retained receipt.
          content:
            application/json:
              schema:
                type: object
                properties:
                  recorded:
                    type: boolean
                  duplicate:
                    type: boolean
                  counted:
                    type: boolean
                  matchedGoalIds:
                    type: array
                    items:
                      type: string
                required:
                - recorded
                - duplicate
                - counted
                - matchedGoalIds
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '410':
          $ref: '#/components/responses/Gone'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - bearerAuth: []
      x-hootlens-scopes:
      - conversions:write
      x-hootlens-pat-only: true
  /v1/projects/{projectId}/conversions/report:
    get:
      tags:
      - Conversions
      summary: Conversion outcomes by original visit source
      description: 'Eligible recorded visits, converting visits, event occurrences, browser/server provenance, and revenue by the original source, campaign, device, entry page, or release. Ranges cover at most 92 UTC days and use the visit-start day. since and coverage distinguish unavailable history from zero. At most 50 rows are displayed; larger collection/report bounds mark coverage partial and omittedRows names rows not shown. Currency totals are never combined.


        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: getConversionReport
      parameters:
      - $ref: '#/components/parameters/projectId'
      - name: from
        in: query
        required: true
        description: First visit-start UTC day, as epoch milliseconds.
        schema:
          type: integer
          minimum: 0
      - name: to
        in: query
        required: true
        description: Last visit-start UTC day, as epoch milliseconds.
        schema:
          type: integer
          minimum: 1
      - name: goalId
        in: query
        required: true
        description: An existing goal ID.
        schema:
          $ref: '#/components/schemas/Id'
      - name: dimension
        in: query
        required: false
        description: Original visit dimension.
        schema:
          type: string
          enum:
          - channel
          - referrer
          - utmSource
          - utmCampaign
          - device
          - entryPage
          - release
          default: channel
      responses:
        '200':
          description: Outcomes, separate currencies, and explicit measurement coverage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionReport'
        '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
    ServerConversionInput:
      type: object
      properties:
        recordingId:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,80}$
        sessionId:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,80}$
        event:
          type: object
          properties:
            id:
              type: string
              pattern: ^[A-Za-z0-9_-]{16,128}$
            name:
              type: string
              pattern: ^[a-z][a-z0-9_]{0,63}$
            at:
              type: integer
              exclusiveMinimum: 0
              maximum: 9007199254740991
            amountMinor:
              type: integer
              minimum: 0
              maximum: 1000000000
            currency:
              type: string
              enum:
              - USD
              - EUR
              - GBP
              - CAD
              - AUD
              - NZD
              - JPY
              - CHF
              - SEK
              - NOK
              - DKK
              - INR
              - BRL
              - MXN
              - SGD
              - ZAR
              - KWD
              - BHD
              - OMR
              - KRW
              - AED
              - SAR
              - CNY
              - HKD
              - PLN
              - CZK
              - HUF
              - ILS
              - TRY
              - THB
              - MYR
              - PHP
              - IDR
          required:
          - id
          - name
          - at
          additionalProperties: false
      required:
      - recordingId
      - sessionId
      - event
      additionalProperties: false
    ConversionReport:
      type: object
      properties:
        from:
          type: integer
          description: First visit-start day.
          minimum: 0
        to:
          type: integer
          description: Last visit-start day.
          minimum: 0
        goalId:
          $ref: '#/components/schemas/Id'
        goalName:
          type: string
        dimension:
          type: string
          enum:
          - channel
          - referrer
          - utmSource
          - utmCampaign
          - device
          - entryPage
          - release
        since:
          oneOf:
          - type: integer
            description: First available measurement under this goal definition.
            minimum: 0
          - type: 'null'
        coverage:
          type: object
          properties:
            status:
              type: string
              enum:
              - complete
              - partial
              - unavailable
            note:
              type: string
          required:
          - status
          - note
          additionalProperties: true
        totals:
          $ref: '#/components/schemas/ConversionMetrics'
        rows:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/ConversionMetrics'
            - type: object
              properties:
                key:
                  type: string
                label:
                  type: string
                rate:
                  oneOf:
                  - type: number
                  - type: 'null'
              required:
              - key
              - label
              - rate
              additionalProperties: true
          maxItems: 50
        omittedRows:
          type: integer
        windowBasis:
          type: string
          enum:
          - visit_started
      required:
      - from
      - to
      - goalId
      - goalName
      - dimension
      - since
      - coverage
      - totals
      - rows
      - omittedRows
      - windowBasis
      additionalProperties: true
    ConversionMoney:
      type: object
      properties:
        currency:
          type: string
        amountMinor:
          oneOf:
          - type: integer
            description: Integer currency minor units. Null when the aggregate cannot be represented safely.
          - type: 'null'
      required:
      - currency
      - amountMinor
      additionalProperties: true
    ConversionMetrics:
      type: object
      properties:
        visits:
          type: integer
        conversions:
          type: integer
        occurrences:
          type: integer
        browserReported:
          type: integer
        serverReported:
          type: integer
        revenue:
          type: array
          items:
            $ref: '#/components/schemas/ConversionMoney'
      required:
      - visits
      - conversions
      - occurrences
      - browserReported
      - serverReported
      - revenue
      additionalProperties: true
    Id:
      type: string
      description: 'An identifier: 1 to 80 letters, digits, underscores or hyphens.'
      pattern: ^[a-zA-Z0-9_-]{1,80}$
  responses:
    Gone:
      description: The thing asked for existed but has expired, such as a settings change preview.
      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'
    PaymentRequired:
      description: The site (project) or account plan does not allow this.
      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'
    Conflict:
      description: The request conflicts with the current state of the record.
      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