{ "swagger": "2.0", "info": { "title": "LLM Pulse API", "description": "REST API for the LLM Pulse AI visibility platform. Swagger 2.0 spec kept in sync with the OpenAPI 3.0 spec at /openapi.json. OAuth 2.1 endpoints (/oauth/authorize, /oauth/token, /oauth/register, /oauth/jwks.json, /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource) are at the host root (outside this spec's /api/v1 basePath) — see the OpenAPI 3.0 spec for full schemas. For full endpoint reference (including response shapes) see /api-docs/llms-full.txt or https://api.llmpulse.ai/api-docs.", "version": "1.8.1", "contact": { "name": "LLM Pulse Support", "url": "https://llmpulse.ai", "email": "info@llmpulse.ai" }, "license": { "name": "Proprietary", "url": "https://llmpulse.ai/terms" } }, "host": "api.llmpulse.ai", "basePath": "/api/v1", "schemes": ["https"], "consumes": ["application/json"], "produces": ["application/json"], "securityDefinitions": { "BearerAuth": { "type": "apiKey", "name": "Authorization", "in": "header", "description": "Send `Bearer YOUR_API_KEY`. Keys start with `llmpulse_` and are managed at https://app.llmpulse.ai/app/api_keys." } }, "security": [{ "BearerAuth": [] }], "tags": [ { "name": "Health", "description": "API health check" }, { "name": "Dimensions", "description": "Lists of projects, competitors, prompts, mentions, citations and other dimensional entities" }, { "name": "Metrics", "description": "Aggregated time-series, summary, Share of Voice, top sources and agent-traffic metrics" }, { "name": "Citation Intelligence", "description": "Grouped cited-URL intelligence with page-cache metadata and mention evidence" }, { "name": "AI Model Insights", "description": "Aggregate AI Model Insights report endpoints" }, { "name": "Answers", "description": "Raw AI responses with mentions, citations, sentiments, sources" }, { "name": "Sentiments", "description": "Per-execution sentiment analysis records" }, { "name": "Recommendations", "description": "Recommendation runs powering the in-app Recommendations experience" }, { "name": "Prompts", "description": "Bulk-create prompts" }, { "name": "Content Intelligence", "description": "Create and inspect Content Intelligence tasks" }, { "name": "MCP", "description": "Model Context Protocol endpoint for AI clients" } ], "parameters": { "ProjectId": { "name": "project_id", "in": "query", "required": true, "type": "integer", "description": "Project ID" }, "Competitors": { "name": "competitors", "in": "query", "type": "string", "description": "Comma-separated competitor IDs" }, "Page": { "name": "page", "in": "query", "type": "integer", "default": 1, "minimum": 1 }, "PerPage": { "name": "per_page", "in": "query", "type": "integer", "default": 20, "maximum": 100, "minimum": 1 }, "Metrics": { "name": "metrics", "in": "query", "type": "string", "description": "Comma-separated list of metrics: mentions, citations, responses, mention_rate, visibility, weighted_visibility, ai_visibility_score, citation_rate, avg_position, avg_mention_position, net_sentiment, sentiment_*_*" }, "Granularity": { "name": "granularity", "in": "query", "type": "string", "enum": ["day", "week", "month"] }, "Range": { "name": "range", "in": "query", "type": "integer", "description": "Number of days to look back" }, "From": { "name": "from", "in": "query", "type": "string", "format": "date-time" }, "To": { "name": "to", "in": "query", "type": "string", "format": "date-time" }, "Model": { "name": "model", "in": "query", "type": "string", "enum": ["chatgpt", "perplexity", "gemini", "ai_overview", "ai_mode", "copilot", "claude", "grok", "deepseek", "meta_ai"], "description": "Filter by AI model. Models the API key's user has not enabled are silently dropped." }, "CollectionId": { "name": "collection_id", "in": "query", "type": "integer" }, "CountryCode": { "name": "country_code", "in": "query", "type": "string" }, "LanguageCode": { "name": "language_code", "in": "query", "type": "string" }, "Prompt": { "name": "prompt", "in": "query", "type": "integer" }, "PromptType": { "name": "prompt_type", "in": "query", "type": "string", "enum": ["informational", "navigational", "commercial", "transactional"], "description": "Filter by prompt type (search intent)." }, "BrandKind": { "name": "brand_kind", "in": "query", "type": "string", "enum": ["brand", "brand_other", "non_brand"], "description": "Filter by brand kind: brand (own brand/products), brand_other (competitors/other brands), non_brand (generic, no brand named)." }, "IncludeProject":{ "name": "include_project","in": "query", "type": "boolean", "default": true }, "UrlSha256": { "name": "url_sha256", "in": "path", "required": true, "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "64-character hex SHA-256 of the cited URL" } }, "paths": { "/ping": { "get": { "tags": ["Health"], "summary": "Health check", "operationId": "ping", "description": "Validates the API key and optionally pings a project.", "parameters": [ { "name": "project_id", "in": "query", "required": false, "type": "integer" } ], "responses": { "200": { "description": "API is healthy" }, "401": { "$ref": "#/responses/Unauthorized" } } } }, "/metrics/timeseries": { "get": { "tags": ["Metrics"], "summary": "Time-series metrics", "operationId": "getTimeseries", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Metrics" }, { "$ref": "#/parameters/Granularity" }, { "$ref": "#/parameters/Range" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" }, { "$ref": "#/parameters/Competitors" }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/CountryCode" }, { "$ref": "#/parameters/LanguageCode" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/PromptType" }, { "$ref": "#/parameters/BrandKind" }, { "$ref": "#/parameters/IncludeProject" } ], "responses": { "200": { "description": "Time-series data" }, "401": { "$ref": "#/responses/Unauthorized" }, "404": { "$ref": "#/responses/NotFound" }, "422": { "$ref": "#/responses/UnprocessableEntity" } } } }, "/metrics/summary": { "get": { "tags": ["Metrics"], "summary": "Aggregated metrics summary", "operationId": "getSummary", "description": "Same as /metrics/timeseries with an extra summary + position_distribution block.", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Metrics" }, { "$ref": "#/parameters/Granularity" }, { "$ref": "#/parameters/Range" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" }, { "$ref": "#/parameters/Competitors" }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/PromptType" }, { "$ref": "#/parameters/BrandKind" } ], "responses": { "200": { "description": "Summary metrics" } } } }, "/metrics/prompt_summary": { "get": { "tags": ["Metrics"], "summary": "Per-prompt metrics summary", "operationId": "getPromptSummary", "description": "Paginated per-prompt aggregated metrics with optional breakdown=model.", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Range" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" }, { "name": "breakdown", "in": "query", "type": "string", "enum": ["model"] }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/CountryCode" }, { "$ref": "#/parameters/LanguageCode" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/PromptType" }, { "$ref": "#/parameters/BrandKind" }, { "name": "sort", "in": "query", "type": "string", "enum": ["responses", "mentions", "citations", "mention_rate", "visibility", "citation_rate", "avg_mention_position", "avg_position"], "default": "responses" }, { "name": "sort_dir", "in": "query", "type": "string", "enum": ["asc", "desc"], "default": "desc" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" } ], "responses": { "200": { "description": "Per-prompt metrics" } } } }, "/metrics/sov": { "get": { "tags": ["Metrics"], "summary": "Share of Voice", "operationId": "getShareOfVoice", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Range" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" }, { "$ref": "#/parameters/Granularity" }, { "$ref": "#/parameters/Competitors" }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/PromptType" }, { "$ref": "#/parameters/BrandKind" } ], "responses": { "200": { "description": "Share of voice data" } } } }, "/metrics/top_sources": { "get": { "tags": ["Metrics"], "summary": "Top cited sources", "operationId": "getTopSources", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Range" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/CountryCode" }, { "$ref": "#/parameters/LanguageCode" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/PromptType" }, { "$ref": "#/parameters/BrandKind" }, { "name": "sort", "in": "query", "type": "string", "enum": ["total_responses", "avg_mention_rate", "avg_visibility"], "default": "total_responses" }, { "name": "query", "in": "query", "type": "string" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" } ], "responses": { "200": { "description": "Top sources" } } } }, "/metrics/agent_traffic": { "get": { "tags": ["Metrics"], "summary": "AI bot crawler traffic (Scale+, Beta)", "operationId": "getAgentTraffic", "description": "Aggregated AI bot traffic. Requires the Scale plan; lower tiers receive ERR_PLAN_REQUIRED.", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Range" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" }, { "name": "bot", "in": "query", "type": "string" }, { "name": "company", "in": "query", "type": "string" }, { "name": "group_by", "in": "query", "type": "string", "enum": ["bot", "company"], "default": "bot" }, { "$ref": "#/parameters/Granularity" } ], "responses": { "200": { "description": "Agent traffic data" }, "403": { "$ref": "#/responses/PlanRequired" } } } }, "/dimensions/projects": { "get": { "tags": ["Dimensions"], "summary": "List projects", "operationId": "listProjects", "responses": { "200": { "description": "Projects" } } } }, "/dimensions/projects/{id}": { "get": { "tags": ["Dimensions"], "summary": "Project details", "operationId": "getProjectDetails", "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer" } ], "responses": { "200": { "description": "Project details" } } } }, "/dimensions/competitors": { "get": { "tags": ["Dimensions"], "summary": "List competitors", "operationId": "listCompetitors", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "name": "include_project_brand", "in": "query", "type": "boolean", "default": false } ], "responses": { "200": { "description": "Competitors" } } } }, "/dimensions/competitors/{id}": { "get": { "tags": ["Dimensions"], "summary": "Competitor details", "operationId": "getCompetitorDetails", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "name": "id", "in": "path", "required": true, "type": "integer" } ], "responses": { "200": { "description": "Competitor details" } } } }, "/dimensions/collections": { "get": { "tags": ["Dimensions"], "summary": "List tags/collections", "operationId": "listCollections", "parameters": [ { "$ref": "#/parameters/ProjectId" } ], "responses": { "200": { "description": "Collections" } } } }, "/dimensions/tags": { "get": { "tags": ["Dimensions"], "summary": "List tags (alias)", "operationId": "listTags", "parameters": [ { "$ref": "#/parameters/ProjectId" } ], "responses": { "200": { "description": "Tags" } } } }, "/dimensions/models": { "get": { "tags": ["Dimensions"], "summary": "List models with data", "operationId": "listModels", "parameters": [ { "$ref": "#/parameters/ProjectId" } ], "responses": { "200": { "description": "Models" } } } }, "/dimensions/locales": { "get": { "tags": ["Dimensions"], "summary": "List locales", "operationId": "listLocales", "parameters": [ { "$ref": "#/parameters/ProjectId" } ], "responses": { "200": { "description": "Locales" } } } }, "/dimensions/sentiments": { "get": { "tags": ["Dimensions"], "summary": "List sentiment categories", "operationId": "listSentimentCategories", "parameters": [ { "$ref": "#/parameters/ProjectId" } ], "responses": { "200": { "description": "Sentiment buckets" } } } }, "/dimensions/prompts": { "get": { "tags": ["Dimensions"], "summary": "List prompts", "operationId": "listPrompts", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/CountryCode" }, { "$ref": "#/parameters/LanguageCode" }, { "$ref": "#/parameters/PromptType" }, { "$ref": "#/parameters/BrandKind" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" } ], "responses": { "200": { "description": "Paginated prompts" } } } }, "/dimensions/prompt_executions":{ "get": { "tags": ["Dimensions"], "summary": "List prompt executions", "operationId": "listPromptExecutions", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/CountryCode" }, { "$ref": "#/parameters/LanguageCode" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" } ], "responses": { "200": { "description": "Paginated executions" } } } }, "/dimensions/sources": { "get": { "tags": ["Dimensions"], "summary": "List source URLs", "operationId": "listSources", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/CountryCode" }, { "$ref": "#/parameters/LanguageCode" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" }, { "name": "source_type", "in": "query", "type": "string", "enum": ["owned", "competitor", "third_party"] } ], "responses": { "200": { "description": "Paginated sources" } } } }, "/dimensions/mentions": { "get": { "tags": ["Dimensions"], "summary": "List brand mentions", "operationId": "listMentions", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/CountryCode" }, { "$ref": "#/parameters/LanguageCode" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" } ], "responses": { "200": { "description": "Paginated mentions" } } } }, "/dimensions/citations": { "get": { "tags": ["Dimensions"], "summary": "List brand citations", "operationId": "listCitations", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/CountryCode" }, { "$ref": "#/parameters/LanguageCode" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" } ], "responses": { "200": { "description": "Paginated citations" } } } }, "/dimensions/competitor_mentions": { "get": { "tags": ["Dimensions"], "summary": "List competitor mentions", "operationId": "listCompetitorMentions", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Competitors" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" } ], "responses": { "200": { "description": "Paginated competitor mentions" } } } }, "/dimensions/competitor_citations": { "get": { "tags": ["Dimensions"], "summary": "List competitor citations", "operationId": "listCompetitorCitations", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Competitors" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" } ], "responses": { "200": { "description": "Paginated competitor citations" } } } }, "/dimensions/all_mentions": { "get": { "tags": ["Dimensions"], "summary": "List all mentions (brand + competitor)", "operationId": "listAllMentions", "description": "Each record has an actor_type field.", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Competitors" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" } ], "responses": { "200": { "description": "Paginated mentions" } } } }, "/dimensions/all_citations": { "get": { "tags": ["Dimensions"], "summary": "List all citations (brand + competitor)", "operationId": "listAllCitations", "description": "Each record has an actor_type field.", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Competitors" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" } ], "responses": { "200": { "description": "Paginated citations" } } } }, "/dimensions/agent_bots": { "get": { "tags": ["Dimensions"], "summary": "AI bot catalog", "operationId": "listAgentBots", "parameters": [ { "$ref": "#/parameters/ProjectId" } ], "responses": { "200": { "description": "Bot catalog" } } } }, "/citation_intelligence/groups": { "get": { "tags": ["Citation Intelligence"], "summary": "Grouped citation intelligence", "operationId": "listCitationGroups", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "name": "view", "in": "query", "type": "string", "enum": ["url", "domain", "host"], "default": "url" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" }, { "name": "order", "in": "query", "type": "string", "enum": ["group_key", "total_responses", "total_citations", "citation_rate", "avg_citation_position", "first_seen_at", "last_seen_at"] }, { "name": "direction", "in": "query", "type": "string", "enum": ["asc", "desc"] }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/CountryCode" }, { "$ref": "#/parameters/LanguageCode" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" }, { "name": "query", "in": "query", "type": "string" }, { "name": "source_type", "in": "query", "type": "string", "enum": ["owned", "competitor", "third_party", "social_media", "own_domain", "ugc", "background"] }, { "name": "sentiment", "in": "query", "type": "string", "enum": ["negative"] }, { "name": "content_gap", "in": "query", "type": "string", "enum": ["mentioned", "gap"] } ], "responses": { "200": { "description": "Grouped citation intelligence" }, "422": { "$ref": "#/responses/UnprocessableEntity" } } } }, "/citation_intelligence/urls/{url_sha256}": { "get": { "tags": ["Citation Intelligence"], "summary": "Cited URL detail", "operationId": "getCitedUrlDetail", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/UrlSha256" } ], "responses": { "200": { "description": "URL-level intelligence" } } } }, "/citation_intelligence/urls/{url_sha256}/occurrences": { "get": { "tags": ["Citation Intelligence"], "summary": "Cited URL occurrences", "operationId": "listCitedUrlOccurrences", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/UrlSha256" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" } ], "responses": { "200": { "description": "Paginated occurrences" } } } }, "/citation_intelligence/urls/{url_sha256}/content": { "get": { "tags": ["Citation Intelligence"], "summary": "Cited URL cached content", "operationId": "getCitedUrlContent", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/UrlSha256" } ], "responses": { "200": { "description": "Sanitized cached content" } } } }, "/reports/ai_model_insights/summary": { "get": { "tags": ["AI Model Insights"], "summary": "AI Model Insights summary", "operationId": "getAiModelInsightsSummary", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Range" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" }, { "$ref": "#/parameters/Granularity" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/CountryCode" }, { "$ref": "#/parameters/LanguageCode" }, { "$ref": "#/parameters/Competitors" } ], "responses": { "200": { "description": "Summary" } } } }, "/reports/ai_model_insights/position_distribution": { "get": { "tags": ["AI Model Insights"], "summary": "Position distribution comparison", "operationId": "getAiModelPositionDistribution", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Range" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" }, { "$ref": "#/parameters/Granularity" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/CountryCode" }, { "$ref": "#/parameters/LanguageCode" }, { "$ref": "#/parameters/Model" }, { "name": "brand1", "in": "query", "type": "integer" }, { "name": "brand2", "in": "query", "type": "integer" } ], "responses": { "200": { "description": "Bucketed position totals" } } } }, "/reports/ai_model_insights/ai_overview_results": { "get": { "tags": ["AI Model Insights"], "summary": "Google AI Overview result availability", "operationId": "getAiOverviewResults", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Range" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" }, { "$ref": "#/parameters/Granularity" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/CountryCode" }, { "$ref": "#/parameters/LanguageCode" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" } ], "responses": { "200": { "description": "AI Overview results" } } } }, "/answers": { "get": { "tags": ["Answers"], "summary": "List AI responses", "operationId": "listAnswers", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/CountryCode" }, { "$ref": "#/parameters/LanguageCode" }, { "$ref": "#/parameters/Prompt" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" } ], "responses": { "200": { "description": "Paginated answers" } } } }, "/answers/{id}": { "get": { "tags": ["Answers"], "summary": "Get one AI response", "operationId": "getAnswer", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "name": "id", "in": "path", "required": true, "type": "integer" }, { "name": "include_source_page_details", "in": "query", "type": "boolean", "default": false } ], "responses": { "200": { "description": "Answer details" } } } }, "/sentiments": { "get": { "tags": ["Sentiments"], "summary": "List sentiment records", "operationId": "listSentimentRecords", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "name": "competitor_id", "in": "query", "type": "integer" }, { "name": "brand_only", "in": "query", "type": "boolean" }, { "name": "analysis", "in": "query", "type": "string", "enum": ["very_positive", "positive", "neutral", "negative", "very_negative"] }, { "$ref": "#/parameters/Model" }, { "$ref": "#/parameters/CollectionId" }, { "$ref": "#/parameters/CountryCode" }, { "$ref": "#/parameters/LanguageCode" }, { "$ref": "#/parameters/From" }, { "$ref": "#/parameters/To" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" } ], "responses": { "200": { "description": "Paginated sentiments" } } } }, "/recommendations": { "get": { "tags": ["Recommendations"], "summary": "List recommendation runs", "operationId": "listRecommendations", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "name": "recommendation_type", "in": "query", "type": "string", "enum": ["ai_visibility", "social_community", "brand_building", "sentiment_reputation"] }, { "name": "status", "in": "query", "type": "string", "enum": ["pending", "processing", "completed", "failed"] }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" } ], "responses": { "200": { "description": "Paginated recommendations" } } } }, "/recommendations/{id}": { "get": { "tags": ["Recommendations"], "summary": "Get recommendation run", "operationId": "getRecommendation", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "name": "id", "in": "path", "required": true, "type": "integer" }, { "name": "item_status", "in": "query", "type": "string", "enum": ["active", "completed", "archived"] }, { "name": "resolve_source_refs", "in": "query", "type": "boolean", "default": true } ], "responses": { "200": { "description": "Recommendation detail" } } } }, "/prompts": { "post": { "tags": ["Prompts"], "summary": "Bulk-create prompts", "operationId": "createPrompts", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "required": ["project_id", "prompts", "country_code", "language_code"], "properties": { "project_id": { "type": "integer" }, "prompts": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "country_code": { "type": "string" }, "language_code": { "type": "string" } } } } ], "responses": { "201": { "description": "Created" }, "403": { "$ref": "#/responses/InsufficientScope" }, "422": { "$ref": "#/responses/UnprocessableEntity" } } } }, "/prompts/assign_tags": { "post": { "tags": ["Prompts"], "summary": "Bulk-attach tags to prompts", "operationId": "assignPromptTags", "parameters": [ { "name": "body", "in": "body", "required": true, "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" }, "403": { "$ref": "#/responses/InsufficientScope" }, "422": { "$ref": "#/responses/UnprocessableEntity" } } } }, "/competitors": { "post": { "tags": ["Competitors"], "summary": "Add a competitor", "operationId": "createCompetitor", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "required": ["project_id", "brand_name", "domain"], "properties": { "project_id": { "type": "integer" }, "brand_name": { "type": "string" }, "domain": { "type": "string" }, "matching_names": { "type": "array", "items": { "type": "string" } } } } } ], "responses": { "201": { "description": "Created" }, "403": { "$ref": "#/responses/InsufficientScope" }, "422": { "$ref": "#/responses/UnprocessableEntity" } } } }, "/collections": { "post": { "tags": ["Collections"], "summary": "Create a tag", "operationId": "createCollection", "parameters": [ { "name": "body", "in": "body", "required": true, "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" }, "403": { "$ref": "#/responses/InsufficientScope" }, "422": { "$ref": "#/responses/UnprocessableEntity" } } } }, "/annotations": { "post": { "tags": ["Annotations"], "summary": "Create a timeline annotation (Growth+)", "operationId": "createAnnotation", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "required": ["project_id", "title"], "properties": { "project_id": { "type": "integer" }, "title": { "type": "string" }, "annotation_date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "color": { "type": "string" }, "annotation_category_id": { "type": "integer" } } } } ], "responses": { "201": { "description": "Created" }, "403": { "$ref": "#/responses/PlanRequired" }, "422": { "$ref": "#/responses/UnprocessableEntity" } } } }, "/technical_geo_reports": { "post": { "tags": ["Reports"], "summary": "Run technical GEO analysis", "operationId": "createTechnicalGeoReports", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "required": ["project_id", "url"], "properties": { "project_id": { "type": "integer" }, "url": { "type": "string" }, "country_code": { "type": "string" } } } } ], "responses": { "201": { "description": "Created" }, "403": { "$ref": "#/responses/InsufficientScope" }, "422": { "$ref": "#/responses/UnprocessableEntity" } } } }, "/intelligence_tasks": { "get": { "tags": ["Content Intelligence"], "summary": "List Content Intelligence tasks", "operationId": "listIntelligenceTasks", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "name": "task_type", "in": "query", "type": "string", "enum": ["brief", "create", "update", "pr_insights", "custom"] }, { "name": "status", "in": "query", "type": "string" }, { "$ref": "#/parameters/Page" }, { "$ref": "#/parameters/PerPage" } ], "responses": { "200": { "description": "Paginated tasks" } } }, "post": { "tags": ["Content Intelligence"], "summary": "Create a Content Intelligence task", "operationId": "createIntelligenceTask", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "required": ["project_id", "task_type"], "properties": { "project_id": { "type": "integer" }, "task_type": { "type": "string", "enum": ["brief", "create", "update", "pr_insights", "custom"] }, "prompt_id": { "type": "integer" }, "custom_topic": { "type": "string" }, "user_instructions": { "type": "string" }, "output_language_code": { "type": "string" }, "existing_content": { "type": "string" }, "existing_content_url": { "type": "string" } } } } ], "responses": { "201": { "description": "Created" }, "422": { "$ref": "#/responses/UnprocessableEntity" } } } }, "/intelligence_tasks/{id}": { "get": { "tags": ["Content Intelligence"], "summary": "Get a Content Intelligence task", "operationId": "getIntelligenceTask", "parameters": [ { "$ref": "#/parameters/ProjectId" }, { "name": "id", "in": "path", "required": true, "type": "string", "description": "Numeric task ID or public_id string token" } ], "responses": { "200": { "description": "Task with result_data when completed" } } } }, "/mcp": { "post": { "tags": ["MCP"], "summary": "MCP JSON-RPC endpoint", "operationId": "handleMcpPost", "description": "Available on every plan, including Starter, Growth and the free trial. Accepts OAuth 2.1 access tokens (recommended for interactive AI clients — discovery at /.well-known/oauth-authorization-server, DCR at /oauth/register) and Bearer-token API keys (Scale plan or above, headless integrations).", "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": ["2.0"] }, "id": { "type": "string" }, "method": { "type": "string" }, "params": { "type": "object" } } } } ], "responses": { "200": { "description": "JSON-RPC response" } } }, "get": { "tags": ["MCP"], "summary": "MCP GET handshake", "operationId": "handleMcpGet", "responses": { "200": { "description": "JSON-RPC response" } } } } }, "responses": { "Unauthorized": { "description": "Authentication failed", "schema": { "$ref": "#/definitions/Error" } }, "NotFound": { "description": "Resource not found", "schema": { "$ref": "#/definitions/Error" } }, "Forbidden": { "description": "Access forbidden", "schema": { "$ref": "#/definitions/Error" } }, "PlanRequired": { "description": "Plan upgrade required", "schema": { "$ref": "#/definitions/Error" } }, "InsufficientScope": { "description": "API key lacks write permission", "schema": { "$ref": "#/definitions/Error" } }, "UnprocessableEntity": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/Error" } } }, "definitions": { "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_PLAN_REQUIRED", "ERR_PROJECT_NOT_FOUND", "ERR_NOT_FOUND", "ERR_INVALID_PARAM", "ERR_INVALID_RANGE", "ERR_LIMIT_REACHED", "ERR_QUOTA_EXCEEDED", "ERR_RATE_LIMITED"] }, "message": { "type": "string" }, "meta": { "type": "object" } } }, "request_id": { "type": "string" } } }, "Project": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "brand_name": { "type": "string", "description": "LLM-facing brand label, distinct from name." } } } } }