# LLM Pulse API — llms.txt Last generated: 2026-06-06 LLM Pulse measures brand visibility and sentiment inside AI-generated answers (ChatGPT, Perplexity, Gemini, Google AI Overviews, Google AI Mode). This file is a machine-readable index of our REST API and MCP integration so AI agents can find the right endpoint without parsing the HTML docs. ## Key links - Human docs: https://llmpulse.net/api-docs - Full machine reference: https://llmpulse.net/api-docs/llms-full.txt - OpenAPI 3.0 spec: https://llmpulse.net/openapi.json - Swagger 2.0 spec: https://llmpulse.net/swagger.json - Postman collection: https://llmpulse.net/LLMPulse_API_v1.postman_collection.json - MCP endpoint: POST https://api.llmpulse.ai/api/v1/mcp - Support docs (mirrored): https://github.com/llmpulse/llmpulse/tree/main/docs/support-agent/api ## Authentication - REST API: send `Authorization: Bearer YOUR_API_KEY` on every request. Keys start with `llmpulse_`. Get a key at https://app.llmpulse.ai/app/api_keys (Scale plan or above). - MCP (`/api/v1/mcp`): same Bearer token works, AND we additionally support OAuth 2.1 with PKCE-S256 and Dynamic Client Registration (RFC 7591). OAuth-based MCP is available on every plan, including Starter, Growth and the free trial. Discovery: `GET /.well-known/oauth-authorization-server`. The recommended client setup is just to give your MCP client the URL `https://api.llmpulse.ai/api/v1/mcp` and let it walk the user through the OAuth flow. - Rate limit: 300 requests/minute, per token (API key or OAuth JWT). - All endpoints under `/api/v1/` return JSON. Errors use `{ "error": { "code": "...", "message": "...", "meta": {} }, "request_id": "..." }`. ## Error codes | Code | HTTP | Meaning | |---|---|---| | `ERR_MISSING_AUTH` | 401 | No Authorization header. | | `ERR_INVALID_API_KEY` | 401 | Unknown key. | | `ERR_REVOKED_API_KEY` | 403 | Key has been revoked. | | `ERR_PLAN_REQUIRED` | 403 | Endpoint requires a higher plan tier. | | `ERR_PROJECT_NOT_FOUND` | 404 | Project not found or not accessible. | | `ERR_NOT_FOUND` | 404 | Resource not found. | | `ERR_INVALID_PARAM` | 422 | Invalid parameter value. | | `ERR_INVALID_RANGE` | 422 | Invalid date range (from > to). | | `ERR_LIMIT_REACHED` | 422 | Prompt quota reached. | | `ERR_QUOTA_EXCEEDED` | 422 | Intelligence task quota exceeded. | | `ERR_RATE_LIMITED` | 429 | Rate limit exceeded. | ## Endpoints Base URL: `https://api.llmpulse.ai/api/v1` (relative paths below). List generated directly from the deployed Rails route table. ### Health - `GET /ping` — Health check; validates the API key and optionally pings a project. ### Metrics - `GET /metrics/agent_traffic` — AI bot crawler traffic by bot/company over time (Scale+, Beta). - `GET /metrics/prompt_summary` — Paginated per-prompt metrics (responses, mentions, citations, mention_rate, citation_rate, avg position). - `GET /metrics/sov` — Share of Voice for the project vs competitors (over time, current snapshot, Top-4 + Others breakdown). - `GET /metrics/summary` — Aggregated period summary with totals, min/max/last, plus position distribution. - `GET /metrics/timeseries` — Time-series for one or more metrics, broken down by actor (brand + competitors). - `GET /metrics/top_sources` — Top cited domains across AI responses with sortable mention/citation stats. ### Dimensions - `GET /dimensions/agent_bots` — Static catalog of AI bots that Agent Analytics can identify (slug, company, category). - `GET /dimensions/all_citations` — Unified brand + competitor citations in one stream (actor_type field discriminates). - `GET /dimensions/all_mentions` — Unified brand + competitor mentions in one stream (actor_type field discriminates). - `GET /dimensions/citations` — Paginated brand citation records (project brand only). - `GET /dimensions/collections` — List prompt tags/collections (alias: /dimensions/tags). - `GET /dimensions/competitor_citations` — Paginated competitor citation records. - `GET /dimensions/competitor_mentions` — Paginated competitor mention records. - `GET /dimensions/competitors` — List competitors for a project (optionally including the project brand as actor_type=project). - `GET /dimensions/competitors/:id` — Detailed info for one competitor: matching names, app store IDs, color. - `GET /dimensions/locales` — List countries and languages with data for the project. - `GET /dimensions/mentions` — Paginated brand mention records (project brand only). - `GET /dimensions/models` — List AI models the project has execution data for. - `GET /dimensions/projects` — List all projects accessible to the API key. - `GET /dimensions/projects/:id` — Detailed info for one project: matching names, locale, industry, app store IDs, stats. - `GET /dimensions/prompt_executions` — Paginated list of execution records: model, executed_at, success, fan_out_queries, counts. - `GET /dimensions/prompts` — Paginated list of prompts with their primary tag, all tags, locale, and last_executed_at. - `GET /dimensions/sentiments` — List sentiment categories (metric keys + labels + colors). For records use /sentiments. - `GET /dimensions/sources` — Paginated list of every URL extracted from AI responses with source_type classification. - `GET /dimensions/tags` — Alias for /dimensions/collections. ### Citation Intelligence - `GET /citation_intelligence/groups` — Grouped citation intelligence by URL / domain / host with filters and per-model breakdown. - `GET /citation_intelligence/urls/:url_sha256` — Per-URL detail: counts, citation rate, page-cache metadata, page mention evidence. - `GET /citation_intelligence/urls/:url_sha256/content` — Sanitized cached page content for a cited URL plus mention evidence. - `GET /citation_intelligence/urls/:url_sha256/occurrences` — Paginated occurrences of a cited URL across prompt executions. ### AI Model Insights - `GET /reports/ai_model_insights/ai_overview_results` — Google AI Overview result-availability data with by-prompt result-rate table. - `GET /reports/ai_model_insights/position_distribution` — Per-model position distribution comparison (Position 1, 2-3, 4-7, 8+) for one or two brands. - `GET /reports/ai_model_insights/summary` — AI Model Insights summary: per-model mentions, citations, sentiment, weighted visibility, actor matrices. ### Answers - `GET /answers` — Paginated AI responses with truncated content (10k chars), counts, executed_at. - `GET /answers/:id` — Full AI response with mentions, citations, sentiments, sources, shopping_products, brand_entities, fan_out_queries. ### Sentiments - `GET /sentiments` — Paginated sentiment analysis records with comments, topics, scores; filterable by analysis level and brand_only. ### Recommendations - `GET /recommendations` — List recommendation runs for a project (filter by recommendation_type and status). - `GET /recommendations/:id` — Detailed recommendation run with items, action steps, priorities, and resolved source references. ### Prompts - `POST /prompts` — Bulk-create prompts (up to 100 per request); skips duplicates and validates the account prompt quota. - `POST /prompts/assign_tags` — Bulk-attach tags to existing prompts (resolve by id or name, optional create-on-the-fly). Idempotent. ### Competitors - `POST /competitors` — Add a competitor (brand_name + domain) to a project; respects the plan competitor cap. ### Collections - `POST /collections` — Create a tag (Collection) in a project; can attach existing prompts in the same call. ### Annotations - `POST /annotations` — Add a timeline annotation to a project (requires Growth+). ### Technical GEO Reports - `POST /technical_geo_reports` — Run the full technical GEO analysis bundle (crawlability, schema, content readiness, discoverability, site structure, robots.txt, llms.txt, AI visibility) for a URL + country. ### Content Intelligence - `GET /intelligence_tasks` — List Content Intelligence tasks for a project with task_type and status filters. - `GET /intelligence_tasks/:id` — Get one Content Intelligence task with full result_data when completed (accepts numeric id or public_id). - `POST /intelligence_tasks` — Create a Content Intelligence task (brief, create, update, pr_insights, custom); processed async. ### MCP - `GET /mcp` — Model Context Protocol (MCP) JSON-RPC endpoint for AI clients (GET handshake). - `POST /mcp` — Model Context Protocol (MCP) JSON-RPC endpoint for AI clients. ## MCP tools The same data is available through Model Context Protocol. Configure your MCP client to call `https://api.llmpulse.ai/api/v1/mcp` — recommended path on every plan is OAuth (your client walks the user through sign-in automatically). Headless clients on Scale+ can use the Bearer API key above instead. The server filters `tools/list` by the users plan, so they only see tools they can call. Tools that fail a plan check return `ERR_PLAN_REQUIRED`. Tools currently registered (from `Mcp::LlmPulseServer::TOOLS`): - `assign_prompt_tags` - `create_annotation` - `create_collection` - `create_competitor` - `create_intelligence_task` - `create_prompts` - `create_technical_geo_report` - `get_agent_traffic` - `get_ai_model_position_distribution` - `get_ai_model_summary` - `get_ai_overview_results` - `get_answer` - `get_cited_url_content` - `get_cited_url_details` - `get_competitor_details` - `get_intelligence_task` - `get_project_details` - `get_prompt_summary` - `get_recommendation` - `get_sov` - `get_summary` - `get_timeseries` - `get_top_sources` - `launch_recommendations` - `list_agent_bots` - `list_all_citations` - `list_all_mentions` - `list_answers` - `list_citation_groups` - `list_citations` - `list_cited_url_occurrences` - `list_collections` - `list_competitor_citations` - `list_competitor_mentions` - `list_competitors` - `list_detailed_sentiments` - `list_intelligence_tasks` - `list_locales` - `list_mentions` - `list_models` - `list_projects` - `list_prompt_executions` - `list_prompts` - `list_recommendations` - `list_sentiments` - `list_sources` - `list_tags` ## Conventions - All timestamps are ISO 8601 UTC unless noted; date-bucketed metrics are computed in `Europe/Madrid` to match the in-app charts. - Pagination: `page` (default 1) + `per_page` (default 20, max 100). Responses include `total` and `data`. - Date ranges: use `from` + `to` (ISO 8601) OR `range` (number of days). Metrics endpoints default to 30 days when neither is provided. - Metric aliases: `mention_rate` and `visibility` are interchangeable; `weighted_visibility` and `ai_visibility_score` are interchangeable. - `brand_name` is the LLM-facing brand label (returned alongside `name`, the internal project label). - Per-user AI model flags silently filter unauthorized models from every read endpoint. ## How to cite "LLM Pulse API v1 (YYYY-MM-DD), , https://api.llmpulse.ai/api-docs/."