Hoot Lens Element names API

openapi: 3.2.0
info:
  title: Hoot Lens Element names 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: Element names
paths:
  /v1/projects/{projectId}/element-names:
    get:
      tags:
      - Element names
      summary: List element names
      description: 'Names the team gave elements, by selector. They appear as `name` on elements in heatmaps, findings and impact reports, and in digests, alerts and agent tools. Written by people on the team; never taken from visitors.


        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: listElementNames
      parameters:
      - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: The names.
          content:
            application/json:
              schema:
                type: object
                properties:
                  names:
                    type: array
                    items:
                      $ref: '#/components/schemas/ElementDisplayName'
                required:
                - names
                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
    put:
      tags:
      - Element names
      summary: Name an element
      description: 'Sets or replaces the name of one element, keyed by its selector. Plain words only: control characters are removed, whitespace collapses, and markup is refused with 400. A site can have 200 names. Needs an owner or editor; viewers and 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: setElementName
      parameters:
      - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ElementNameInput'
      responses:
        '200':
          description: The name.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    $ref: '#/components/schemas/ElementDisplayName'
                required:
                - name
                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:
      - Element names
      summary: Remove an element name
      description: 'Removes the name so the element shows its automatic name again. Needs an owner or editor; viewers and 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: removeElementName
      parameters:
      - $ref: '#/components/parameters/projectId'
      - name: key
        in: query
        required: false
        description: The element's selector.
        schema:
          type: string
          minLength: 1
          maxLength: 600
      responses:
        '204':
          description: Removed.
        '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
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
    ElementNameInput:
      type: object
      properties:
        key:
          type: string
          minLength: 1
          maxLength: 300
          description: The element's selector exactly as findings and heatmaps list it. A data-hoot-id selector is the stable one.
        name:
          type: string
          minLength: 1
          maxLength: 60
          description: What the team calls the element. Plain words, no markup.
      required:
      - key
      - name
    ElementDisplayName:
      type: object
      properties:
        key:
          type: string
          description: The element's selector, as findings and heatmaps list it.
        name:
          type: string
          description: What the team calls the element.
        updatedAt:
          type: integer
          description: Epoch milliseconds.
          minimum: 0
        updatedBy:
          type: string
          description: The user who last set it.
      required:
      - key
      - name
      - updatedAt
      additionalProperties: true
    Id:
      type: string
      description: 'An identifier: 1 to 80 letters, digits, underscores or hyphens.'
      pattern: ^[a-zA-Z0-9_-]{1,80}$
  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