Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: LLM Pulse Store Integrations 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: Store Integrations
description: 'The endpoints behind the LLM Pulse app for Shopify: match a store to its project, push the orders AI assistants referred to the store and read them back, and turn catalog products into buyer prompts to track. They need an API key (Scale plan or above) and are not available to accounts with a white-label portal or an embed, which receive ERR_INTEGRATION_UNAVAILABLE (403).'
paths:
/store_connection:
get:
tags:
- Store Integrations
summary: Match a store to a project
x-llms-description: 'Store app setup: whether the account may use a store integration and which project a store domain maps to, plus candidate projects. Not available to white-label or embed accounts.'
operationId: getStoreConnection
x-rest-only: Called by the store app (Shopify) to read its own connection, not by agents.
description: 'Tells a store app whether the API key''s account can use it and which project the store belongs to: the live project whose domain equals the store domain, else one whose domain is a parent or a subdomain of it, else null. candidates lists every live project of the account so the app can offer a picker. Pitch projects are never matched or listed, since a store is a data connection a pitch project does not take. Takes no project_id. Not available to accounts with a white-label portal or an embed (ERR_INTEGRATION_UNAVAILABLE).'
parameters:
- name: platform
in: query
required: true
schema:
type: string
enum:
- shopify
description: Store platform
- name: domain
in: query
required: true
schema:
type: string
description: Store domain, with or without scheme, e.g. acme-store.com
responses:
'200':
description: Eligibility, the matching project and the candidates
content:
application/json:
schema:
$ref: '#/components/schemas/StoreConnectionResponse'
'403':
$ref: '#/components/responses/IntegrationUnavailable'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/ai_orders:
get:
tags:
- Store Integrations
summary: Read AI-referred store orders
x-llms-description: 'AI-referred store orders and revenue for a project: totals, per AI assistant and a daily series (default last 90 days).'
operationId: listAiOrders
x-mcp-tool: get_ai_orders
x-mcp-plan: growth
description: 'Reads back the AI-referred orders a store app pushed for a project: totals, one row per AI assistant and a daily series of the days with orders. Revenue values are decimal strings in currency. Team members need read access to AI Traffic. Not available to accounts with a white-label portal or an embed (ERR_INTEGRATION_UNAVAILABLE).'
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: platform
in: query
schema:
type: string
enum:
- shopify
default: shopify
description: Store platform
- name: from
in: query
schema:
type: string
format: date
description: First day (YYYY-MM-DD). Defaults to 89 days before to
- name: to
in: query
schema:
type: string
format: date
description: Last day (YYYY-MM-DD). Defaults to today; the window is at most 400 days
responses:
'200':
description: Totals, per-assistant rows and the daily series
content:
application/json:
schema:
$ref: '#/components/schemas/AiOrdersResponse'
'403':
$ref: '#/components/responses/IntegrationUnavailable'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
put:
tags:
- Store Integrations
summary: Replace AI-referred store orders for a window
x-llms-description: Replace the daily AI-referred orders and revenue a store app reports for a window; raw referrers are classified and non-AI ones ignored.
operationId: replaceAiOrders
x-rest-only: Called by the store app (Shopify) to push AI-referred orders; agents read them with get_ai_orders.
x-write: true
description: 'Replaces the daily AI-referred orders and revenue of the from..to window. Send the raw referring host or utm_source of each order''s first visit as referrer: LLM Pulse classifies it and ignores anything that is not an AI assistant. Entries for the same day and assistant are summed. Every stored row of that project and platform inside the window is replaced, so pushing the same window again converges instead of counting twice. Rows are kept per project and platform, not per store, so one store reports per project. A pitch project takes no store data: pushing orders to one returns ERR_INVALID_PARAM. Requires a `read_write` scope API key and, for team members, update access to AI Traffic. Not available to accounts with a white-label portal or an embed (ERR_INTEGRATION_UNAVAILABLE).'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AiOrdersUpdateRequest'
responses:
'200':
description: Rows stored and entries ignored
content:
application/json:
schema:
$ref: '#/components/schemas/AiOrdersUpdateResponse'
'403':
$ref: '#/components/responses/IntegrationUnavailable'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/catalog_prompt_suggestions:
get:
tags:
- Store Integrations
summary: List catalog prompt suggestions
x-llms-description: List buyer prompts suggested from a store catalog, filterable by status and product.
operationId: listCatalogPromptSuggestions
x-rest-only: Store app (Shopify) catalog flow, not exposed to agents.
description: Lists the buyer prompts suggested from a store catalog, oldest first, with their status and the product each one came from. Team members need read access to Prompts. Not available to accounts with a white-label portal or an embed (ERR_INTEGRATION_UNAVAILABLE).
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: status
in: query
schema:
type: string
enum:
- pending
- accepted
- rejected
description: Only suggestions in this status
- name: product_external_id
in: query
schema:
type: string
description: Only suggestions for this store product id
- name: page
in: query
schema:
type: integer
default: 1
minimum: 1
- name: per_page
in: query
schema:
type: integer
default: 50
maximum: 100
minimum: 1
responses:
'200':
description: Paginated suggestions
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogPromptSuggestionsResponse'
'403':
$ref: '#/components/responses/IntegrationUnavailable'
'404':
$ref: '#/components/responses/NotFound'
post:
tags:
- Store Integrations
summary: Suggest buyer prompts from catalog products
x-llms-description: Generate buyer prompt suggestions for up to 20 store catalog products (shares the hourly suggestion allowance).
operationId: createCatalogPromptSuggestions
x-rest-only: Store app (Shopify) catalog flow, not exposed to agents.
x-write: true
description: Writes buyer prompts for up to 20 catalog products and saves them as pending suggestions in the project's Suggested prompts queue, with the product recorded on each. Generation draws on the hourly prompt-suggestion allowance the app also uses (ERR_QUOTA_EXCEEDED once it is used up); a failed generation returns ERR_GENERATION_FAILED (502) and can be retried. Requires a `read_write` scope API key and, for team members, create access to Prompts. Not available to accounts with a white-label portal or an embed (ERR_INTEGRATION_UNAVAILABLE).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogPromptSuggestionsCreateRequest'
responses:
'201':
description: The suggestions saved for these products
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogPromptSuggestionsCreateResponse'
'403':
$ref: '#/components/responses/IntegrationUnavailable'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'502':
$ref: '#/components/responses/GenerationFailed'
/catalog_prompt_suggestions/accept:
post:
tags:
- Store Integrations
summary: Accept catalog prompt suggestions
x-llms-description: Track pending catalog suggestions as prompts, each tagged with a collection named after its product.
operationId: acceptCatalogPromptSuggestions
x-rest-only: Store app (Shopify) catalog flow, not exposed to agents.
x-write: true
description: 'Starts tracking pending suggestions: each one becomes a prompt, tagged with a collection named after its product. Suggestions that are no longer pending come back in skipped. All accepted suggestions must share one country and language. When the new prompts would exceed the plan, the call returns ERR_LIMIT_REACHED and accepts nothing. The prompts of a launched pitch project are fixed, so accepting a suggestion returns ERR_INVALID_PARAM with error.meta.reason pitch_prompts_frozen. Requires a `read_write` scope API key and, for team members, create access to Prompts. Not available to accounts with a white-label portal or an embed (ERR_INTEGRATION_UNAVAILABLE).'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogPromptSuggestionIdsRequest'
responses:
'200':
description: Accepted and skipped suggestions
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogPromptSuggestionsAcceptResponse'
'403':
$ref: '#/components/responses/IntegrationUnavailable'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/catalog_prompt_suggestions/reject:
post:
tags:
- Store Integrations
summary: Reject catalog prompt suggestions
x-llms-description: Mark pending catalog suggestions as rejected.
operationId: rejectCatalogPromptSuggestions
x-rest-only: Store app (Shopify) catalog flow, not exposed to agents.
x-write: true
description: Marks pending suggestions as rejected; suggestions that are no longer pending stay as they are. Requires a `read_write` scope API key and, for team members, update access to Prompts. Not available to accounts with a white-label portal or an embed (ERR_INTEGRATION_UNAVAILABLE).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogPromptSuggestionIdsRequest'
responses:
'200':
description: How many suggestions were rejected
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogPromptSuggestionsRejectResponse'
'403':
$ref: '#/components/responses/IntegrationUnavailable'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
components:
schemas:
CatalogPromptSuggestionsRejectResponse:
type: object
required:
- project_id
- rejected
- request_id
properties:
project_id:
type: integer
rejected:
type: integer
request_id:
type: string
CatalogPromptSuggestionsResponse:
type: object
required:
- project_id
- page
- per_page
- total
- data
- request_id
properties:
project_id:
type: integer
page:
type: integer
per_page:
type: integer
total:
type: integer
data:
type: array
items:
$ref: '#/components/schemas/CatalogPromptSuggestion'
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
CatalogPromptSuggestionsCreateResponse:
type: object
required:
- project_id
- created
- skipped
- data
- request_id
properties:
project_id:
type: integer
created:
type: integer
skipped:
type: integer
description: Generated prompts not saved because the project already holds them as a suggestion (from any source or product, in any status).
data:
type: array
items:
$ref: '#/components/schemas/CatalogPromptSuggestion'
request_id:
type: string
AiOrdersUpdateRequest:
type: object
required:
- project_id
- platform
- currency
- from
- to
- days
properties:
project_id:
type: integer
platform:
type: string
enum:
- shopify
currency:
type: string
description: ISO 4217 code, e.g. EUR
from:
type: string
format: date
description: First day of the window this push replaces
to:
type: string
format: date
description: Last day of the window; at most 400 days after from
days:
type: array
maxItems: 400
items:
type: object
required:
- day
- referrer
- orders
- revenue
properties:
day:
type: string
format: date
description: Must fall inside from..to
referrer:
type: string
description: Raw referring host or utm_source of the order's first visit, e.g. chatgpt.com. Entries that are not an AI assistant are ignored
orders:
type: integer
minimum: 0
revenue:
type: string
description: Non-negative decimal amount in currency, e.g. 120.50. A JSON number is accepted too
CatalogProduct:
type: object
required:
- external_id
- title
properties:
external_id:
type: string
description: The store's product id, e.g. gid://shopify/Product/1
title:
type: string
handle:
type: string
product_type:
type: string
vendor:
type: string
tags:
type: array
maxItems: 20
items:
type: string
collections:
type: array
maxItems: 20
items:
type: string
url:
type: string
CatalogPromptSuggestionIdsRequest:
type: object
required:
- project_id
- ids
properties:
project_id:
type: integer
ids:
type: array
minItems: 1
maxItems: 100
items:
type: integer
CatalogPromptSuggestionsCreateRequest:
type: object
required:
- project_id
- platform
- products
properties:
project_id:
type: integer
platform:
type: string
enum:
- shopify
country_code:
type: string
description: Defaults to the project country
language_code:
type: string
description: Defaults to the project language
products:
type: array
minItems: 1
maxItems: 20
items:
$ref: '#/components/schemas/CatalogProduct'
CatalogPromptSuggestionsAcceptResponse:
type: object
required:
- project_id
- accepted
- skipped
- prompts_available
- request_id
properties:
project_id:
type: integer
accepted:
type: array
items:
type: object
required:
- suggestion_id
- prompt_id
- collection_id
properties:
suggestion_id:
type: integer
prompt_id:
type: integer
collection_id:
type:
- integer
- 'null'
description: The collection named after the product; null when the product has no title or the team member cannot create tags
skipped:
type: array
items:
type: object
required:
- suggestion_id
- reason
properties:
suggestion_id:
type: integer
reason:
type: string
description: accepted or rejected (the suggestion was no longer pending), or pending_deletion
prompts_available:
type:
- integer
- 'null'
description: Prompt slots left on the plan; null when unlimited
request_id:
type: string
StoreConnectionResponse:
type: object
required:
- platform
- domain
- project
- ambiguous
- candidates
- account
- request_id
properties:
platform:
type: string
description: The store platform, e.g. shopify
domain:
type: string
description: 'The store domain as compared: lowercase, without scheme, www or path'
project:
type:
- object
- 'null'
description: 'The live project the store maps to: its domain equals the store''s, or is a parent or subdomain of it. Null when no project matches'
required:
- id
- name
- domain
properties:
id:
type: integer
name:
type: string
domain:
type: string
country_code:
type:
- string
- 'null'
language_code:
type:
- string
- 'null'
ambiguous:
type: boolean
description: True when several live projects match the store domain (for example one project per market). project is then null and the app asks the key holder to pick from candidates.
candidates:
type: array
description: Every live project of the account, for a project picker
items:
type: object
required:
- id
- name
- domain
properties:
id:
type: integer
name:
type: string
domain:
type: string
description: Empty when the project has no website URL
account:
type: object
properties:
plan:
type:
- string
- 'null'
description: Internal plan key of the account, e.g. scale or scaleplus; null for a key limited to some projects
request_id:
type: string
CatalogPromptSuggestion:
type: object
required:
- id
- prompt
- status
- source
- country_code
- language_code
- product
- prompt_id
- accepted_at
- created_at
properties:
id:
type: integer
prompt:
type: string
status:
type: string
description: pending, accepted or rejected
source:
type: string
description: Always catalog
country_code:
type:
- string
- 'null'
language_code:
type:
- string
- 'null'
product:
type: object
description: The catalog product the suggestion was written for
properties:
external_id:
type:
- string
- 'null'
description: The store's product id, e.g. gid://shopify/Product/1
handle:
type:
- string
- 'null'
title:
type:
- string
- 'null'
prompt_id:
type:
- integer
- 'null'
description: The tracked prompt an accepted suggestion became; null until accepted
accepted_at:
type:
- string
- 'null'
format: date-time
description: When the suggestion was accepted; null until then
created_at:
type: string
format: date-time
AiOrdersUpdateResponse:
type: object
required:
- project_id
- platform
- stored
- ignored
- request_id
properties:
project_id:
type: integer
platform:
type: string
stored:
type: integer
description: Rows stored, one per day and AI assistant
ignored:
type: integer
description: Entries whose referrer is not an AI assistant
request_id:
type: string
AiOrdersResponse:
type: object
required:
- project_id
- platform
- currency
- from
- to
- totals
- by_source
- series
- request_id
properties:
project_id:
type: integer
platform:
type: string
currency:
type:
- string
- 'null'
description: ISO 4217 code of the most recent stored day; null when the window holds no stored order
from:
type: string
format: date
to:
type: string
format: date
totals:
type: object
required:
- orders
- revenue
properties:
orders:
type: integer
revenue:
type: string
description: Decimal amount with two decimals, e.g. 1834.20
by_source:
type: array
description: One row per AI assistant, highest revenue first
items:
type: object
required:
- source
- name
- orders
- revenue
properties:
source:
type: string
description: AI assistant slug, e.g. chatgpt or perplexity
name:
type: string
description: Display name, e.g. ChatGPT
orders:
type: integer
revenue:
type: string
series:
type: array
description: Days that have stored orders, oldest first
items:
type: object
required:
- day
- orders
- revenue
properties:
day:
type: string
format: date
orders:
type: integer
revenue:
type: string
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
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
GenerationFailed:
description: The AI generation failed; retry the request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ERR_GENERATION_FAILED
message: suggestions could not be generated, try again
request_id: abc-123
IntegrationUnavailable:
description: The account has a white-label portal or an embed, so store integrations are not available (ERR_INTEGRATION_UNAVAILABLE). Writes with a read-only key answer ERR_INSUFFICIENT_SCOPE, and a team member without the permission ERR_INSUFFICIENT_PERMISSION, with the same status
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ERR_INTEGRATION_UNAVAILABLE
message: Store integrations are not available for white-label or embed accounts
request_id: abc-123
parameters:
ProjectId:
name: project_id
in: query
required: true
schema:
type: integer
description: Project ID
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