LLM Pulse Webhooks API
Outbound event notifications: subscribe an HTTPS URL to project events and receive HMAC-signed deliveries with no polling. Scale plan and above.
Outbound event notifications: subscribe an HTTPS URL to project events and receive HMAC-signed deliveries with no polling. Scale plan and above.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/llmpulse-ai:llmpulse-ai-webhooks-api"
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.
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. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. 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: LLM Pulse Webhooks API
description: 'REST API for the LLM Pulse AI visibility platform. Track brand mentions, citations, sentiment, and Share of Voice across AI-generated answers (ChatGPT, Perplexity, Gemini, Google AI Overviews, Google AI Mode, and optional add-on models). Includes the MCP (Model Context Protocol) endpoint for AI clients. MCP is available on every plan and during eligible trials via OAuth 2.1, with Bearer-token API keys also accepted for headless integrations on the Scale plan or above. Full machine-readable reference at https://llmpulse.ai/api-docs/llms-full.txt. An API key can be limited to one or several projects when it is created, and the set never changes. Such a key sees only those projects: any other project id, domain or name answers ERR_PROJECT_NOT_FOUND exactly like a project that does not exist, listings return only those projects'' rows, and operations on the whole account (creating or deleting a project, the project draft wizard) answer ERR_KEY_PROJECT_SCOPED. Operations carry vendor extensions: x-plan is the plan or entitlement the endpoint requires beyond an API key (growth, scale or reputation_access), x-write marks endpoints that need a read and write key, x-mcp-tool names the MCP tool that returns the same data, x-mcp-plan gives that tool''s plan where it differs, and x-rest-only explains an endpoint with no MCP tool. Parameters are read strictly, on REST and MCP alike: a value outside a documented enum, a boolean other than true, false, 1 or 0, an id or count that is not a plain positive number (12abc, 1.0 or 0), an id of a record the project does not have, or a from later than to answers 422 ERR_INVALID_PARAM naming the parameter, never an ignored filter. A listed value, in a query or a request body, matches in any letter case and is read in its documented spelling (granularity=Week reads as week, aggregation_type=BYPAGE as byPage, event_type=Mention.Created as mention.created). page and per_page keep their own rule: a value that is not a number reads as absent and an out-of-range one is clamped.'
version: 1.97.0
contact:
name: LLM Pulse Support
url: https://llmpulse.ai
email: info@llmpulse.ai
license:
name: Proprietary
url: https://llmpulse.ai/terms
servers:
- url: https://api.llmpulse.ai/api/v1
description: Production API
security:
- BearerAuth: []
tags:
- name: Webhooks
description: 'Outbound event notifications: subscribe an HTTPS URL to project events and receive HMAC-signed deliveries with no polling. Scale plan and above.'
paths:
/webhooks:
get:
tags:
- Webhooks
summary: List webhook subscriptions
x-llms-description: List active webhook subscriptions for the account (optional project_id filter).
operationId: listWebhooks
x-mcp-tool: list_webhook_subscriptions
description: Lists active webhook subscriptions for the account, optionally filtered by project. A read-only API key receives each `target_url` masked to its scheme, host and any non-default port followed by `/…`, because the full URL can let anyone post to the receiver; a `read_write` scope key receives the full URL. Works on every plan, with an API key created on Scale too. Below Scale the subscriptions are kept but deliver nothing, and they can still be listed and deleted.
parameters:
- name: project_id
in: query
required: false
schema:
type: integer
description: Optional project filter. An id that is not a plain number, or that names no project of the account, returns ERR_PROJECT_NOT_FOUND.
- name: page
in: query
required: false
schema:
type: integer
- name: per_page
in: query
required: false
schema:
type: integer
description: Max 100
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
page:
type: integer
per_page:
type: integer
total:
type: integer
data:
type: array
items:
type: object
properties:
id:
type: integer
project_id:
type: integer
event_type:
type: string
enum:
- mention.created
- competitor_mention.created
- citation.created
- prompt_execution.completed
- sentiment.negative_detected
- recommendation.completed
- intelligence_task.completed
- intelligence_task.updated
- geo_audit_run.completed
- geo_audit_alert.triggered
- tracking_run.completed
target_url:
type: string
description: The URL deliveries are sent to. A read-only API key receives only its scheme, host and any non-default port followed by `/…` (for example `https://hook.eu1.make.com/…`); a `read_write` scope key receives the full URL.
disabled:
type: boolean
description: True when the subscription receives no more events, including when the API key or OAuth connection that created it was revoked, or when that API key is limited to some projects and no longer covers the subscription's project. Creating it again with the same project, event and URL replaces it with a new subscription and secret.
failure_count:
type: integer
last_delivered_at:
type:
- string
- 'null'
format: date-time
created_at:
type: string
format: date-time
request_id:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/PlanRequired'
'404':
$ref: '#/components/responses/NotFound'
post:
tags:
- Webhooks
summary: Create a webhook subscription
x-llms-description: Subscribe a public HTTPS URL to a project event (new brand or competitor mention, citation, execution, negative sentiment, completed recommendations report or GEO Writer task, GEO Writer edit, GEO audit run or alert, finished tracking run); deliveries are HMAC-signed. Scale plan or above.
operationId: createWebhook
x-mcp-tool: create_webhook_subscription
x-plan: scale
x-write: true
description: 'Subscribes a public HTTPS URL to a project event. LLM Pulse POSTs a JSON envelope (`event`, `occurred_at`, `project_id`, `subscription_id`, `data`) to the URL every time the event occurs, signed via the `X-LLMPulse-Signature` header (HMAC-SHA256 of the raw body computed with the subscription secret). Failed deliveries receive up to 5 attempts in total, including the first, with backoff; subscriptions auto-disable after 20 consecutive failed deliveries. While the account is below the Scale plan its subscriptions are kept but deliver nothing: no failed delivery is counted, none is disabled, and deliveries resume once the account is back on Scale or above, without resending the events from that period. Each delivery also checks that the API key that created the subscription still covers its project: an API key limited to some projects that loses the project stops the subscription for good. Idempotent for the same project + event + URL: re-posting returns the existing subscription, unless the API key or OAuth connection that created it was revoked, or that API key no longer covers the project; then it is replaced by a new subscription with a new secret. The response carries `secret` when it creates the subscription, and on a re-post only for the API key or OAuth connection that created it: any other credential gets the subscription without `secret`. Requires a `read_write` scope API key and the Scale plan or above.'
responses:
'201':
description: Created, or the existing subscription on a re-post. The signing secret is only returned by this endpoint, and on a re-post only to the credential that created the subscription.
content:
application/json:
schema:
type: object
properties:
id:
type: integer
project_id:
type: integer
event_type:
type: string
enum:
- mention.created
- competitor_mention.created
- citation.created
- prompt_execution.completed
- sentiment.negative_detected
- recommendation.completed
- intelligence_task.completed
- intelligence_task.updated
- geo_audit_run.completed
- geo_audit_alert.triggered
- tracking_run.completed
target_url:
type: string
disabled:
type: boolean
description: True when the subscription receives no more events, including when the API key or OAuth connection that created it was revoked, or when that API key is limited to some projects and no longer covers the subscription's project. Creating it again with the same project, event and URL replaces it with a new subscription and secret.
failure_count:
type: integer
last_delivered_at:
type:
- string
- 'null'
format: date-time
created_at:
type: string
format: date-time
secret:
type: string
description: HMAC signing secret (whsec_...). Returned when the subscription is created, and on a re-post only to the API key or OAuth connection that created it; absent for any other credential.
request_id:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/InsufficientScope'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- project_id
- event_type
- target_url
properties:
project_id:
type: integer
event_type:
type: string
enum:
- mention.created
- competitor_mention.created
- citation.created
- prompt_execution.completed
- sentiment.negative_detected
- recommendation.completed
- intelligence_task.completed
- intelligence_task.updated
- geo_audit_run.completed
- geo_audit_alert.triggered
- tracking_run.completed
target_url:
type: string
description: Public HTTPS URL that will receive signed event payloads
/webhooks/{id}:
delete:
tags:
- Webhooks
summary: Delete a webhook subscription
x-llms-description: Delete a webhook subscription; the target URL stops receiving events immediately.
operationId: deleteWebhook
x-mcp-tool: delete_webhook_subscription
x-write: true
description: Deletes a webhook subscription; the target URL stops receiving events immediately. Requires a `read_write` scope API key. Works on every plan, with an API key created on Scale too, so a subscription paused below Scale can still be removed.
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
deleted:
type: boolean
id:
type: integer
request_id:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/InsufficientScope'
'404':
$ref: '#/components/responses/NotFound'
/webhooks/sample/{event_type}:
get:
tags:
- Webhooks
summary: Sample event payloads
x-llms-description: Up to 3 example event payloads for an event type, built from recent project data (used by integration editors).
operationId: sampleWebhookPayloads
x-mcp-tool: get_webhook_sample
x-plan: scale
description: Returns up to 3 example event payloads for the event type, built from the project's most recent real data (or a static sample when the project has no data). Used by integration editors such as the Zapier sample loader. Requires the Scale plan or above.
parameters:
- name: event_type
in: path
required: true
schema:
type: string
enum:
- mention.created
- competitor_mention.created
- citation.created
- prompt_execution.completed
- sentiment.negative_detected
- recommendation.completed
- intelligence_task.completed
- intelligence_task.updated
- geo_audit_run.completed
- geo_audit_alert.triggered
- tracking_run.completed
- name: project_id
in: query
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
event_type:
type: string
data:
type: array
items:
type: object
properties:
event:
type: string
occurred_at:
type: string
format: date-time
project_id:
type: integer
subscription_id:
type: integer
data:
type: object
request_id:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/PlanRequired'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
components:
schemas:
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- ERR_MISSING_AUTH
- ERR_INVALID_API_KEY
- ERR_REVOKED_API_KEY
- ERR_INSUFFICIENT_SCOPE
- ERR_INSUFFICIENT_PERMISSION
- ERR_KEY_PROJECT_SCOPED
- ERR_PLAN_REQUIRED
- ERR_INTEGRATION_UNAVAILABLE
- ERR_GENERATION_FAILED
- ERR_ACCOUNT_INACTIVE
- ERR_DRAFT_NOT_FOUND
- ERR_DRAFT_STATE
- ERR_PROJECT_NOT_FOUND
- ERR_NOT_FOUND
- ERR_SEARCH_CONSOLE_NOT_CONNECTED
- ERR_SEARCH_CONSOLE_ACCESS_REVOKED
- ERR_SEARCH_CONSOLE_UPSTREAM
- ERR_CMS_NOT_CONNECTED
- ERR_CMS_ACCESS_REVOKED
- ERR_CMS_REJECTED
- ERR_CMS_UPSTREAM
- ERR_AI_TRAFFIC_NOT_CONNECTED
- ERR_WEB_ANALYTICS_NOT_CONNECTED
- ERR_WEB_ANALYTICS_INVALID_QUERY
- ERR_WEB_ANALYTICS_ACCESS_REVOKED
- ERR_WEB_ANALYTICS_UPSTREAM
- ERR_AGENT_TRAFFIC_NOT_CONNECTED
- ERR_INVALID_PARAM
- ERR_INVALID_RANGE
- ERR_LIMIT_REACHED
- ERR_QUOTA_EXCEEDED
- ERR_STALE_CONTENT
- ERR_RATE_LIMITED
message:
type: string
meta:
type: object
description: Extra detail for some codes. A not-connected or access-revoked error from the Search Console, AI traffic, web analytics or agent traffic endpoints carries connect_url, the in-app page where the user connects or reconnects the source. A prompt write refused because a launched pitch project's prompts are fixed carries reason pitch_prompts_frozen.
request_id:
type: string
responses:
UnprocessableEntity:
description: Invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ERR_INVALID_PARAM
message: invalid metrics
request_id: abc-123
PlanRequired:
description: Endpoint requires a higher plan tier
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ERR_PLAN_REQUIRED
message: Scale plan or above required
request_id: abc-123
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ERR_PROJECT_NOT_FOUND
message: project_not_found
request_id: abc-123
InsufficientScope:
description: API key lacks write permission
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ERR_INSUFFICIENT_SCOPE
message: insufficient_scope_write_required
request_id: abc-123
Unauthorized:
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ERR_MISSING_AUTH
message: missing_authorization
request_id: abc-123
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: API key authentication. Keys are managed at https://llmpulse.ai/app/api_keys (Scale plan or above). Used for the REST API and as a headless option for /mcp. A key can be limited to one or several projects when it is created; the set cannot be changed later.
OAuth2:
type: oauth2
description: OAuth 2.1 with PKCE-S256 and Dynamic Client Registration. Accepted on /mcp only, available on every plan and during eligible trials. Discovery metadata at /.well-known/oauth-authorization-server.
flows:
authorizationCode:
authorizationUrl: https://api.llmpulse.ai/oauth/authorize
tokenUrl: https://api.llmpulse.ai/oauth/token
scopes:
mcp:read: Read data via MCP tools
mcp:write: Create resources via MCP write tools