{ "info": { "name": "LLMPulse API v1", "_postman_id": "f52adfc8-6809-45c0-895b-dda717946249", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": "Every LLM Pulse API v1 endpoint, grouped by resource in the same order as https://llmpulse.ai/api-docs. Generated from openapi.json by `rake api_docs:postman`. Set the api_key and project_id collection variables, then run any request. Optional query params ship disabled: tick the ones you need." }, "variable": [ { "key": "base_url", "value": "https://api.llmpulse.ai/api/v1" }, { "key": "api_key", "value": "" }, { "key": "project_id", "value": "" }, { "key": "competitors", "value": "" }, { "key": "page", "value": "1" }, { "key": "per_page", "value": "20" }, { "key": "range", "value": "30" }, { "key": "metrics_all", "value": "mentions,citations,responses,visibility,citation_rate,avg_position,ai_visibility_score,sentiment_very_positive,sentiment_positive,sentiment_neutral,sentiment_negative,sentiment_very_negative,net_sentiment" }, { "key": "event_type", "value": "mention.created" }, { "key": "annotation_id", "value": "" }, { "key": "answer_id", "value": "" }, { "key": "collection_id", "value": "" }, { "key": "competitor_id", "value": "" }, { "key": "intelligence_task_id", "value": "" }, { "key": "project_draft_id", "value": "" }, { "key": "prompt_id", "value": "" }, { "key": "recommendation_id", "value": "" }, { "key": "url_sha256", "value": "" }, { "key": "webhook_id", "value": "" } ], "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_key}}", "type": "string" } ] }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('Status is 200 or 304', function () {", " pm.expect(pm.response.code === 200 || pm.response.code === 304).to.be.true;", "});" ] } } ], "item": [ { "name": "Health", "item": [ { "name": "Health check", "request": { "method": "GET", "url": { "raw": "{{base_url}}/ping", "host": [ "{{base_url}}" ], "path": [ "ping" ], "query": [ { "key": "project_id", "value": "{{project_id}}", "disabled": true } ] }, "description": "Validates the API key and optionally pings a project. Returns the authenticated user_id, project (if project_id is supplied), and a request_id." } } ] }, { "name": "Projects", "item": [ { "name": "List projects", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/projects", "host": [ "{{base_url}}" ], "path": [ "dimensions", "projects" ], "query": [ { "key": "output", "value": "", "disabled": true } ] }, "description": "All projects accessible with your API key." } }, { "name": "Project details", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/projects/{{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "projects", "{{project_id}}" ] }, "description": "Detailed info for one project: matching_names, industry, business model, primary products, target audience, brand voice, locale, app store IDs, stats (incl. prompts_by_brand_kind counts) and data_coverage (models, countries and languages with data)." } }, { "name": "List models with data", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/models?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "models" ], "query": [ { "key": "project_id", "value": "{{project_id}}" } ] } } }, { "name": "List locales with data", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/locales?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "locales" ], "query": [ { "key": "project_id", "value": "{{project_id}}" } ] } } }, { "name": "Start a project draft (wizard step 1)", "request": { "method": "POST", "url": { "raw": "{{base_url}}/project_drafts", "host": [ "{{base_url}}" ], "path": [ "project_drafts" ] }, "description": "Start the multi-step project-creation wizard. Returns a draft_id plus AI suggestions (name, description, industry, brand aliases) for the URL. Cold URLs can take up to ~2 minutes to analyze; pass suggest=false to skip AI and respond instantly. Drafts expire after 24h. Requires a `read_write` scope API key.", "body": { "mode": "raw", "raw": "{\n \"website_url\": \"\",\n \"main_country\": \"\",\n \"main_language\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "Read a project draft", "request": { "method": "GET", "url": { "raw": "{{base_url}}/project_drafts/{{project_draft_id}}", "host": [ "{{base_url}}" ], "path": [ "project_drafts", "{{project_draft_id}}" ], "query": [ { "key": "include_suggestions", "value": "false", "disabled": true } ] } } }, { "name": "Submit a wizard step", "request": { "method": "PATCH", "url": { "raw": "{{base_url}}/project_drafts/{{project_draft_id}}", "host": [ "{{base_url}}" ], "path": [ "project_drafts", "{{project_draft_id}}" ] }, "description": "Submit one step (details, prompts, competitors, owned_media). Strict forward gating: a step is only accepted when every previous step is complete (`ERR_DRAFT_STATE` otherwise); completed steps can be resubmitted. Responds with the updated draft plus AI suggestions for the next step.", "body": { "mode": "raw", "raw": "{\n \"step\": \"details\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "Finalize a draft into a real project", "request": { "method": "POST", "url": { "raw": "{{base_url}}/project_drafts/{{project_draft_id}}/finalize", "host": [ "{{base_url}}" ], "path": [ "project_drafts", "{{project_draft_id}}", "finalize" ] }, "description": "Creates the project with all accumulated draft data (same effects as POST /projects). Idempotent: finalizing an already-finalized draft returns 200 with the existing project. Optional overrides: weekly_email_subscribed, execute_prompts_immediately.", "body": { "mode": "raw", "raw": "{\n \"weekly_email_subscribed\": false,\n \"execute_prompts_immediately\": false\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "Create a project (fast mode)", "request": { "method": "POST", "url": { "raw": "{{base_url}}/projects", "host": [ "{{base_url}}" ], "path": [ "projects" ] }, "description": "Create a complete project in one call: project fields, prompts (queued for execution and categorization), competitors, weekly email subscription. Idempotent via `external_identifier` (embed-enabled accounts only; replay returns 200 with the existing project). Requires a `read_write` scope API key.", "body": { "mode": "raw", "raw": "{\n \"website_url\": \"https://acme.com\",\n \"name\": \"Acme\",\n \"main_country\": \"US\",\n \"main_language\": \"en\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } } ] }, { "name": "Metrics", "item": [ { "name": "Time-series metrics", "request": { "method": "GET", "url": { "raw": "{{base_url}}/metrics/timeseries?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "metrics", "timeseries" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "metrics", "value": "{{metrics_all}}", "disabled": true }, { "key": "granularity", "value": "", "disabled": true }, { "key": "range", "value": "{{range}}", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "competitors", "value": "", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "prompt_type", "value": "", "disabled": true }, { "key": "brand_kind", "value": "", "disabled": true }, { "key": "include_project", "value": "true", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] }, "description": "Returns time-series data for one or more metrics, broken down by actor (project + competitors). Supports day/week/month granularity, with sticky carry-forward semantics for week/month aggregates." } }, { "name": "Aggregated metrics summary", "request": { "method": "GET", "url": { "raw": "{{base_url}}/metrics/summary?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "metrics", "summary" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "metrics", "value": "{{metrics_all}}", "disabled": true }, { "key": "granularity", "value": "", "disabled": true }, { "key": "range", "value": "{{range}}", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "competitors", "value": "", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "prompt_type", "value": "", "disabled": true }, { "key": "brand_kind", "value": "", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] }, "description": "Same as /metrics/timeseries but adds a `summary` block with total/min/max/last per metric per actor, plus a `position_distribution` block (Position 1, Position 2, Position 3+). Citations and citation rate include visible citations and background source references. Background references use position 0 and are excluded from avg_position and position distributions. `total` is a SUM for count metrics (mentions, citations, responses) and an AVERAGE across periods for rate/percentage and average metrics (visibility/mention_rate, citation_rate, ai_visibility_score, sentiment shares, avg_position, avg_mention_position, net_sentiment); rates are never summed. Each summary row carries an `aggregation` field (`sum` or `average`)." } }, { "name": "Per-prompt metrics summary", "request": { "method": "GET", "url": { "raw": "{{base_url}}/metrics/prompt_summary?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "metrics", "prompt_summary" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "range", "value": "{{range}}", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "breakdown", "value": "", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "prompt_type", "value": "", "disabled": true }, { "key": "brand_kind", "value": "", "disabled": true }, { "key": "sort", "value": "responses", "disabled": true }, { "key": "sort_dir", "value": "desc", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] }, "description": "Paginated per-prompt aggregated metrics. Returns responses, mentions, citations, mention_rate, citation_rate, avg_mention_position and avg_position per prompt. Citations and citation rate include visible citations and background source references; avg_position uses visible citations only. Pass `breakdown=model` to split each prompt by model." } }, { "name": "Share of Voice", "request": { "method": "GET", "url": { "raw": "{{base_url}}/metrics/sov?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "metrics", "sov" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "range", "value": "{{range}}", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "granularity", "value": "", "disabled": true }, { "key": "competitors", "value": "", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "prompt_type", "value": "", "disabled": true }, { "key": "brand_kind", "value": "", "disabled": true }, { "key": "output", "value": "", "disabled": true }, { "key": "view", "value": "over_time", "disabled": true } ] }, "description": "Share of Voice breakdown comparing your project to competitors. Returns over_time, current snapshot, and a Top-4 + Others breakdown." } }, { "name": "Top cited sources", "request": { "method": "GET", "url": { "raw": "{{base_url}}/metrics/top_sources?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "metrics", "top_sources" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "range", "value": "{{range}}", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "prompt_type", "value": "", "disabled": true }, { "key": "brand_kind", "value": "", "disabled": true }, { "key": "sort", "value": "total_responses", "disabled": true }, { "key": "query", "value": "", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] }, "description": "Registrable domains most frequently cited in AI responses for the project, including visible citations and background source references. This endpoint remains a domain rollup when exact-subdomain matching is enabled. Results can be sorted by total responses, average mention rate, or average visibility." } } ] }, { "name": "Competitors", "item": [ { "name": "List competitors", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/competitors?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "competitors" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "include_project_brand", "value": "false", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] } } }, { "name": "Competitor details", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/competitors/{{competitor_id}}?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "competitors", "{{competitor_id}}" ], "query": [ { "key": "project_id", "value": "{{project_id}}" } ] } } }, { "name": "Add a competitor", "request": { "method": "POST", "url": { "raw": "{{base_url}}/competitors", "host": [ "{{base_url}}" ], "path": [ "competitors" ] }, "description": "Adds a competitor (brand name + domain) to a project. Honours the per-plan max competitors cap. Requires a `read_write` scope API key.", "body": { "mode": "raw", "raw": "{\n \"project_id\": \"{{project_id}}\",\n \"brand_name\": \"\",\n \"domain\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "Update a competitor", "request": { "method": "PATCH", "url": { "raw": "{{base_url}}/competitors/{{competitor_id}}", "host": [ "{{base_url}}" ], "path": [ "competitors", "{{competitor_id}}" ] }, "description": "Updates brand_name, matching_names (full replacement list; the brand name is always included automatically) and/or color. The domain is immutable after creation. Name changes re-run mention/citation matching in the background: the competitor shows processing=true for a few minutes and further edits are rejected meanwhile. Requires a `read_write` scope API key.", "body": { "mode": "raw", "raw": "{\n \"project_id\": \"{{project_id}}\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "Delete a competitor", "request": { "method": "DELETE", "url": { "raw": "{{base_url}}/competitors/{{competitor_id}}?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "competitors", "{{competitor_id}}" ], "query": [ { "key": "project_id", "value": "{{project_id}}" } ] }, "description": "Deletes a competitor (irreversible). It disappears immediately and frees a competitor slot; its tracked data is purged by a background job. Requires a `read_write` scope API key." } } ] }, { "name": "Prompts", "item": [ { "name": "List prompts", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/prompts?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "prompts" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "prompt_type", "value": "", "disabled": true }, { "key": "brand_kind", "value": "", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] } } }, { "name": "List prompt executions", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/prompt_executions?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "prompt_executions" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "mention_filter", "value": "", "disabled": true }, { "key": "citation_filter", "value": "", "disabled": true }, { "key": "competitors", "value": "", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] } } }, { "name": "Bulk-create prompts", "request": { "method": "POST", "url": { "raw": "{{base_url}}/prompts", "host": [ "{{base_url}}" ], "path": [ "prompts" ] }, "description": "Add prompts to a project in bulk (up to 100 per request). Validates the account prompt quota and skips duplicates. Requires a `read_write` scope API key.", "body": { "mode": "raw", "raw": "{\n \"project_id\": \"{{project_id}}\",\n \"prompts\": [],\n \"country_code\": \"\",\n \"language_code\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "Delete a prompt", "request": { "method": "DELETE", "url": { "raw": "{{base_url}}/prompts/{{prompt_id}}?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "prompts", "{{prompt_id}}" ], "query": [ { "key": "project_id", "value": "{{project_id}}" } ] }, "description": "Deletes a prompt (irreversible). The prompt disappears immediately and frees a prompt slot; its historical data (executions, mentions, citations, sentiment) is purged by a background job. Requires a `read_write` scope API key." } } ] }, { "name": "Collections & Tags", "item": [ { "name": "List tags/collections", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/collections?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "collections" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "output", "value": "", "disabled": true } ] } } }, { "name": "List tags (alias for /collections)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/tags?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "tags" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "output", "value": "", "disabled": true } ] } } }, { "name": "Bulk-attach tags to prompts", "request": { "method": "POST", "url": { "raw": "{{base_url}}/prompts/assign_tags", "host": [ "{{base_url}}" ], "path": [ "prompts", "assign_tags" ] }, "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.", "body": { "mode": "raw", "raw": "{\n \"project_id\": \"{{project_id}}\",\n \"prompt_ids\": []\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "Create a tag", "request": { "method": "POST", "url": { "raw": "{{base_url}}/collections", "host": [ "{{base_url}}" ], "path": [ "collections" ] }, "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.", "body": { "mode": "raw", "raw": "{\n \"project_id\": \"{{project_id}}\",\n \"name\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "Update a tag", "request": { "method": "PATCH", "url": { "raw": "{{base_url}}/collections/{{collection_id}}", "host": [ "{{base_url}}" ], "path": [ "collections", "{{collection_id}}" ] }, "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.", "body": { "mode": "raw", "raw": "{\n \"project_id\": \"{{project_id}}\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "Delete a tag", "request": { "method": "DELETE", "url": { "raw": "{{base_url}}/collections/{{collection_id}}?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "collections", "{{collection_id}}" ], "query": [ { "key": "project_id", "value": "{{project_id}}" } ] }, "description": "Deletes a tag/collection. The prompts inside it are NOT deleted; only the grouping disappears. Requires a `read_write` scope API key." } } ] }, { "name": "Answers", "item": [ { "name": "List AI responses", "request": { "method": "GET", "url": { "raw": "{{base_url}}/answers?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "answers" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "mention_filter", "value": "", "disabled": true }, { "key": "citation_filter", "value": "", "disabled": true }, { "key": "competitors", "value": "", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "query", "value": "", "disabled": true } ] }, "description": "Successful prompt-execution responses with truncated content (max 10,000 chars). Pass `query` for case-insensitive full-text search inside response texts: `total` becomes the exact count of matching responses and each item returns `snippet` + `match_count` instead of `response`/`response_truncated`." } }, { "name": "Get one AI response", "request": { "method": "GET", "url": { "raw": "{{base_url}}/answers/{{answer_id}}?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "answers", "{{answer_id}}" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "include_source_page_details", "value": "false", "disabled": true } ] }, "description": "Full answer with mentions, citations, sentiments, sources, shopping_products, brand_entities, fan_out_queries. Pass `include_source_page_details=true` to nest page-cache metadata under each source." } } ] }, { "name": "Mentions & Citations", "item": [ { "name": "List brand mentions", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/mentions?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "mentions" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] } } }, { "name": "List brand citations", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/citations?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "citations" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] }, "description": "Includes visible citations and background source references. Background references use position 0, meaning no visible rank." } }, { "name": "List competitor mentions", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/competitor_mentions?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "competitor_mentions" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "competitors", "value": "", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] } } }, { "name": "List competitor citations", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/competitor_citations?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "competitor_citations" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "competitors", "value": "", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] }, "description": "Includes visible citations and background source references. Background references use position 0, meaning no visible rank." } }, { "name": "List all mentions (brand + competitor)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/all_mentions?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "all_mentions" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "competitors", "value": "", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] }, "description": "Unified mentions stream. Each record has an `actor_type` field (`project` or `competitor`) so the same payload covers both." } }, { "name": "List all citations (brand + competitor)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/all_citations?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "all_citations" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "competitors", "value": "", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] }, "description": "Unified citations stream with an `actor_type` field on each record. Includes visible citations and background source references; background references use position 0, meaning no visible rank." } } ] }, { "name": "Sentiments", "item": [ { "name": "List sentiment categories", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/sentiments?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "sentiments" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "output", "value": "", "disabled": true } ] }, "description": "Sentiment metric keys + labels + colors. For records, use /sentiments." } }, { "name": "List sentiment records", "request": { "method": "GET", "url": { "raw": "{{base_url}}/sentiments?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "sentiments" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "competitor_id", "value": "", "disabled": true }, { "key": "brand_only", "value": "", "disabled": true }, { "key": "analysis", "value": "", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true } ] } } } ] }, { "name": "Sources & Citation Intelligence", "item": [ { "name": "List source URLs", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/sources?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "sources" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "source_type", "value": "", "disabled": true }, { "key": "mention_filter", "value": "", "disabled": true }, { "key": "competitors", "value": "", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] } } }, { "name": "Grouped citation intelligence", "request": { "method": "GET", "url": { "raw": "{{base_url}}/citation_intelligence/groups?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "citation_intelligence", "groups" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "view", "value": "url", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "order", "value": "", "disabled": true }, { "key": "direction", "value": "", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "query", "value": "", "disabled": true }, { "key": "source_type", "value": "", "disabled": true }, { "key": "sentiment", "value": "", "disabled": true }, { "key": "content_gap", "value": "", "disabled": true } ] }, "description": "Grouped citation intelligence by url / domain / host with per-model breakdown, citation rate, and avg citation position. Counts and citation rate include visible citations and background source references. Average position ignores rows with position=0. Owned and competitor source matching honor the project's exact-subdomain setting. Filter vocabulary aligns with `source_type` returned by the API." } }, { "name": "Mention share by citing domain", "request": { "method": "GET", "url": { "raw": "{{base_url}}/citation_intelligence/mentions_by_domain?project_id={{project_id}}&domains=", "host": [ "{{base_url}}" ], "path": [ "citation_intelligence", "mentions_by_domain" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "domains", "value": "" }, { "key": "model", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "prompt", "value": "", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true } ] }, "description": "For the responses where each given source domain is cited, returns the share of those responses that mention the brand vs each competitor (brand + competitors sum to 100% per domain). Pass multiple domains to get the whole matrix in one call." } }, { "name": "Cited URL detail", "request": { "method": "GET", "url": { "raw": "{{base_url}}/citation_intelligence/urls/{{url_sha256}}?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "citation_intelligence", "urls", "{{url_sha256}}" ], "query": [ { "key": "project_id", "value": "{{project_id}}" } ] } } }, { "name": "Cited URL occurrences", "request": { "method": "GET", "url": { "raw": "{{base_url}}/citation_intelligence/urls/{{url_sha256}}/occurrences?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "citation_intelligence", "urls", "{{url_sha256}}", "occurrences" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true } ] } } }, { "name": "Cited URL cached content", "request": { "method": "GET", "url": { "raw": "{{base_url}}/citation_intelligence/urls/{{url_sha256}}/content?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "citation_intelligence", "urls", "{{url_sha256}}", "content" ], "query": [ { "key": "project_id", "value": "{{project_id}}" } ] } } } ] }, { "name": "AI Model Insights", "item": [ { "name": "AI Model Insights summary", "request": { "method": "GET", "url": { "raw": "{{base_url}}/reports/ai_model_insights/summary?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "reports", "ai_model_insights", "summary" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "range", "value": "{{range}}", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "granularity", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "prompt_type", "value": "", "disabled": true }, { "key": "brand_kind", "value": "", "disabled": true }, { "key": "competitors", "value": "", "disabled": true } ] }, "description": "Per-model mentions, citations, brand net sentiment with raw counts, weighted visibility totals/shares, plus actor matrices. All actor entries use the standard shape `{ type, id, competitor_id, name, domain }` with bare (scheme-less) domains." } }, { "name": "Position distribution comparison", "request": { "method": "GET", "url": { "raw": "{{base_url}}/reports/ai_model_insights/position_distribution?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "reports", "ai_model_insights", "position_distribution" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "range", "value": "{{range}}", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "granularity", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "prompt_type", "value": "", "disabled": true }, { "key": "brand_kind", "value": "", "disabled": true }, { "key": "model", "value": "", "disabled": true }, { "key": "brand1", "value": "", "disabled": true }, { "key": "brand2", "value": "", "disabled": true } ] } } }, { "name": "Google AI Overview result availability", "request": { "method": "GET", "url": { "raw": "{{base_url}}/reports/ai_model_insights/ai_overview_results?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "reports", "ai_model_insights", "ai_overview_results" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "range", "value": "{{range}}", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "granularity", "value": "", "disabled": true }, { "key": "collection_id", "value": "", "disabled": true }, { "key": "country_code", "value": "", "disabled": true }, { "key": "language_code", "value": "", "disabled": true }, { "key": "prompt_type", "value": "", "disabled": true }, { "key": "brand_kind", "value": "", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true } ] } } } ] }, { "name": "AI & Agent Traffic", "item": [ { "name": "AI bot crawler traffic (Scale+, Beta)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/metrics/agent_traffic?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "metrics", "agent_traffic" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "range", "value": "{{range}}", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "bot", "value": "", "disabled": true }, { "key": "company", "value": "", "disabled": true }, { "key": "group_by", "value": "bot", "disabled": true }, { "key": "granularity", "value": "", "disabled": true } ] }, "description": "Aggregated AI bot traffic hitting the project's origin server (GPTBot, PerplexityBot, ClaudeBot, OAI-SearchBot, Google-Extended, etc.). Sourced from Cloudflare or CSV uploads. Requires the Scale plan; lower tiers receive ERR_PLAN_REQUIRED." } }, { "name": "AI referral traffic (Scale+)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/metrics/ai_traffic?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "metrics", "ai_traffic" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "range", "value": "{{range}}", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "source", "value": "", "disabled": true }, { "key": "granularity", "value": "", "disabled": true } ] }, "description": "AI referral traffic for a project: human visits arriving from AI assistants (ChatGPT, Perplexity, Gemini, Claude, etc.), measured from the connected web analytics provider (Google Analytics 4, Adobe Analytics, PostHog, Plausible or Piano). Returns per-source users, sessions and conversions with totals and a conversion rate. Requires a connected provider and the Scale plan; otherwise returns ERR_AI_TRAFFIC_NOT_CONNECTED or ERR_PLAN_REQUIRED." } }, { "name": "AI bot catalog (Scale+)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/dimensions/agent_bots?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "dimensions", "agent_bots" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "output", "value": "", "disabled": true } ] }, "description": "Static catalog of AI bots that Agent Analytics can identify. Useful for rendering filter UIs that mirror our internal classification (slug, display name, company, category, Cloudflare verified-bot mapping, description). Requires the Scale plan; lower tiers receive ERR_PLAN_REQUIRED. The equivalent MCP tool list_agent_bots is available on all plans." } } ] }, { "name": "Search Console", "item": [ { "name": "Search Console summary (Growth+)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/search_console/summary?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "search_console", "summary" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "range", "value": "{{range}}", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "dimension", "value": "", "disabled": true } ] }, "description": "Google Search Console headline totals (impressions, clicks, ctr as a 0..1 fraction, average position) for the project over a date range. Pass dimension=country or dimension=device to also receive the breakdown aggregated over the range. Requires the project to have a connected Search Console property and the Growth plan or above; otherwise returns ERR_SEARCH_CONSOLE_NOT_CONNECTED or ERR_PLAN_REQUIRED." } }, { "name": "Search Console time series (Growth+)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/search_console/timeseries?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "search_console", "timeseries" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "range", "value": "{{range}}", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "granularity", "value": "", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] }, "description": "Google Search Console property-wide series (impressions, clicks, ctr, position) bucketed by day, week or month. Requires a connected Search Console property (Growth+)." } }, { "name": "Top Search Console queries (Growth+)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/search_console/queries?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "search_console", "queries" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "range", "value": "{{range}}", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "sort", "value": "impressions", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] }, "description": "Top Google Search Console search queries over a date range, ranked by impressions, clicks, ctr or position, paginated. Knowingly undercounts anonymized queries; for exact totals use /search_console/summary. Requires a connected Search Console property (Growth+)." } }, { "name": "Top Search Console pages (Growth+)", "request": { "method": "GET", "url": { "raw": "{{base_url}}/search_console/pages?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "search_console", "pages" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "range", "value": "{{range}}", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "sort", "value": "impressions", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true }, { "key": "output", "value": "", "disabled": true } ] }, "description": "Top Google Search Console landing pages over a date range, ranked by impressions, clicks, ctr or position, paginated. Requires a connected Search Console property (Growth+)." } } ] }, { "name": "Recommendations", "item": [ { "name": "List recommendation runs", "request": { "method": "GET", "url": { "raw": "{{base_url}}/recommendations?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "recommendations" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "recommendation_type", "value": "", "disabled": true }, { "key": "status", "value": "", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true } ] } } }, { "name": "Launch a recommendations generation", "request": { "method": "POST", "url": { "raw": "{{base_url}}/recommendations", "host": [ "{{base_url}}" ], "path": [ "recommendations" ] }, "description": "Launches a full-scope recommendations generation (async job, 1-3 minutes; poll GET /recommendations/{id} until status is completed). Consumes the project weekly recommendation-item budget: returns ERR_LIMIT_REACHED when it is exhausted or when a generation of the same type is already pending/processing. sentiment_reputation requires the Scale plan or above. Requires a `read_write` scope API key.", "body": { "mode": "raw", "raw": "{\n \"project_id\": \"{{project_id}}\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "Get recommendation run with items", "request": { "method": "GET", "url": { "raw": "{{base_url}}/recommendations/{{recommendation_id}}?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "recommendations", "{{recommendation_id}}" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "item_status", "value": "", "disabled": true }, { "key": "resolve_source_refs", "value": "true", "disabled": true } ] } } } ] }, { "name": "GEO Writer", "item": [ { "name": "List GEO Writer tasks", "request": { "method": "GET", "url": { "raw": "{{base_url}}/intelligence_tasks?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "intelligence_tasks" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "task_type", "value": "", "disabled": true }, { "key": "status", "value": "", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true } ] } } }, { "name": "Create a GEO Writer task", "request": { "method": "POST", "url": { "raw": "{{base_url}}/intelligence_tasks", "host": [ "{{base_url}}" ], "path": [ "intelligence_tasks" ] }, "body": { "mode": "raw", "raw": "{\n \"project_id\": \"{{project_id}}\",\n \"task_type\": \"brief\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "Get a GEO Writer task", "request": { "method": "GET", "url": { "raw": "{{base_url}}/intelligence_tasks/{{intelligence_task_id}}?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "intelligence_tasks", "{{intelligence_task_id}}" ], "query": [ { "key": "project_id", "value": "{{project_id}}" } ] } } } ] }, { "name": "Technical GEO Reports", "item": [ { "name": "Run technical GEO analysis", "request": { "method": "POST", "url": { "raw": "{{base_url}}/technical_geo_reports", "host": [ "{{base_url}}" ], "path": [ "technical_geo_reports" ] }, "description": "Launches the full technical GEO analysis bundle (crawlability, schema, content readiness, discoverability, site structure, robots.txt, agent readiness, llms.txt, AI visibility) for a URL + country. Each report runs in a background job. Requires a `read_write` scope API key.", "body": { "mode": "raw", "raw": "{\n \"project_id\": \"{{project_id}}\",\n \"url\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } } ] }, { "name": "Annotations", "item": [ { "name": "List timeline annotations", "request": { "method": "GET", "url": { "raw": "{{base_url}}/annotations?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "annotations" ], "query": [ { "key": "project_id", "value": "{{project_id}}" }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "annotation_category_id", "value": "", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true } ] }, "description": "Lists project timeline annotations, newest first. Rows can come from manual notes, project automations, GEO tests, or platform events. The origin field distinguishes them; editable says whether the requesting user may modify the row. Available on every plan." } }, { "name": "Create a timeline annotation", "request": { "method": "POST", "url": { "raw": "{{base_url}}/annotations", "host": [ "{{base_url}}" ], "path": [ "annotations" ] }, "description": "Marks a date in the project timeseries with a title + description. Available on every plan. Requires a `read_write` scope API key.", "body": { "mode": "raw", "raw": "{\n \"project_id\": \"{{project_id}}\",\n \"title\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "Update a timeline annotation", "request": { "method": "PATCH", "url": { "raw": "{{base_url}}/annotations/{{annotation_id}}", "host": [ "{{base_url}}" ], "path": [ "annotations", "{{annotation_id}}" ] }, "description": "Updates title, description, annotation_date, color and/or annotation_category_id. Only user-created annotations belonging to the requesting user can be updated (system annotations never). Available on every plan and requires a `read_write` scope API key.", "body": { "mode": "raw", "raw": "{\n \"project_id\": \"{{project_id}}\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "Delete a timeline annotation", "request": { "method": "DELETE", "url": { "raw": "{{base_url}}/annotations/{{annotation_id}}?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "annotations", "{{annotation_id}}" ], "query": [ { "key": "project_id", "value": "{{project_id}}" } ] }, "description": "Deletes an annotation. Same ownership rule as PATCH. Available on every plan and requires a `read_write` scope API key." } } ] }, { "name": "Webhooks", "item": [ { "name": "List webhook subscriptions", "request": { "method": "GET", "url": { "raw": "{{base_url}}/webhooks", "host": [ "{{base_url}}" ], "path": [ "webhooks" ], "query": [ { "key": "project_id", "value": "{{project_id}}", "disabled": true }, { "key": "page", "value": "{{page}}", "disabled": true }, { "key": "per_page", "value": "{{per_page}}", "disabled": true } ] }, "description": "Lists active webhook subscriptions for the account, optionally filtered by project. Requires the Scale plan or above." } }, { "name": "Create a webhook subscription", "request": { "method": "POST", "url": { "raw": "{{base_url}}/webhooks", "host": [ "{{base_url}}" ], "path": [ "webhooks" ] }, "description": "Subscribes a public HTTPS URL to a project event. LLM Pulse POSTs a JSON envelope (`event`, `occurred_at`, `project_id`, `subscription_id`, `data`) to the URL every time the event occurs, signed via the `X-LLMPulse-Signature` header (HMAC-SHA256 of the raw body computed with the subscription secret). Failed deliveries are retried 5 times with backoff; subscriptions auto-disable after 20 consecutive failed deliveries. Idempotent for the same project + event + URL. Requires a `read_write` scope API key and the Scale plan or above.", "body": { "mode": "raw", "raw": "{\n \"project_id\": \"{{project_id}}\",\n \"event_type\": \"mention.created\",\n \"target_url\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "Delete a webhook subscription", "request": { "method": "DELETE", "url": { "raw": "{{base_url}}/webhooks/{{webhook_id}}", "host": [ "{{base_url}}" ], "path": [ "webhooks", "{{webhook_id}}" ] }, "description": "Deletes a webhook subscription; the target URL stops receiving events immediately. Requires a `read_write` scope API key and the Scale plan or above." } }, { "name": "Sample event payloads", "request": { "method": "GET", "url": { "raw": "{{base_url}}/webhooks/sample/{{event_type}}?project_id={{project_id}}", "host": [ "{{base_url}}" ], "path": [ "webhooks", "sample", "{{event_type}}" ], "query": [ { "key": "project_id", "value": "{{project_id}}" } ] }, "description": "Returns up to 3 example event payloads for the event type, built from the project's most recent real data (or a static sample when the project has no data). Used by integration editors such as the Zapier sample loader. Requires the Scale plan or above." } } ] }, { "name": "MCP", "item": [ { "name": "MCP GET handshake", "request": { "method": "GET", "url": { "raw": "{{base_url}}/mcp", "host": [ "{{base_url}}" ], "path": [ "mcp" ] } } }, { "name": "Model Context Protocol endpoint", "request": { "method": "POST", "url": { "raw": "{{base_url}}/mcp", "host": [ "{{base_url}}" ], "path": [ "mcp" ] }, "description": "JSON-RPC 2.0 endpoint for AI clients using the Model Context Protocol. Available on every plan and during eligible trials. Two auth options are accepted: (1) **OAuth 2.1 access token** issued via `/oauth/token` (recommended: clients discover the flow at `/.well-known/oauth-authorization-server` and Dynamic Client Registration is supported at `/oauth/register`); (2) **API key** in the `Authorization: Bearer` header (requires Scale plan or above, suitable for headless integrations). The server filters `tools/list` per user plan; calls to gated tools return `ERR_PLAN_REQUIRED`.", "body": { "mode": "raw", "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": \"\",\n \"method\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "header": [ { "key": "Content-Type", "value": "application/json" } ] } }, { "name": "MCP server card", "request": { "method": "GET", "url": { "raw": "{{base_url}}/mcp/server-card", "host": [ "{{base_url}}" ], "path": [ "mcp", "server-card" ] }, "description": "Public MCP Server Card describing this server: name, version, the streamable HTTP endpoint, the protocol versions it speaks and the Authorization header a client must send. Requires no authentication, because it is the document a client reads before it holds a credential. The card contains no credential itself; the Authorization entry is a template marked isSecret. Advertised in the Agentic Resource Discovery catalog at /.well-known/ai-catalog.json, and deliberately NOT served at /.well-known/mcp/server-card.json, a location the MCP specification rules out because a single server's card is application-level rather than site-wide metadata." } } ] } ] }