# LLM Pulse API: llms.txt Last generated: 2026-10-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://api.llmpulse.ai/api-docs (one page per resource, listed under each section below) - Full machine reference: https://api.llmpulse.ai/api-docs/llms-full.txt - OpenAPI 3.0 spec: https://api.llmpulse.ai/openapi.json - Swagger 2.0 spec: https://api.llmpulse.ai/swagger.json - Postman collection: https://api.llmpulse.ai/LLMPulse_API_v1.postman_collection.json - Native Rust CLI (macOS, Linux, Windows): https://github.com/LLM-Pulse/llmpulse-cli/releases - CLI guide: https://api.llmpulse.ai/help-center/cli - Official SDKs (12 languages): https://github.com/orgs/LLM-Pulse/repositories?q=llmpulse- - SDK guide: https://api.llmpulse.ai/help-center/llm-pulse-sdks - MCP endpoint: POST https://api.llmpulse.ai/api/v1/mcp - ARD agent catalog (Agentic Resource Discovery): https://llmpulse.ai/.well-known/ai-catalog.json - 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. Get a key at https://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 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. - Project-scoped keys: a key can be limited to one or several projects when it is created, and the set never changes. It sees only those projects; any other project answers `ERR_PROJECT_NOT_FOUND` like one that does not exist, and creating projects or drafts answers `ERR_KEY_PROJECT_SCOPED`. - 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_INSUFFICIENT_PERMISSION` | 403 | Key owned by a team member whose permission matrix does not grant this feature. | | `ERR_KEY_PROJECT_SCOPED` | 403 | Key limited to some projects, used on an operation that acts on the whole account. | | `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 (the message names it). | | `ERR_INVALID_RANGE` | 422 | Search Console date range with from after to. | | `ERR_LIMIT_REACHED` | 422 | Project, prompt, technical GEO report or recommendation limit reached (the message says which). | | `ERR_QUOTA_EXCEEDED` | 422 | Competitor, GEO Writer task or webhook subscription cap reached (the message says which). | | `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 Docs: https://api.llmpulse.ai/api-docs - `GET /ping`: Health check; validates the API key and optionally pings a project. ### Account Docs: https://api.llmpulse.ai/api-docs - `GET /account`: Plan, subscription window, quota usage (prompts, projects, competitors, intelligence tasks) and API rate limits for the authenticated account. ### Projects Docs: https://api.llmpulse.ai/api-docs/projects - `GET /dimensions/locales`: List countries and languages with data for the project. - `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 /project_drafts/:id`: Read a draft: state, current step, accumulated data; include_suggestions=true returns cached suggestions only. - `PATCH /project_drafts/:id`: Submit a wizard step (details, prompts, competitors, owned_media) with strict forward gating; responds with next-step AI suggestions. - `PATCH /projects/:id`: Update the project profile / Brand Book (brand_name, description, industry, business_model, target_audience, brand_voice, goals, primary_products, matching_names). A matching_names change re-runs matching in the background. - `POST /project_drafts`: Start the multi-step project wizard: returns a draft_id + AI suggestions for the URL (name, description, industry, aliases). - `POST /project_drafts/:id/finalize`: Create the real project from a completed draft (idempotent; same effects as POST /projects). - `POST /projects`: Create a complete project in one call (name, locale, prompts, competitors, owned media, Brand Book profile); idempotent via external_identifier. ### Metrics Docs: https://api.llmpulse.ai/api-docs/metrics - `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 (sum for counts, average for rates; see aggregation field), 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. ### Competitors Docs: https://api.llmpulse.ai/api-docs/competitors - `DELETE /competitors/:id`: Delete a competitor (irreversible; frees a competitor slot; tracked data purged in the background). - `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. - `PATCH /competitors/:id`: Update a competitor (brand_name, matching_names, color; domain is immutable). Name changes re-run matching in the background. - `POST /competitors`: Add a competitor (brand_name + domain) to a project; respects the plan competitor cap. ### Prompts Docs: https://api.llmpulse.ai/api-docs/prompts - `DELETE /prompts/:id`: Delete a prompt (irreversible; frees a prompt slot; history purged in the background). - `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/query_fan_outs`: Query fan-out: the sub-queries models issued behind your prompts, per distinct sub-query (view=query) or per prompt (view=prompt). - `POST /prompts`: Bulk-create prompts (up to 100 per request); skips duplicates and validates the account prompt quota. ### Collections & Tags Docs: https://api.llmpulse.ai/api-docs/collections-and-tags - `DELETE /collections/:id`: Delete a tag/collection; the prompts inside it are kept. - `GET /dimensions/collections`: List prompt tags/collections (alias: /dimensions/tags). - `GET /dimensions/tags`: Alias for /dimensions/collections. - `PATCH /collections/:id`: Rename a tag/collection or change its description. - `POST /collections`: Create a tag (Collection) in a project; can attach existing prompts in the same call. - `POST /prompts/assign_tags`: Bulk-attach tags to existing prompts (resolve by id or name, optional create-on-the-fly). Idempotent. ### Answers Docs: https://api.llmpulse.ai/api-docs/answers - `GET /answers`: Paginated AI responses with truncated content (10k chars), counts, executed_at. query = full-text search (total becomes the exact match count; rows return snippet + match_count). - `GET /answers/:id`: Full AI response with mentions, citations, sentiments, sources, shopping_products, brand_entities, fan_out_queries. ### Mentions & Citations Docs: https://api.llmpulse.ai/api-docs/mentions-and-citations - `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/competitor_citations`: Paginated competitor citation records. - `GET /dimensions/competitor_mentions`: Paginated competitor mention records. - `GET /dimensions/mentions`: Paginated brand mention records (project brand only). ### Sentiments Docs: https://api.llmpulse.ai/api-docs/sentiments - `GET /dimensions/sentiments`: List sentiment categories (metric keys + labels + colors). For records use /sentiments. - `GET /sentiments`: Paginated sentiment analysis records with comments, topics, scores; filterable by analysis level and brand_only. ### Sources & Citation Intelligence Docs: https://api.llmpulse.ai/api-docs/citation-intelligence - `GET /citation_intelligence/groups`: Grouped citation intelligence by URL / domain / host with filters and per-model breakdown. - `GET /citation_intelligence/mentions_by_domain`: For responses citing each given source domain, the brand-vs-competitor mention share (sums to 100% per domain). - `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. - `GET /dimensions/sources`: Paginated list of every URL extracted from AI responses with source_type classification. ### AI Model Insights Docs: https://api.llmpulse.ai/api-docs/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. ### AI & Agent Traffic Docs: https://api.llmpulse.ai/api-docs/ai-traffic - `GET /dimensions/agent_bots`: Static catalog of AI bots that Agent Analytics can identify (slug, company, category). - `GET /metrics/agent_traffic`: AI bot crawler traffic by bot/company over time (Scale plan or above, Beta). - `GET /metrics/ai_traffic`: AI referral traffic (human visits from ChatGPT, Perplexity, Gemini, etc.) by source over time, from the connected web analytics provider (Scale plan or above). ### Shopping & Ads Docs: https://api.llmpulse.ai/api-docs/shopping-and-ads - `GET /dimensions/ads`: Paid placements returned inside AI answers, per advertising domain (view=advertisers) or per individual placement (view=ads), with counts and positions (Scale plan or above). - `GET /dimensions/local_businesses`: Local businesses listed inside AI answers, one row per business at its address, with appearances, prompts, average rating and position, and whether it is yours or a competitor (every plan). - `GET /dimensions/shopping`: Shopping results returned inside AI answers, per distinct product (view=products) or per selling merchant (view=merchants), with appearance counts, price range and rating (Scale plan or above). ### Owned Media & Communities Docs: https://api.llmpulse.ai/api-docs/owned-media - `GET /dimensions/owned_media`: Owned-media citations by platform (provider=youtube, instagram, facebook, tiktok, linkedin, mobile_apps): cited videos, posts, profiles, channels and app-store listings, each flagged as yours or not (Growth+). - `GET /dimensions/reddit`: Reddit content cited by AI answers, per subreddit (view=subreddits), per author (view=authors) or per thread (view=threads), with sentiment split and engagement (Growth+). ### Reputation & Studies Docs: https://api.llmpulse.ai/api-docs/reputation-and-studies - `GET /reputation/reports`: List the monthly reputation reports for a project, newest first, with status and which analyst models produced data. - `GET /reputation/reports/:id`: Reputation report scores as flat rows: one row per analyst model, brand, dimension and attribute, with score and reasoning. - `GET /studies`: List the custom AI studies defined on the account (account-scoped; project_id is an optional filter). - `GET /studies/:id`: One custom AI study with its brief, subjects, dimensions and report history. - `GET /studies/:id/reports/:report_id`: Custom study report scores as flat rows: one row per analyst model, subject, dimension and attribute, with score and reasoning. ### Search Console Docs: https://api.llmpulse.ai/api-docs/search-console - `GET /search_console/pages`: Top Google Search Console landing pages for a date range, ranked by impressions/clicks/CTR/position, paginated (Growth+). - `GET /search_console/queries`: Top Google Search Console search queries for a date range, ranked by impressions/clicks/CTR/position, paginated (Growth+). - `GET /search_console/summary`: Google Search Console headline totals (impressions, clicks, CTR, average position) for a date range, with optional country/device breakdown. Requires a connected GSC property (Growth+). - `GET /search_console/timeseries`: Google Search Console property-wide series (impressions, clicks, CTR, position) bucketed by day/week/month (Growth+). ### Recommendations Docs: https://api.llmpulse.ai/api-docs/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. - `POST /recommendations`: Launch a new recommendations generation (async, 1-3 min; consumes the weekly recommendation budget). Poll GET /recommendations/:id. ### GEO Writer Docs: https://api.llmpulse.ai/api-docs/geo-writer - `GET /intelligence_tasks`: List GEO Writer (formerly Content Intelligence) tasks for a project with task_type and status filters. - `GET /intelligence_tasks/:id`: Get one GEO Writer (formerly Content Intelligence) task with full result_data when completed (accepts numeric id or public_id). - `PATCH /intelligence_tasks/:id`: Edit the text of a completed GEO Writer task in place: edits maps dotted result_data paths (title, sections.0.content) to replacement text; the generated version is kept for revert. - `POST /intelligence_tasks`: Create a GEO Writer (formerly Content Intelligence) task (brief, create, update, pr_insights, custom, or product_listing with a product object); processed async. - `POST /intelligence_tasks/:id/revert`: Discard every manual edit on a GEO Writer task and restore the generated output. ### Technical GEO Reports Docs: https://api.llmpulse.ai/api-docs/technical-geo-reports - `GET /technical_geo_reports`: List technical GEO reports of one type for a project, newest first, with status and score. - `GET /technical_geo_reports/:id`: Get one technical GEO report with current status and full result_data when completed. - `PATCH /technical_geo_reports/:id/content`: Replace the llms.txt and llms-full.txt files of a completed llms_txt report: edits holds the full new text of one or both files and content_version must match result_data.content_version as last read; the generated files are kept for revert. - `POST /technical_geo_reports`: Run the full nine-report technical GEO analysis bundle for a URL + country. The bundle starts only when nine daily units remain; each successfully created report uses one unit, and reports that are not created use none. Optional output_language_code (ISO 639-1, or auto to keep the language of the website) sets the language of the llms.txt files. - `POST /technical_geo_reports/:id/revert_content`: Discard every manual edit on an llms_txt report and restore the generated llms.txt and llms-full.txt files. ### Annotations Docs: https://api.llmpulse.ai/api-docs/annotations - `DELETE /annotations/:id`: Delete an own-user annotation. Available on every plan. - `GET /annotations`: List project timeline annotations (user + system), with date and category filters. Available on every plan. - `PATCH /annotations/:id`: Update an own-user annotation (title, description, date, color, category). Available on every plan. - `POST /annotations`: Add a timeline annotation to a project. Available on every plan. ### Store Integrations Docs: https://api.llmpulse.ai/api-docs/store-integrations - `GET /ai_orders`: AI-referred store orders and revenue for a project: totals, per AI assistant and a daily series (default last 90 days). - `GET /catalog_prompt_suggestions`: List buyer prompts suggested from a store catalog, filterable by status and product. - `GET /store_connection`: 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. - `POST /catalog_prompt_suggestions`: Generate buyer prompt suggestions for up to 20 store catalog products (shares the hourly suggestion allowance). - `POST /catalog_prompt_suggestions/accept`: Track pending catalog suggestions as prompts, each tagged with a collection named after its product. - `POST /catalog_prompt_suggestions/reject`: Mark pending catalog suggestions as rejected. - `PUT /ai_orders`: Replace the daily AI-referred orders and revenue a store app reports for a window; raw referrers are classified and non-AI ones ignored. ### Webhooks Docs: https://api.llmpulse.ai/api-docs/webhooks - `DELETE /webhooks/:id`: Delete a webhook subscription; the target URL stops receiving events immediately. - `GET /webhooks`: List active webhook subscriptions for the account (optional project_id filter). - `GET /webhooks/sample/:event_type`: Up to 3 example event payloads for an event type, built from recent project data (used by integration editors). - `POST /webhooks`: Subscribe a public HTTPS URL to a project event (new mention, citation, execution, negative sentiment, completed report); deliveries are HMAC-signed. Scale plan or above. ### MCP Docs: https://api.llmpulse.ai/api-docs/integrations - `GET /mcp`: Model Context Protocol (MCP) JSON-RPC endpoint for AI clients (GET handshake). - `GET /mcp/server-card`: Public MCP server card describing the endpoint, transport and auth. No authentication required. - `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`. The recommended path on every plan is OAuth (your client walks the user through sign-in automatically). Headless clients on the Scale plan or above 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`. Tip: if your MCP client struggles to connect (MCP/OAuth support is still uneven across clients), an easy fallback on the Scale plan or above is to hand your AI assistant a Bearer API key plus a link to these docs. It can then call every REST endpoint directly over plain HTTP, no MCP client setup required. Tools currently registered (from `Mcp::LlmPulseServer::TOOLS`): - `ask_support` - `assign_prompt_tags` - `create_annotation` - `create_collection` - `create_competitor` - `create_intelligence_task` - `create_project` - `create_prompts` - `create_technical_geo_report` - `create_webhook_subscription` - `delete_annotation` - `delete_collection` - `delete_competitor` - `delete_prompt` - `delete_webhook_subscription` - `finalize_project_draft` - `get_account_usage` - `get_agent_traffic` - `get_ai_model_position_distribution` - `get_ai_model_summary` - `get_ai_orders` - `get_ai_overview_results` - `get_ai_traffic` - `get_answer` - `get_cited_url_content` - `get_cited_url_details` - `get_competitor_details` - `get_intelligence_task` - `get_mentions_by_citing_domain` - `get_project_details` - `get_project_draft` - `get_prompt_summary` - `get_recommendation` - `get_reputation_report` - `get_search_console_pages` - `get_search_console_queries` - `get_search_console_summary` - `get_search_console_timeseries` - `get_sov` - `get_study` - `get_study_report` - `get_summary` - `get_technical_geo_report` - `get_timeseries` - `get_top_sources` - `get_webhook_sample` - `launch_recommendations` - `list_ads` - `list_agent_bots` - `list_all_citations` - `list_all_mentions` - `list_annotations` - `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_local_businesses` - `list_locales` - `list_mentions` - `list_models` - `list_owned_media` - `list_projects` - `list_prompt_executions` - `list_prompts` - `list_query_fan_outs` - `list_recommendations` - `list_reddit_citations` - `list_reputation_reports` - `list_sentiments` - `list_shopping_products` - `list_sources` - `list_studies` - `list_tags` - `list_technical_geo_reports` - `list_webhook_subscriptions` - `remove_prompt_tags` - `revert_intelligence_task_content` - `revert_technical_geo_report_content` - `send_feedback` - `start_project_draft` - `update_annotation` - `update_collection` - `update_competitor` - `update_intelligence_task_content` - `update_project` - `update_project_draft` - `update_technical_geo_report_content` ## 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`. - Output format: read endpoints accept an optional `output` parameter. Omit it for the default nested JSON (unchanged); `output=flat` returns the same metadata plus `columns` and `rows`; `output=csv` returns those rows as text/csv for BI tools (Tableau, Excel, Sheets, warehouse loaders). Errors are always JSON. `/metrics/sov` also takes `view=over_time|current|breakdown`. - 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/."