LLM Pulse Collections & Tags API
Collections (labelled Tags in the app) group prompts by topic, funnel stage or campaign so metrics can be filtered by them.
Collections (labelled Tags in the app) group prompts by topic, funnel stage or campaign so metrics can be filtered by them.
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-collections-tags-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 Collections & Tags 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: Collections & Tags
description: Collections (labelled Tags in the app) group prompts by topic, funnel stage or campaign so metrics can be filtered by them.
paths:
/dimensions/collections:
get:
tags:
- Collections & Tags
summary: List tags/collections
x-llms-description: 'List prompt tags/collections (alias: /dimensions/tags).'
operationId: listCollections
x-mcp-tool: list_collections
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/Output'
responses:
'200':
description: Collections
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionsResponse'
/dimensions/tags:
get:
tags:
- Collections & Tags
summary: List tags (alias for /collections)
x-llms-description: Alias for /dimensions/collections.
operationId: listTags
x-mcp-tool: list_tags
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/Output'
responses:
'200':
description: Tags
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionsResponse'
/prompts/assign_tags:
post:
tags:
- Collections & Tags
summary: Bulk-attach tags to prompts
x-llms-description: Bulk-attach tags to existing prompts (resolve by id or name, optional create-on-the-fly). Idempotent.
operationId: assignPromptTags
x-mcp-tool: assign_prompt_tags
x-write: true
description: 'Idempotent bulk assignment of tags (Collections) to existing prompts. Tags can be resolved by id or by name (case-insensitive). Use `create_missing: true` to auto-create unknown tag names. Requires a `read_write` scope API key.'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- project_id
- prompt_ids
properties:
project_id:
type: integer
prompt_ids:
type: array
items:
type: integer
tag_ids:
type: array
items:
type: integer
tag_names:
type: array
items:
type: string
create_missing:
type: boolean
responses:
'200':
description: Tags attached
content:
application/json:
schema:
$ref: '#/components/schemas/PromptTagsAssignResponse'
'403':
$ref: '#/components/responses/InsufficientScope'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/prompts/remove_tags:
post:
tags:
- Collections & Tags
summary: Bulk-detach tags from prompts
x-llms-description: Bulk-detach tags from existing prompts (resolve by id or name). Never deletes tags or prompts. Idempotent.
operationId: removePromptTags
x-mcp-tool: remove_prompt_tags
x-write: true
description: 'Idempotent bulk removal of tags (Collections) from existing prompts: up to 500 prompt_ids and 50 tags, resolved by id or by name (case-insensitive). Only the prompt-tag links are removed; tags and prompts stay. Links that did not exist are counted in skipped_not_linked. Requires a `read_write` scope API key and, for team members, update access to Prompts.'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- project_id
- prompt_ids
properties:
project_id:
type: integer
prompt_ids:
type: array
items:
type: integer
tag_ids:
type: array
items:
type: integer
tag_names:
type: array
items:
type: string
responses:
'200':
description: Tags detached
content:
application/json:
schema:
$ref: '#/components/schemas/PromptTagsRemoveResponse'
'403':
$ref: '#/components/responses/InsufficientScope'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/collections:
post:
tags:
- Collections & Tags
summary: Create a tag
x-llms-description: Create a tag (Collection) in a project; can attach existing prompts in the same call.
operationId: createCollection
x-mcp-tool: create_collection
x-write: true
description: Creates a tag (Collection) in a project. Optional `prompt_ids` attaches existing prompts in the same call. Tag name must be unique per project (case-insensitive). Requires a `read_write` scope API key.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- project_id
- name
properties:
project_id:
type: integer
name:
type: string
description:
type: string
prompt_ids:
type: array
items:
type: integer
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionCreateResponse'
'403':
$ref: '#/components/responses/InsufficientScope'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/collections/{id}:
patch:
tags:
- Collections & Tags
summary: Update a tag
x-llms-description: Rename a tag/collection or change its description.
operationId: updateCollection
x-mcp-tool: update_collection
x-write: true
description: Renames a tag/collection or changes its description. Prompt membership is managed via POST /prompts/assign_tags, not here. 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
name:
type: string
description:
type: string
responses:
'200':
description: Updated
'403':
$ref: '#/components/responses/InsufficientScope'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
delete:
tags:
- Collections & Tags
summary: Delete a tag
x-llms-description: Delete a tag/collection; the prompts inside it are kept.
operationId: deleteCollection
x-mcp-tool: delete_collection
x-write: true
description: Deletes a tag/collection. The prompts inside it are NOT deleted; only the grouping disappears. 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/InsufficientScope'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
CollectionCreateResponse:
type: object
required:
- project_id
- collection
- prompts_attached
- total_collections
- request_id
properties:
project_id:
type: integer
collection:
type: object
required:
- id
- name
- description
properties:
id:
type: integer
name:
type: string
description:
type:
- string
- 'null'
prompts_attached:
type: integer
description: Existing prompts attached through prompt_ids
total_collections:
type: integer
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
TagRef:
type: object
required:
- id
- name
properties:
id:
type: integer
name:
type: string
PromptTagsRemoveResponse:
type: object
required:
- project_id
- prompts_targeted
- tags_detached
- links_removed
- skipped_not_linked
- missing_tag_names
- ignored_prompt_ids
- request_id
properties:
project_id:
type: integer
prompts_targeted:
type: integer
description: Prompts of the project among prompt_ids
tags_detached:
type: array
items:
$ref: '#/components/schemas/TagRef'
links_removed:
type: integer
skipped_not_linked:
type: integer
missing_tag_names:
type: array
items:
type: string
description: tag_names that matched no tag
ignored_prompt_ids:
type: array
items:
type: integer
description: prompt_ids that are not prompts of this project
request_id:
type: string
CollectionsResponse:
type: object
required:
- project_id
- collections
- request_id
properties:
project_id:
type: integer
collections:
type: array
items:
$ref: '#/components/schemas/TagRef'
request_id:
type: string
PromptTagsAssignResponse:
type: object
required:
- project_id
- prompts_targeted
- tags_attached
- new_links_created
- skipped_already_linked
- missing_tag_names
- ignored_prompt_ids
- request_id
properties:
project_id:
type: integer
prompts_targeted:
type: integer
description: Prompts of the project among prompt_ids
tags_attached:
type: array
items:
$ref: '#/components/schemas/TagRef'
new_links_created:
type: integer
skipped_already_linked:
type: integer
missing_tag_names:
type: array
items:
type: string
description: tag_names that matched no tag and were not created
ignored_prompt_ids:
type: array
items:
type: integer
description: prompt_ids that are not prompts of this project
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
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:
Output:
name: output
in: query
schema:
type: string
enum:
- flat
- csv
description: Rectangular output for BI tools (Tableau, Excel, Sheets, ELT). Omit for the default nested JSON. 'flat' returns the same metadata plus 'columns' and 'rows'; 'csv' returns those rows as text/csv. Errors are always returned as JSON.
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