LLM Pulse Recommendations API
Recommendation runs that power the in-app Recommendations page, the endpoint that launches a new one, and the one that completes, archives or restores an item.
Recommendation runs that power the in-app Recommendations page, the endpoint that launches a new one, and the one that completes, archives or restores an item.
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-recommendations-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 Recommendations 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: Recommendations
description: Recommendation runs that power the in-app Recommendations page, the endpoint that launches a new one, and the one that completes, archives or restores an item.
paths:
/recommendations:
get:
tags:
- Recommendations
summary: List recommendation runs
x-llms-description: List recommendation runs for a project (filter by recommendation_type and status).
operationId: listRecommendations
x-mcp-tool: list_recommendations
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: recommendation_type
in: query
schema:
type: string
enum:
- ai_visibility
- social_community
- brand_building
- sentiment_reputation
- name: status
in: query
schema:
type: string
enum:
- pending
- processing
- completed
- failed
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
responses:
'200':
description: Paginated recommendations
content:
application/json:
schema:
$ref: '#/components/schemas/RecommendationsResponse'
post:
tags:
- Recommendations
summary: Launch a recommendations generation
x-llms-description: Launch a new recommendations generation (async, 1-3 min; consumes the weekly recommendation budget). Poll GET /recommendations/:id.
operationId: launchRecommendations
x-mcp-tool: launch_recommendations
x-write: true
description: 'Launches a full-scope recommendations generation (async job, 1-3 minutes; poll GET /recommendations/{id} until status is completed). Consumes the project weekly recommendation-item budget: returns ERR_LIMIT_REACHED when it is exhausted or when a generation of the same type is already pending/processing. sentiment_reputation requires the Scale plan or above. Requires a `read_write` scope API key.'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- project_id
properties:
project_id:
type: integer
recommendation_type:
type: string
enum:
- ai_visibility
- social_community
- brand_building
- sentiment_reputation
default: ai_visibility
responses:
'201':
description: Generation launched (status pending)
'403':
$ref: '#/components/responses/InsufficientScope'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/recommendations/{id}:
get:
tags:
- Recommendations
summary: Get recommendation run with items
x-llms-description: Detailed recommendation run with items, action steps, priorities, and resolved source references.
operationId: getRecommendation
x-mcp-tool: get_recommendation
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: id
in: path
required: true
schema:
type: integer
- name: item_status
in: query
schema:
type: string
enum:
- active
- completed
- archived
- name: resolve_source_refs
in: query
schema:
type: boolean
default: true
responses:
'200':
description: Recommendation detail with items
'404':
$ref: '#/components/responses/NotFound'
/recommendations/{id}/items/{item_id}:
patch:
tags:
- Recommendations
summary: Complete, archive or restore a recommendation item
x-llms-description: Mark one recommendation item as completed, archive it (with an optional reason later runs learn from), or move it back to active, like the buttons on the Recommendations page.
operationId: updateRecommendationItem
x-mcp-tool: update_recommendation_item
x-write: true
description: 'Moves one item of a recommendation run between `active`, `completed` and `archived`, exactly like the complete, archive and restore buttons on the Recommendations page, and stamps `status_changed_at`. When archiving, an optional `reason` teaches later runs: `not_relevant` and `too_complex` steer the next recommendations away from similar ones, and on a PR & Citation Building item that targets a domain (`metadata.domain`), `competitor` or `not_relevant` stops that site from being suggested again. The reason is stored in `metadata.archive_reason` and dropped when the item leaves `archived`. A reason with another status, an unknown one, or `competitor` on an item without a domain returns `ERR_INVALID_PARAM`. Returns the item in the shape `GET /recommendations/{id}` lists items. Requires a `read_write` scope API key and, for team members, create permission on Recommendations (the permission the page uses for these buttons).'
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: Recommendation run id
- name: item_id
in: path
required: true
schema:
type: integer
description: Item id, from the items of GET /recommendations/{id}
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- project_id
- status
properties:
project_id:
type: integer
status:
type: string
enum:
- active
- completed
- archived
description: completed, archived, or active to restore the item
reason:
type: string
enum:
- not_relevant
- too_complex
- competitor
description: Optional, with status archived only. competitor only on a PR & Citation Building item that targets a domain.
responses:
'200':
description: The updated item
content:
application/json:
schema:
$ref: '#/components/schemas/RecommendationItemUpdateResponse'
'403':
$ref: '#/components/responses/InsufficientScope'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
components:
schemas:
RecommendationItemUpdateResponse:
type: object
required:
- project_id
- item
- request_id
properties:
project_id:
type: integer
item:
$ref: '#/components/schemas/RecommendationItem'
request_id:
type: string
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
RecommendationItem:
type: object
description: One recommendation item, in the shape GET /recommendations/{id} lists items
required:
- id
- recommendation_id
- recommendation_type
- category
- title
- priority
- status
- position
- action_items
- source_refs
- created_at
- updated_at
properties:
id:
type: integer
recommendation_id:
type: integer
recommendation_type:
type: string
category:
type: string
title:
type: string
description:
type:
- string
- 'null'
priority:
type: string
enum:
- high
- medium
- low
estimated_impact:
type:
- string
- 'null'
action_items:
type: array
items:
type: string
source_refs:
type: array
items:
type: string
description: Evidence codes (e.g. P1, C2) resolved in resolved_source_refs
status:
type: string
enum:
- active
- completed
- archived
status_changed_at:
type:
- string
- 'null'
format: date-time
position:
type: integer
metadata:
type: object
additionalProperties: true
description: Free-form details. Carries effort (low, medium or high) when the generator rated it, archive_reason (not_relevant, too_complex or competitor) on an item archived with a reason, and domain on PR & Citation Building items.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
resolved_source_refs:
type: array
items:
type: object
additionalProperties: true
description: The evidence each source_refs code points to (prompt, citation or own page)
unresolved_source_refs:
type: array
items:
type: string
description: Present only when a code points to no stored evidence
PaginatedEnvelope:
type: object
description: Envelope shared by the paginated listings; each listing adds its own data rows
required:
- project_id
- page
- per_page
- total
- request_id
properties:
project_id:
type: integer
page:
type: integer
per_page:
type: integer
total:
type: integer
description: Rows matching the filters across every page
request_id:
type: string
RecommendationsResponse:
allOf:
- $ref: '#/components/schemas/PaginatedEnvelope'
- type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/RecommendationSummary'
RecommendationSummary:
type: object
required:
- id
- project_id
- recommendation_type
- status
- error_message
- generated_at
- created_at
- updated_at
- total_recommendations
- high_priority_count
- summary
- context
properties:
id:
type: integer
project_id:
type: integer
recommendation_type:
type: string
enum:
- ai_visibility
- social_community
- brand_building
- sentiment_reputation
status:
type: string
enum:
- pending
- processing
- completed
- failed
error_message:
type:
- string
- 'null'
description: Set only when status is failed
generated_at:
type:
- string
- 'null'
format: date-time
description: Null until the generation completes
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
total_recommendations:
type: integer
high_priority_count:
type: integer
summary:
type: object
description: Empty until the generation completes
properties:
total_recommendations:
type: integer
high_priority_count:
type: integer
categories:
type: array
items:
type: string
context:
type: object
description: Generation context and run diagnostics as stored; empty until the generation completes. Its keys are not a stable contract
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
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
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
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