LLM Pulse Annotations API
Mark a date on the project timeline (a campaign launch, a site migration) so charts show what happened when.
Mark a date on the project timeline (a campaign launch, a site migration) so charts show what happened when.
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-annotations-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 Annotations 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: Annotations
description: Mark a date on the project timeline (a campaign launch, a site migration) so charts show what happened when.
paths:
/annotations:
get:
tags:
- Annotations
summary: List timeline annotations
x-llms-description: List project timeline annotations (user + system), with date and category filters. Available on every plan.
operationId: listAnnotations
x-mcp-tool: list_annotations
description: Lists project timeline annotations, newest first. Rows can come from manual notes, project automations, or platform events. The origin field distinguishes them; editable says whether the requesting user may modify the row. Available on every plan.
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: from
in: query
schema:
type: string
format: date
- name: to
in: query
schema:
type: string
format: date
- name: annotation_category_id
in: query
schema:
type: integer
minimum: 1
description: Keep the annotations filed under this category, one of the project's or a system category. Any other id returns 422 ERR_INVALID_PARAM.
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
responses:
'200':
description: Paginated annotations
'403':
$ref: '#/components/responses/InsufficientPermission'
post:
tags:
- Annotations
summary: Create a timeline annotation
x-llms-description: Add a timeline annotation to a project. Available on every plan.
operationId: createAnnotation
x-mcp-tool: create_annotation
x-write: true
description: Marks a date in the project timeseries with a title + description. Available on every plan. Requires a `read_write` scope API key.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- project_id
- title
properties:
project_id:
type: integer
title:
type: string
annotation_date:
type: string
format: date
description: ISO YYYY-MM-DD; defaults to today
description:
type: string
color:
type: string
description: 'Hex color, e.g. #2563eb'
annotation_category_id:
type: integer
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationCreateResponse'
'403':
$ref: '#/components/responses/InsufficientScope'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/annotations/{id}:
patch:
tags:
- Annotations
summary: Update a timeline annotation
x-llms-description: Update an own-user annotation (title, description, date, color, category). Available on every plan.
operationId: updateAnnotation
x-mcp-tool: update_annotation
x-write: true
description: Updates title, description, annotation_date, color and/or annotation_category_id. Only user-created annotations belonging to the requesting user can be updated (system annotations never). Available on every plan and requires a `read_write` scope API key.
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- project_id
properties:
project_id:
type: integer
title:
type: string
description:
type: string
annotation_date:
type: string
format: date
color:
type: string
annotation_category_id:
type: integer
responses:
'200':
description: Updated
'403':
$ref: '#/components/responses/InsufficientPermission'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
delete:
tags:
- Annotations
summary: Delete a timeline annotation
x-llms-description: Delete an own-user annotation. Available on every plan.
operationId: deleteAnnotation
x-mcp-tool: delete_annotation
x-write: true
description: Deletes an annotation. Same ownership rule as PATCH. Available on every plan and requires a `read_write` scope API key.
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Deleted
'403':
$ref: '#/components/responses/InsufficientPermission'
'404':
$ref: '#/components/responses/NotFound'
components:
responses:
InsufficientPermission:
description: API key belongs to a team member whose permission matrix does not grant this feature
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ERR_INSUFFICIENT_PERMISSION
message: insufficient_team_member_permission
request_id: abc-123
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
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
parameters:
ProjectId:
name: project_id
in: query
required: true
schema:
type: integer
description: Project ID
PerPage:
name: per_page
in: query
schema:
type: integer
default: 20
maximum: 100
minimum: 1
Page:
name: page
in: query
schema:
type: integer
default: 1
minimum: 1
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
AnnotationCreateResponse:
type: object
required:
- project_id
- annotation
- request_id
properties:
project_id:
type: integer
annotation:
type: object
required:
- id
- title
- annotation_date
- description
- color
- annotation_category_id
properties:
id:
type: integer
title:
type: string
annotation_date:
type: string
format: date
description:
type:
- string
- 'null'
color:
type:
- string
- 'null'
description: Hex color such as '#4F46E5'
annotation_category_id:
type:
- integer
- 'null'
request_id:
type: string
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