# Promptwatch API Documentation

## Docs

- [List action items](https://promptwatch.com/docs/api-reference/actions/list-action-items.md): Returns paginated action items for the project. Defaults to non-dismissed actions (page 1, size 50). Pass status=dismissed with an optional startDate to fetch dismissed actions.
- [Update action item status](https://promptwatch.com/docs/api-reference/actions/update-action-item-status.md): Updates an action item status (accept, dismiss, complete, etc.).
- [Brand Visibility Over Time](https://promptwatch.com/docs/api-reference/analytics/brand-visibility-over-time.md): Get brand visibility over time.
- [Crawler activity events](https://promptwatch.com/docs/api-reference/analytics/crawler-activity-events.md): List individual AI crawler HTTP requests (event log) for the project, with pagination and filters. Same data as the in-product crawler activity explorer.
- [Crawler Activity Trends](https://promptwatch.com/docs/api-reference/analytics/crawler-activity-trends.md): Get crawler activity trends over time. If the `crawlers` query parameter is omitted, the response includes all known AI crawler types that have data in the selected range (the server queries the full set of allowed crawler keys). Projects with no recorded crawler logs return empty dates and series.
- [Referrer Stats](https://promptwatch.com/docs/api-reference/analytics/referrer-stats.md): Get referrer comparison stats with period-over-period changes. Projects with no recorded visitor analytics return an empty data array.
- [Sentiment Time Series](https://promptwatch.com/docs/api-reference/analytics/sentiment-time-series.md): Get brand sentiment time series data
- [Top Browsers](https://promptwatch.com/docs/api-reference/analytics/top-browsers.md): Get top browsers by visitor count. Projects with no recorded visitor analytics return an empty data array.
- [Top Crawler Pages](https://promptwatch.com/docs/api-reference/analytics/top-crawler-pages.md): Get top pages requested by crawlers. Projects with no recorded crawler logs return an empty array.
- [Top Devices](https://promptwatch.com/docs/api-reference/analytics/top-devices.md): Get top devices by visitor count. Projects with no recorded visitor analytics return an empty data array.
- [Top Locations](https://promptwatch.com/docs/api-reference/analytics/top-locations.md): Get top geographic locations by visitor count. Projects with no recorded visitor analytics return an empty data array.
- [Top Pages](https://promptwatch.com/docs/api-reference/analytics/top-pages.md): Get top pages by visitor count. Projects with no recorded visitor analytics return an empty data array.
- [Top Sources](https://promptwatch.com/docs/api-reference/analytics/top-sources.md): Get top referrer sources by visitor count. Projects with no recorded visitor analytics return an empty data array.
- [Total Visits](https://promptwatch.com/docs/api-reference/analytics/total-visits.md): Get total visitor counts over time. Projects with no recorded visitor analytics return an empty array.
- [Visitor Trends](https://promptwatch.com/docs/api-reference/analytics/visitor-trends.md): Get visitor trends grouped by referrer. Projects with no recorded visitor analytics return empty dates and series.
- [Validate API Key](https://promptwatch.com/docs/api-reference/authentication/validate-api-key.md): Validate an API key and get associated project/organization details. For organization-level keys, optionally provide X-Project-Id header to validate access to a specific project.
- [Create Brand](https://promptwatch.com/docs/api-reference/brands/create-brand.md): Create or connect a brand to the project.
- [List Brands](https://promptwatch.com/docs/api-reference/brands/list-brands.md): Get all brands for the project.
- [Update Brand](https://promptwatch.com/docs/api-reference/brands/update-brand.md): Update brand relationship.
- [Citation Analytics](https://promptwatch.com/docs/api-reference/citations/citation-analytics.md): Get citation analytics including top cited domains, URLs, and authority metrics
- [Citation Rank Analysis](https://promptwatch.com/docs/api-reference/citations/citation-rank-analysis.md): Get citation rank analysis for your domain over time
- [Domain Citations Over Time](https://promptwatch.com/docs/api-reference/citations/domain-citations-over-time.md): Get domain citation frequency over time for top domains
- [Domains by LLM](https://promptwatch.com/docs/api-reference/citations/domains-by-llm.md): Get domain citations grouped by LLM source
- [Grouped Citations](https://promptwatch.com/docs/api-reference/citations/grouped-citations.md): Get a paginated, sortable table of cited URLs with per-URL citation count, average/best/worst position, domain rank (DR), authority, and the models citing each page. Mirrors the citations dashboard table.
- [LLM Sources](https://promptwatch.com/docs/api-reference/citations/llm-sources.md): Get top LLM sources with citation statistics
- [Self-Citation Frequency](https://promptwatch.com/docs/api-reference/citations/self-citation-frequency.md): Get self-citation frequency over time (citations pointing to your own domain)
- [Top Cited Pages](https://promptwatch.com/docs/api-reference/citations/top-cited-pages.md): Get top cited pages with average rank
- [Content Gap Stats](https://promptwatch.com/docs/api-reference/content-gap/content-gap-stats.md): Get aggregate content coverage statistics for the project
- [Content Recommendations](https://promptwatch.com/docs/api-reference/content-gap/content-recommendations.md): Get content recommendations from the latest content gap analysis for a prompt
- [Latest Content Coverage](https://promptwatch.com/docs/api-reference/content-gap/latest-content-coverage.md): Get the latest content coverage result for a prompt. Returns null if the prompt exists but has no content coverage yet.
- [List Content Gap Prompts](https://promptwatch.com/docs/api-reference/content-gap/list-content-gap-prompts.md): Get paginated list of prompts with content gap scores
- [Create content](https://promptwatch.com/docs/api-reference/content/create-content.md): Starts AI content generation (CREATE or OPTIMIZE). Returns the new document id with status PENDING; use GET /content/:id to poll for status, fields, and body.
- [Get content by id](https://promptwatch.com/docs/api-reference/content/get-content-by-id.md): Returns one content document by id (status, body, and metadata). Use after POST /content/create to poll until generation finishes; see response field descriptions for partial vs final content.
- [List content](https://promptwatch.com/docs/api-reference/content/list-content.md): Lists content documents for the project with pagination. Response rows are summary fields only; use GET /content/:id for the full document.
- [List Models](https://promptwatch.com/docs/api-reference/models/list-models.md): List all available LLM models supported by Promptwatch
- [Create Monitor](https://promptwatch.com/docs/api-reference/monitors/create-monitor.md): Create a new monitor
- [Delete Monitor](https://promptwatch.com/docs/api-reference/monitors/delete-monitor.md): Soft-delete a monitor
- [Get Monitor](https://promptwatch.com/docs/api-reference/monitors/get-monitor.md): Get a single monitor by ID with full details
- [List Monitors](https://promptwatch.com/docs/api-reference/monitors/list-monitors.md): Get all active monitors for the current project with average visibility and response counts in a date range
- [Update Monitor](https://promptwatch.com/docs/api-reference/monitors/update-monitor.md): Update an existing monitor
- [Add Tracked Pages](https://promptwatch.com/docs/api-reference/page-tracker/add-tracked-pages.md): Track one or more URLs. Returns a structured result with added, skipped (already tracked), and failed (invalid URL) arrays. Responds 207 Multi-Status to reflect mixed per-URL outcomes.
- [Delete Tracked Page](https://promptwatch.com/docs/api-reference/page-tracker/delete-tracked-page.md): Stop tracking a page by tracked page id
- [Get Tracked Page](https://promptwatch.com/docs/api-reference/page-tracker/get-tracked-page.md): Get a tracked page with citation stats for a date range. Date range uses inclusive UTC calendar days. When both startDate and endDate are omitted, the default range is today only (00:00:00.000Z through 23:59:59.999Z on the current UTC date). When only one bound is omitted, the missing bound defaults…
- [List Tracked Page Prompts](https://promptwatch.com/docs/api-reference/page-tracker/list-tracked-page-prompts.md): Paginated prompts whose responses cited this tracked page. Date range uses inclusive UTC calendar days. When both startDate and endDate are omitted, the default range is today only (00:00:00.000Z through 23:59:59.999Z on the current UTC date). When only one bound is omitted, the missing bound defaul…
- [List Tracked Page Responses](https://promptwatch.com/docs/api-reference/page-tracker/list-tracked-page-responses.md): Paginated responses that cited this tracked page. Date range uses inclusive UTC calendar days. When both startDate and endDate are omitted, the default range is today only (00:00:00.000Z through 23:59:59.999Z on the current UTC date). When only one bound is omitted, the missing bound defaults to tod…
- [List Tracked Pages](https://promptwatch.com/docs/api-reference/page-tracker/list-tracked-pages.md): List tracked pages for the project with optional URL search and citation stats. Date range uses inclusive UTC calendar days. When both startDate and endDate are omitted, the default range is today only (00:00:00.000Z through 23:59:59.999Z on the current UTC date). When only one bound is omitted, the…
- [Create Persona](https://promptwatch.com/docs/api-reference/personas/create-persona.md): Create a new persona for the project
- [Delete Persona](https://promptwatch.com/docs/api-reference/personas/delete-persona.md): Delete a persona
- [Get Persona](https://promptwatch.com/docs/api-reference/personas/get-persona.md): Get a specific persona by ID
- [List Personas](https://promptwatch.com/docs/api-reference/personas/list-personas.md): Get all personas for the project
- [Update Persona](https://promptwatch.com/docs/api-reference/personas/update-persona.md): Update an existing persona
- [Create Project](https://promptwatch.com/docs/api-reference/projects/create-project.md): Create a new project (requires org-level API key, X-Project-Id header NOT required)
- [List Projects](https://promptwatch.com/docs/api-reference/projects/list-projects.md): Get all projects for the organization (requires org-level API key, X-Project-Id header NOT required)
- [Activate Prompts](https://promptwatch.com/docs/api-reference/prompts/activate-prompts.md): Activate multiple prompts
- [Attach Tags to Prompt](https://promptwatch.com/docs/api-reference/prompts/attach-tags-to-prompt.md): Attach tags to a prompt (creates tags if they don't exist)
- [Attach Topics to Prompt](https://promptwatch.com/docs/api-reference/prompts/attach-topics-to-prompt.md): Attach topics to a prompt (creates topics if they don't exist)
- [Bulk Attach Tags](https://promptwatch.com/docs/api-reference/prompts/bulk-attach-tags.md): Attach tags to multiple prompts (creates tags if they don't exist)
- [Bulk Attach Topics](https://promptwatch.com/docs/api-reference/prompts/bulk-attach-topics.md): Attach topics to multiple prompts (creates topics if they don't exist)
- [Bulk Create Prompts](https://promptwatch.com/docs/api-reference/prompts/bulk-create-prompts.md): Create multiple prompts in a single request (max 100)
- [Bulk Delete Prompts](https://promptwatch.com/docs/api-reference/prompts/bulk-delete-prompts.md): Soft-delete multiple prompts by IDs
- [Create Prompt](https://promptwatch.com/docs/api-reference/prompts/create-prompt.md): Create a new prompt
- [Deactivate Prompts](https://promptwatch.com/docs/api-reference/prompts/deactivate-prompts.md): Deactivate multiple prompts
- [Delete Prompt](https://promptwatch.com/docs/api-reference/prompts/delete-prompt.md): Soft-delete a prompt by ID
- [Get Prompt](https://promptwatch.com/docs/api-reference/prompts/get-prompt.md): Get a single prompt by ID
- [List Prompts](https://promptwatch.com/docs/api-reference/prompts/list-prompts.md): Get paginated list of prompts with search and filtering options
- [Update Prompt](https://promptwatch.com/docs/api-reference/prompts/update-prompt.md): Update a prompt's type and intent
- [Clear Content Publication](https://promptwatch.com/docs/api-reference/publishing/clear-content-publication.md): Unlink a document from its published URL. The page tracker entry and its citation history are kept, so tracking continues for the URL.
- [Get Content Publish Status](https://promptwatch.com/docs/api-reference/publishing/get-content-publish-status.md): Get the latest CMS publish record for a document plus its full push history. Returns latest: null when the document has never been pushed to a CMS.
- [List CMS Connections](https://promptwatch.com/docs/api-reference/publishing/list-cms-connections.md): List the project's Webflow and Framer connections, including whether each is usable for publishing. Use the returned id as connectionId when pushing drafts or publishing live. Connections are created in the dashboard.
- [Publish Content Live](https://promptwatch.com/docs/api-reference/publishing/publish-content-live.md): Publish a previously staged CMS item to the live site and link the resulting URL to the page tracker. Requires a staged draft on the same connection. This makes content publicly visible and cannot be undone through this API.
- [Push Content Draft To CMS](https://promptwatch.com/docs/api-reference/publishing/push-content-draft-to-cms.md): Write the document to the connected CMS as an unpublished draft, creating the item or updating the existing one. Nothing goes live until you call the publish endpoint. Calls the CMS provider synchronously.
- [Set Content Publication](https://promptwatch.com/docs/api-reference/publishing/set-content-publication.md): Record the live URL for a completed document and start tracking that URL in the page tracker. Use this for pages published outside a connected CMS. The document must be COMPLETED.
- [List Query Fanouts](https://promptwatch.com/docs/api-reference/query-fanouts/list-query-fanouts.md): Get paginated list of prompts with query fanouts extracted from AI responses
- [Get Response](https://promptwatch.com/docs/api-reference/responses/get-response.md): Get a single response by ID with full citations
- [List Responses](https://promptwatch.com/docs/api-reference/responses/list-responses.md): Get paginated list of responses with filtering options
- [Mentions Time Series](https://promptwatch.com/docs/api-reference/responses/mentions-time-series.md): Get brand and competitor mentions over time
- [Response Summary](https://promptwatch.com/docs/api-reference/responses/response-summary.md): Get response summary including total responses and brand mentions
- [Sentiment Distribution](https://promptwatch.com/docs/api-reference/responses/sentiment-distribution.md): Get sentiment distribution of LLM responses
- [Sentiment Over Time](https://promptwatch.com/docs/api-reference/responses/sentiment-over-time.md): Get sentiment changes over time for brand mentions
- [Top Competitors](https://promptwatch.com/docs/api-reference/responses/top-competitors.md): Get top competitor mentions from LLM responses
- [Site Health Pages](https://promptwatch.com/docs/api-reference/site-health/site-health-pages.md): Pages with SEO issues (missing title/description, H1 problems, thin content). Omit issueTypes to return all issue types.
- [List Sitemap URLs](https://promptwatch.com/docs/api-reference/sitemap/list-sitemap-urls.md): Paginated list of sitemap URLs for the project. Optionally use filter to narrow to errored (failed/blocked), redirected, or in-progress URLs.
- [Sitemap Crawl Progress](https://promptwatch.com/docs/api-reference/sitemap/sitemap-crawl-progress.md): Get sitemap crawl progress with counts and percentage
- [List Reddit Citations](https://promptwatch.com/docs/api-reference/socials/list-reddit-citations.md): Get a paginated list of Reddit posts cited in LLM responses, with sorting and filtering. Mirrors the Reddit table on the Socials dashboard.
- [List YouTube Citations](https://promptwatch.com/docs/api-reference/socials/list-youtube-citations.md): Get a paginated list of YouTube videos cited in LLM responses, with sorting and filtering. Mirrors the YouTube table on the Socials dashboard.
- [Create Tags](https://promptwatch.com/docs/api-reference/tags/create-tags.md): Create one or more tags for the project
- [Delete Tag](https://promptwatch.com/docs/api-reference/tags/delete-tag.md): Delete a tag and remove it from all prompts
- [List Tags](https://promptwatch.com/docs/api-reference/tags/list-tags.md): Get all tags for the project with prompt counts
- [Rename Tag](https://promptwatch.com/docs/api-reference/tags/rename-tag.md): Rename an existing tag
- [Create Topics](https://promptwatch.com/docs/api-reference/topics/create-topics.md): Create one or more topics for the project
- [Delete Topic](https://promptwatch.com/docs/api-reference/topics/delete-topic.md): Delete a topic and remove it from all prompts
- [List Topics](https://promptwatch.com/docs/api-reference/topics/list-topics.md): Get all topics for the project with prompt counts
- [Rename Topic](https://promptwatch.com/docs/api-reference/topics/rename-topic.md): Rename an existing topic
- [Competitor Visibility Heatmap](https://promptwatch.com/docs/api-reference/visibility/competitor-visibility-heatmap.md): Get competitor visibility heatmap data showing visibility percentages across different models and competitors. Returns a structured matrix ready for heatmap visualization. Use YYYY-MM-DD for startDate and endDate (full calendar days in UTC). Visibility percentages are rounded to 2 decimal places in…
- [Prompt Visibility Time Series](https://promptwatch.com/docs/api-reference/visibility/prompt-visibility-time-series.md): Get per-prompt visibility time series data (the chart lines for each prompt)
- [Visibility Time Series](https://promptwatch.com/docs/api-reference/visibility/visibility-time-series.md): Get brand visibility time series data
- [Akamai](https://promptwatch.com/docs/crawler-logs/akamai.md): Configure crawler log ingestion via Akamai DataStream 2
- [API Responses](https://promptwatch.com/docs/crawler-logs/api-responses.md): HTTP status codes and event outcome details returned by Promptwatch log ingestion endpoints
- [Cloudflare Logpush](https://promptwatch.com/docs/crawler-logs/cloudflare-logpush.md): Configure crawler log ingestion via Cloudflare Logpush (Enterprise)
- [Cloudflare Workers](https://promptwatch.com/docs/crawler-logs/cloudflare-workers.md): Deploy a Cloudflare Worker to stream crawler logs
- [AWS CloudFront](https://promptwatch.com/docs/crawler-logs/cloudfront.md): Configure crawler log ingestion via Amazon Kinesis Firehose and CloudFront Logging v2
- [Fastly](https://promptwatch.com/docs/crawler-logs/fastly.md): Configure crawler log ingestion via Fastly HTTPS logging
- [Google Cloud CDN](https://promptwatch.com/docs/crawler-logs/gcp.md): Configure crawler log ingestion via GCP Pub/Sub and Log Router
- [Getting Started](https://promptwatch.com/docs/crawler-logs/getting-started.md): What crawler logs are and how they enable the Promptwatch platform
- [Manual Setup](https://promptwatch.com/docs/crawler-logs/manual.md): Send crawler logs via HTTP POST
- [Netlify](https://promptwatch.com/docs/crawler-logs/netlify.md): Configure crawler log ingestion via Netlify Log Drains (Enterprise)
- [Shopify + Cloudflare](https://promptwatch.com/docs/crawler-logs/shopify-cloudflare.md): Deploy a Cloudflare Worker for Shopify stores
- [Vercel](https://promptwatch.com/docs/crawler-logs/vercel.md): Configure crawler log ingestion via Vercel Log Drains
- [Webflow + Cloudflare](https://promptwatch.com/docs/crawler-logs/webflow-cloudflare.md): Deploy a Cloudflare Worker for Webflow sites
- [WP Engine + Cloudflare](https://promptwatch.com/docs/crawler-logs/wp-engine-cloudflare.md): Deploy a Cloudflare Worker for WP Engine sites
- [Getting Started](https://promptwatch.com/docs/getting-started.md): Learn how to authenticate and make your first API request
- [Introduction](https://promptwatch.com/docs/introduction.md)
- [Introduction](https://promptwatch.com/docs/mcp/introduction.md): Connect AI assistants directly to your Promptwatch data with the Model Context Protocol
- [Recipes](https://promptwatch.com/docs/mcp/recipes.md): Practical workflows you can run with the Promptwatch MCP — from weekly reports to content creation
- [Setup](https://promptwatch.com/docs/mcp/setup.md): Connect your MCP client to Promptwatch using OAuth or an API key
- [Agent Skills](https://promptwatch.com/docs/mcp/skills.md): Pre-built GEO workflows for Claude Code, Cursor, Codex, and other AI agents
- [Tools](https://promptwatch.com/docs/mcp/tools.md): Every tool exposed by the Promptwatch MCP server, grouped by what it does
- [Rate Limits](https://promptwatch.com/docs/rate-limits.md): Understanding API rate limits and best practices
- [Changelog](https://promptwatch.com/docs/v2/changelog.md): API v2 version history and updates

## OpenAPI Specs

- [openapi](https://promptwatch.com/docs/v2/openapi.json)
- [openapi-v2](https://promptwatch.com/docs/v2/openapi-v2.json)
- [openapi-v1](https://promptwatch.com/docs/openapi-v1.json)