Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
All 92 tools →
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/hootlens-com:hootlens-com-goals-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Hoot Lens Goals 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: Goals
paths:
/v1/projects/{projectId}/goals:
get:
tags:
- Goals
summary: List goals
description: 'What counts as a conversion for this site.
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: listGoals
parameters:
- $ref: '#/components/parameters/projectId'
responses:
'200':
description: The goals.
content:
application/json:
schema:
type: object
properties:
goals:
type: array
items:
$ref: '#/components/schemas/Goal'
required:
- goals
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:
- Goals
summary: Create a goal
description: 'A click goal matches an element by CSS selector, data-hoot-id or label text; a page goal matches a page path pattern. An event goal matches a static business-event name and chooses browser or server reporting. Needs an owner or editor; personal access tokens receive 403. A site can have 20 goals.
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: createGoal
parameters:
- $ref: '#/components/parameters/projectId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GoalInput'
responses:
'201':
description: The new goal.
content:
application/json:
schema:
type: object
properties:
goal:
$ref: '#/components/schemas/Goal'
required:
- goal
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}/goals/{goalId}:
put:
tags:
- Goals
summary: Replace a goal
description: 'Counting restarts when what the goal matches changes, so one goal never mixes two definitions. 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: replaceGoal
parameters:
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/goalId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GoalInput'
responses:
'200':
description: The goal.
content:
application/json:
schema:
type: object
properties:
goal:
$ref: '#/components/schemas/Goal'
required:
- goal
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:
- Goals
summary: Delete a goal
description: 'Refused with 409 while a funnel uses the goal. 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: deleteGoal
parameters:
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/goalId'
responses:
'204':
description: Deleted.
'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: []
x-hootlens-sign-in-only: true
/v1/projects/{projectId}/goals/stats:
get:
tags:
- Goals
summary: Goal conversion statistics
description: 'Visits that converted over all visits, per goal, with a 95% Wilson interval. A goal counts only the days after it began. 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: getGoalStats
parameters:
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/from'
- $ref: '#/components/parameters/to'
responses:
'200':
description: The statistics.
content:
application/json:
schema:
$ref: '#/components/schemas/GoalStats'
'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:
Goal:
allOf:
- oneOf:
- oneOf:
- type: object
properties:
kind:
type: string
const: click
name:
type: string
minLength: 1
maxLength: 60
by:
type: string
const: selector
match:
type: string
minLength: 1
maxLength: 200
required:
- kind
- name
- by
- match
additionalProperties: false
- type: object
properties:
kind:
type: string
const: click
name:
type: string
minLength: 1
maxLength: 60
by:
type: string
const: hootId
match:
type: string
pattern: ^[a-zA-Z0-9_-]{1,80}$
required:
- kind
- name
- by
- match
additionalProperties: false
- type: object
properties:
kind:
type: string
const: click
name:
type: string
minLength: 1
maxLength: 60
by:
type: string
const: label
match:
type: string
minLength: 2
maxLength: 200
required:
- kind
- name
- by
- match
additionalProperties: false
- type: object
properties:
kind:
type: string
const: page
name:
type: string
minLength: 1
maxLength: 60
match:
type: string
required:
- kind
- name
- match
additionalProperties: false
- type: object
properties:
kind:
type: string
const: event
name:
type: string
minLength: 1
maxLength: 60
match:
type: string
pattern: ^[a-z][a-z0-9_]{0,63}$
confirmation:
type: string
enum:
- browser
- server
required:
- kind
- name
- match
- confirmation
additionalProperties: false
- type: object
properties:
id:
type: string
pattern: ^[a-zA-Z0-9_-]{1,80}$
since:
type: integer
minimum: 0
maximum: 9007199254740991
required:
- id
- since
additionalProperties: false
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
GoalStats:
type: object
properties:
from:
type: integer
description: Epoch milliseconds.
minimum: 0
to:
type: integer
description: Epoch milliseconds.
minimum: 0
sessions:
type: integer
goals:
type: array
items:
$ref: '#/components/schemas/GoalStat'
required:
- from
- to
- sessions
- goals
additionalProperties: true
GoalInput:
oneOf:
- oneOf:
- type: object
properties:
kind:
type: string
const: click
name:
type: string
minLength: 1
maxLength: 60
by:
type: string
const: selector
match:
type: string
minLength: 1
maxLength: 200
required:
- kind
- name
- by
- match
- type: object
properties:
kind:
type: string
const: click
name:
type: string
minLength: 1
maxLength: 60
by:
type: string
const: hootId
match:
type: string
pattern: ^[a-zA-Z0-9_-]{1,80}$
required:
- kind
- name
- by
- match
- type: object
properties:
kind:
type: string
const: click
name:
type: string
minLength: 1
maxLength: 60
by:
type: string
const: label
match:
type: string
minLength: 2
maxLength: 200
required:
- kind
- name
- by
- match
- type: object
properties:
kind:
type: string
const: page
name:
type: string
minLength: 1
maxLength: 60
match:
type: string
required:
- kind
- name
- match
- type: object
properties:
kind:
type: string
const: event
name:
type: string
minLength: 1
maxLength: 60
match:
type: string
pattern: ^[a-z][a-z0-9_]{0,63}$
confirmation:
type: string
enum:
- browser
- server
required:
- kind
- name
- match
- confirmation
GoalStat:
type: object
properties:
goalId:
type: string
name:
type: string
kind:
type: string
enum:
- click
- page
- event
sessions:
type: integer
conversions:
type: integer
rate:
oneOf:
- type: number
- type: 'null'
interval:
oneOf:
- type: array
items:
type: number
minItems: 2
maxItems: 2
- type: 'null'
since:
type: integer
description: When counting under the goal's current definition began.
minimum: 0
required:
- goalId
- name
- kind
- sessions
- conversions
- rate
- interval
- since
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'
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:
goalId:
name: goalId
in: path
required: true
description: A goal 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