{"openapi":"3.0.0","paths":{"/v1/health":{"get":{"description":"Check API availability and connectivity. Returns the current server timestamp.","operationId":"PublicHealthController_getHealth_v1","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfHealthResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/HealthResponse"}},"required":["item"]}}}}},"summary":"Check API health","tags":["Health"]}},"/v1/projects":{"get":{"description":"List all projects belonging to your organization. Returns project metadata and the most recent completed monitoring timestamp for each project.","operationId":"PublicProjectsController_listProjects_v1","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ListResponseOfProjectListItemResponse","type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ProjectListItemResponse"}}},"required":["items"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"List all projects","tags":["Projects"]}},"/v1/projects/{projectId}":{"get":{"description":"Get detailed information about a specific project, including per-dimension monitoring freshness and AI monitoring prompts.","operationId":"PublicProjectsController_getProject_v1","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfProjectDetailResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/ProjectDetailResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get project details","tags":["Projects"]}},"/v1/projects/{projectId}/competitors":{"get":{"description":"List all competitors monitored within a project. Includes the project's own domain (marked with `isOwn: true`) and all added competitor domains.","operationId":"PublicCompetitorsController_listCompetitors_v1","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ListResponseOfCompetitorListItemResponse","type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CompetitorListItemResponse"}}},"required":["items"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"List project competitors","tags":["Competitors"]}},"/v1/projects/{projectId}/competitors/{competitorId}":{"get":{"description":"Get detailed information about a specific competitor within a project, including monitored page URLs (homepage and pricing).","operationId":"PublicCompetitorsController_getCompetitor_v1","parameters":[{"name":"competitorId","required":true,"in":"path","description":"Competitor ID","schema":{"example":"507f1f77bcf86cd799439012","type":"string"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfCompetitorDetailResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/CompetitorDetailResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get competitor details","tags":["Competitors"]}},"/v1/projects/{projectId}/tech-trust":{"get":{"description":"Get the latest tech & trust profile data for all competitors in a project. Returns security headers, trust signals, technology stack, robots.txt analysis, and DNS infrastructure.","operationId":"PublicTechTrustController_getTechTrustDashboard_v1","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfTechTrustDashboardResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/TechTrustDashboardResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get latest tech & trust data","tags":["Tech & Trust Profile"]}},"/v1/projects/{projectId}/tech-trust/history":{"get":{"description":"Get paginated history of tech & trust monitoring runs for a project. Each entry includes run timing and summary statistics.","operationId":"PublicTechTrustController_getTechTrustHistory_v1","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"example":20,"type":"number"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"PaginatedResponseOfTechTrustHistoryItemResponse","type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TechTrustHistoryItemResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["items","pagination"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get tech & trust run history","tags":["Tech & Trust Profile"]}},"/v1/projects/{projectId}/tech-trust/history/{runId}":{"get":{"description":"Get full tech & trust data for a specific historical monitoring run, including per-competitor security headers, trust signals, technology stack, robots.txt, and DNS infrastructure.","operationId":"PublicTechTrustController_getTechTrustRunDetail_v1","parameters":[{"name":"runId","required":true,"in":"path","description":"Run ID","schema":{"example":"507f1f77bcf86cd799439012","type":"string"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfTechTrustRunDetailResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/TechTrustRunDetailResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get tech & trust data for a specific run","tags":["Tech & Trust Profile"]}},"/v1/projects/{projectId}/content":{"get":{"description":"Get the latest content intelligence data for all competitors in a project. Returns URL counts, content categorization, strategic URL analysis, and competitive gap assessment. Use this to understand the content landscape across competitors.","operationId":"PublicContentController_getContentDashboard_v1","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfContentDashboardResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/ContentDashboardResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get latest content intelligence data","tags":["Content Intelligence"]}},"/v1/projects/{projectId}/content/history":{"get":{"description":"Get paginated history of content intelligence monitoring runs for a project. Each entry includes run timing and summary statistics with gap analysis.","operationId":"PublicContentController_getContentHistory_v1","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"example":20,"type":"number"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"PaginatedResponseOfContentHistoryItemResponse","type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ContentHistoryItemResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["items","pagination"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get content intelligence run history","tags":["Content Intelligence"]}},"/v1/projects/{projectId}/content/history/{runId}":{"get":{"description":"Get full content intelligence data for a specific historical monitoring run, including per-competitor URL counts, content categorization, and strategic URL metrics.","operationId":"PublicContentController_getContentRunDetail_v1","parameters":[{"name":"runId","required":true,"in":"path","description":"Run ID","schema":{"example":"507f1f77bcf86cd799439012","type":"string"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfContentRunDetailResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/ContentRunDetailResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get content intelligence data for a specific run","tags":["Content Intelligence"]}},"/v1/projects/{projectId}/content/changelog":{"get":{"description":"Get paginated changelog of detected URL changes across competitor sitemaps. Each item shows numeric counts per category plus up to 3 sample URLs per category by default — safe for any token budget. Supports filtering by `competitorId` and `category` query parameters. Pass `allUrlsPerCategory=true` for the full URL list per category (warning: high-activity competitors can produce large responses; combine with filters to scope, and check the `truncated` flag in the response — when true, the byte cap fired and items/URLs were trimmed).","operationId":"PublicContentController_getContentChangelog_v1","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"example":20,"type":"number"}},{"name":"competitorId","required":false,"in":"query","description":"Filter by competitor ID","schema":{"example":"507f1f77bcf86cd799439011","type":"string"}},{"name":"category","required":false,"in":"query","description":"Filter by content category (blog, docs, tools, landing, legal, caseStudies, comparison, integrations, changelog, webinars, other)","schema":{"example":"blog","type":"string"}},{"name":"allUrlsPerCategory","required":false,"in":"query","description":"By default each item returns up to 3 sample URLs per category. Set true to return the full URL list per category. High-activity competitors can produce large responses — combine with `category` and `competitorId` filters to scope. Subject to an internal byte cap; check `truncated` in the response.","schema":{"example":false,"type":"boolean"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"PaginatedResponseOfContentChangelogItemResponse","type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ContentChangelogItemResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"},"truncated":{"type":"boolean","description":"True when the verbose-mode byte cap fired and items/URLs were trimmed to fit the response budget. Refine your query with category/competitorId filters when seen. Always false in default mode.","example":false}},"required":["items","pagination","truncated"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get content changelog","tags":["Content Intelligence"]}},"/v1/projects/{projectId}/positioning":{"get":{"description":"Get the latest positioning data for all competitors in a project. Returns homepage messaging, value propositions, CTAs, target audience, and competitive messaging analysis.","operationId":"PublicPositioningController_getPositioningDashboard_v1","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfPositioningDashboardResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/PositioningDashboardResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get latest positioning data","tags":["Positioning"]}},"/v1/projects/{projectId}/positioning/history":{"get":{"description":"Get paginated history of positioning monitoring runs for a project. Each entry includes run timing and summary statistics with messaging gap analysis.","operationId":"PublicPositioningController_getPositioningHistory_v1","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"example":20,"type":"number"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"PaginatedResponseOfPositioningHistoryItemResponse","type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PositioningHistoryItemResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["items","pagination"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get positioning run history","tags":["Positioning"]}},"/v1/projects/{projectId}/positioning/history/{runId}":{"get":{"description":"Get full positioning data for a specific historical monitoring run, including per-competitor homepage messaging, value propositions, CTAs, and audience data.","operationId":"PublicPositioningController_getPositioningRunDetail_v1","parameters":[{"name":"runId","required":true,"in":"path","description":"Run ID","schema":{"example":"507f1f77bcf86cd799439012","type":"string"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfPositioningRunDetailResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/PositioningRunDetailResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get positioning data for a specific run","tags":["Positioning"]}},"/v1/projects/{projectId}/pricing":{"get":{"description":"Get the latest pricing intelligence data for all competitors in a project. Returns structured pricing plans, free tier availability, billing options, enterprise pricing, promotions, and competitive gap analysis.","operationId":"PublicPricingController_getPricingDashboard_v1","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfPricingDashboardResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/PricingDashboardResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get latest pricing intelligence data","tags":["Pricing Intelligence"]}},"/v1/projects/{projectId}/pricing/history":{"get":{"description":"Get paginated history of pricing intelligence monitoring runs for a project. Each entry includes run timing and summary statistics with pricing gap analysis.","operationId":"PublicPricingController_getPricingHistory_v1","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"example":20,"type":"number"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"PaginatedResponseOfPricingHistoryItemResponse","type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PricingHistoryItemResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["items","pagination"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get pricing run history","tags":["Pricing Intelligence"]}},"/v1/projects/{projectId}/pricing/history/{runId}":{"get":{"description":"Get full pricing intelligence data for a specific historical monitoring run, including per-competitor pricing plans, billing options, free tiers, and enterprise pricing.","operationId":"PublicPricingController_getPricingRunDetail_v1","parameters":[{"name":"runId","required":true,"in":"path","description":"Run ID","schema":{"example":"507f1f77bcf86cd799439012","type":"string"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfPricingRunDetailResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/PricingRunDetailResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get pricing data for a specific run","tags":["Pricing Intelligence"]}},"/v1/projects/{projectId}/ai-visibility":{"get":{"description":"Get the latest AI visibility data for a project. Returns AI Visibility Scores, mention rates, and per-provider breakdowns for all competitors found across ChatGPT, Claude, and Gemini. Use this to understand how AI models perceive and recommend your brand vs competitors.","operationId":"PublicAiVisibilityController_getAiVisibilityDashboard_v1","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfAiVisibilityDashboardResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/AiVisibilityDashboardResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get latest AI visibility data","tags":["AI Visibility"]}},"/v1/projects/{projectId}/ai-visibility/history":{"get":{"description":"Get paginated history of AI visibility checks for a project. Each entry includes check timing and summary statistics with customer metrics, top competitor, and competitor rankings.","operationId":"PublicAiVisibilityController_getAiVisibilityHistory_v1","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"example":20,"type":"number"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"PaginatedResponseOfAiVisibilityHistoryItemResponse","type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AiVisibilityHistoryItemResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["items","pagination"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get AI visibility check history","tags":["AI Visibility"]}},"/v1/projects/{projectId}/ai-visibility/history/{checkId}":{"get":{"description":"Get full AI visibility data for a specific historical check, including per-competitor rankings across all three AI providers with mention rates and AI Visibility Scores.","operationId":"PublicAiVisibilityController_getAiVisibilityCheckDetail_v1","parameters":[{"name":"checkId","required":true,"in":"path","description":"Check ID","schema":{"example":"507f1f77bcf86cd799439012","type":"string"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfAiVisibilityCheckDetailResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/AiVisibilityCheckDetailResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get AI visibility data for a specific check","tags":["AI Visibility"]}},"/v1/projects/{projectId}/ai-visibility/trend":{"get":{"description":"Get AI visibility trend data over time for chart visualization. Returns time-series data points with customer and top competitor mention rates and AI Visibility Scores. Optionally filter by date range or specific AI provider — the provider filter applies to mention rates only; the AI Visibility Score is a single weighted composite across all providers, so customerAiScore/topCompetitorAiScore are null when a provider filter is applied. Returns up to 200 data points — use dateFrom/dateTo to narrow the range for longer histories.","operationId":"PublicAiVisibilityController_getAiVisibilityTrend_v1","parameters":[{"name":"dateFrom","required":false,"in":"query","description":"Start date for trend data (ISO-8601)","schema":{"example":"2026-01-01","type":"string"}},{"name":"dateTo","required":false,"in":"query","description":"End date for trend data (ISO-8601)","schema":{"example":"2026-03-15","type":"string"}},{"name":"provider","required":false,"in":"query","description":"Filter by AI provider. Omit to get aggregated trend across all providers.","schema":{"$ref":"#/components/schemas/AiProvider"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ListResponseOfAiVisibilityTrendDataPointResponse","type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AiVisibilityTrendDataPointResponse"}}},"required":["items"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get AI visibility trend data","tags":["AI Visibility"]}},"/v1/projects/{projectId}/alerts":{"get":{"description":"Get paginated competitive intelligence alerts for a project. Returns alerts generated when monitoring detects meaningful changes in competitor activity — such as pricing restructures, content strategy shifts, or technology stack changes. Supports filtering by monitoring dimension (tech-trust, content, positioning, pricing, ai-visibility), severity level (critical, high, medium, info), and specific competitor. Alerts are sorted by creation date (newest first).","operationId":"PublicAlertsController_listAlerts_v1","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"example":20,"type":"number"}},{"name":"dimension","required":false,"in":"query","description":"Filter by monitoring dimension (tech-trust, content, positioning, pricing, ai-visibility)","schema":{"example":"pricing","type":"string"}},{"name":"severity","required":false,"in":"query","description":"Filter by alert severity (critical, high, medium, info)","schema":{"example":"critical","type":"string"}},{"name":"competitorId","required":false,"in":"query","description":"Filter by competitor ID","schema":{"example":"507f1f77bcf86cd799439011","type":"string"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"PaginatedResponseOfAlertListItemResponse","type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AlertListItemResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["items","pagination"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"List project alerts","tags":["Alerts"]}},"/v1/projects/{projectId}/schedules":{"get":{"description":"Get monitoring schedules for all dimensions in a project. Returns the current configuration (enabled/disabled, interval) and timing (next run, last run) for each monitoring dimension. Use this to monitor scheduling health, detect stalled dimensions, or build alerting around missed runs.","operationId":"PublicSchedulesController_listSchedules_v1","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ListResponseOfScheduleItemResponse","type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ScheduleItemResponse"}}},"required":["items"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"List monitoring schedules","tags":["Schedules"]}},"/v1/projects/{projectId}/strategic-briefing":{"get":{"description":"Get the latest finished strategic briefing for a project — the synthesized, as-of competitive read (what changed, what it means, what to do). This is the ANALYZED briefing; for the raw monitoring data use the per-dimension dashboards (e.g. `/pricing`), and for the monitored-competitor roster use `/competitors`.\n\nOnly the most recent FINISHED edition is returned (never an in-progress one). `meta.availability` is the state to branch on: `ready` (a briefing is returned), `ready-refreshing` (a briefing is returned and a newer edition is being generated right now), `preparing` (the first edition is still being generated — `item` is null), or `none` (no briefing yet). A missing or non-accessible project returns 404 `project_not_found`; the briefing lifecycle itself never 404s.\n\n**Sections — lean by default.** `sections` selects what to return and defaults to `[\"hub\"]` — the executive digest AND the navigation map. Each hub `diagnosis` row carries a `deepDive` pointer naming the dimension to read next; prefix it with `deep-` to form the section value (a pointer of `ai-visibility` → request `sections=deep-ai-visibility`). Valid sections: `hub`, `actions`, `competitors`, the thirteen `deep-<dimension>` deep-dives, or `all` for the full document. Charts are off by default (`includeCharts=false` returns each chart's title + note only); pass `includeCharts=true` for the full data series.\n\n**Always returned, regardless of `sections`:** `coverage` (methodology and honest-degradation caveats for this edition — read these before quoting any figure) and `dimensionHealth` (per-dimension present/absent, so a skipped dimension is never read as an empty finding).\n\n**Reading the numbers:** the AI Visibility Score is 0–100 (higher is better); an AI `rank` is ordinal (lower is better); action `impact` is 1–4 (higher is more critical); action effort is bucketed as `effortMinutes` (`<30` | `30-120` | `>120`). Briefings refresh approximately every 30 days.","operationId":"PublicBriefingController_getStrategicBriefing_v1","parameters":[{"name":"sections","required":false,"in":"query","description":"Which sections to return. Defaults to [\"hub\"] — the executive digest and navigation map. Pass specific sections to go deeper (e.g. a hub diagnosis pointer of `ai-visibility` maps to `deep-ai-visibility`), or `all` for the full document. Prefer deriving deep-<dimension> values from the hub diagnosis pointers rather than requesting slots blind — `dimensionHealth` tells you which exist for this edition.","schema":{"example":["hub"],"type":"array","items":{"type":"string","enum":["hub","actions","competitors","deep-ai-visibility","deep-positioning","deep-pricing","deep-content","deep-tech-trust","deep-agent-readiness","deep-ai-ecosystem","deep-customer-voice","deep-funding-capital","deep-hiring-gtm","deep-landscape","deep-product-launches","deep-reliability-status","all"]}}},{"name":"includeCharts","required":false,"in":"query","description":"Include full chart series data. Defaults to false — charts return their title + note only (the heaviest part of a section is the chart series). Pass true for the full data series.","schema":{"default":false,"example":false,"type":"boolean"}},{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"507f1f77bcf86cd799439011"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefingEnvelopeResponse"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get the latest strategic briefing","tags":["Strategic Briefing"]}},"/v1/tools/tech-stack/scans":{"post":{"description":"Start an asynchronous tech-stack detection scan for a public domain. Detects the frontend frameworks, hosting and CDN infrastructure, CMS, analytics and growth tools, and customer engagement services in use. Returns sub-second with `item: { id, status: \"queued\", createdAt, expiresAt }` — poll `GET /v1/tools/tech-stack/scans/{scanId}` until `status` is `completed` or `failed`. Most scans complete in seconds; heavy-render sites can take up to ~90 seconds. Result and error payloads are persisted for 24h, after which the scan auto-deletes and GET returns 404. No project required. Suitable for ad-hoc competitive lookups, integration into onboarding flows, and pre-sales discovery — and the only supported shape for MCP clients (Cursor / Claude Desktop hardcode 60-second tool-call timeouts).","operationId":"PublicTechStackToolController_createScan_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PTTechStackRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfTechStackScanResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/TechStackScanResponse"}},"required":["item"]}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"502":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Start an async tech-stack scan","tags":["Tools"]}},"/v1/tools/tech-stack/scans/{scanId}":{"get":{"description":"Get the current state of an async tech-stack scan. Returns the scan's lifecycle (`queued` / `running` / `completed` / `failed`) along with `createdAt` and `expiresAt` always, plus `startedAt` once the runner picks it up and `completedAt` once it reaches a terminal state. On `completed` the full canonical scan response is in `item.result` (categorized technology hits with evidence). On `failed` the failure details are in `item.error` with a machine-readable `code` — currently `homepage_fetch_failed` (upstream homepage fetch threw) or `scan_failed` (any other error during scan execution). Scoped to the API key's organization — cross-tenant access, never-existed IDs, expired IDs (24h TTL), and malformed IDs all return 404 `scan_not_found` with an identical envelope to prevent existence-disclosure. Typically sub-second — safe to poll on a 2–5 second interval depending on your timeout budget.","operationId":"PublicTechStackToolController_getScan_v1","parameters":[{"name":"scanId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfTechStackScanResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/TechStackScanResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get an async tech-stack scan by ID","tags":["Tools"]}},"/v1/tools/trust-signals/scans":{"post":{"description":"Start an asynchronous trust-signal analysis for a public domain. Returns a tier verdict (comprehensive / substantial / moderate / minimal) with a 0-100 score and a per-category breakdown across five buyer-concern areas: enterprise readiness, third-party validation, social proof, brand authority, and risk reversal. Also surfaces suspicious patterns (e.g. unverified compliance claims, count-vs-logo mismatches, unlinked press mentions) and gaps versus tier benchmarks. Returns sub-second with `item: { id, status: \"queued\", createdAt, expiresAt }` — poll `GET /v1/tools/trust-signals/scans/{scanId}` until `status` is `completed` or `failed`. Most scans complete in seconds; heavy-render sites can take up to ~90 seconds. Result and error payloads are persisted for 24h, after which the scan auto-deletes and GET returns 404. No project required. Suitable for sales discovery, due-diligence flows, and competitive credibility audits — and the only supported shape for MCP clients (Cursor / Claude Desktop hardcode 60-second tool-call timeouts).","operationId":"PublicTrustSignalsToolController_createScan_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PTTrustSignalsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfTrustSignalsScanResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/TrustSignalsScanResponse"}},"required":["item"]}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"502":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Start an async trust-signals scan","tags":["Tools"]}},"/v1/tools/trust-signals/scans/{scanId}":{"get":{"description":"Get the current state of an async trust-signals scan. Returns the scan's lifecycle (`queued` / `running` / `completed` / `failed`) along with `createdAt` and `expiresAt` always, plus `startedAt` once the runner picks it up and `completedAt` once it reaches a terminal state. On `completed` the full canonical scan response is in `item.result` (tier verdict, category scores, detected signals with evidence, suspicious patterns, gaps). On `failed` the failure details are in `item.error` with a machine-readable `code` — currently `homepage_fetch_failed` (upstream homepage fetch threw) or `scan_failed` (any other error during scan execution). Scoped to the API key's organization — cross-tenant access, never-existed IDs, expired IDs (24h TTL), and malformed IDs all return 404 `scan_not_found` with an identical envelope to prevent existence-disclosure. Typically sub-second — safe to poll on a 2–5 second interval depending on your timeout budget.","operationId":"PublicTrustSignalsToolController_getScan_v1","parameters":[{"name":"scanId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfTrustSignalsScanResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/TrustSignalsScanResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get an async trust-signals scan by ID","tags":["Tools"]}},"/v1/tools/ai-crawler-checker":{"post":{"description":"Check which AI crawlers are allowed, disallowed, or unconfigured on any public domain. Inspects robots.txt for major AI bots (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, and more), checks meta tags and the presence of /llms.txt, and surfaces an accessibility verdict, opt-in/opt-out strategy detection, and how the domain compares to industry peers. Optionally tailor the analysis to a specific industry. Stateless live check — no project required, no data is persisted. Suitable for AI readiness audits, content-strategy reviews, and pre-launch compliance checks.","operationId":"PublicAiCrawlerCheckerToolController_detectAiCrawlers_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PTAiCrawlerCheckerRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfAiCrawlerCheckerToolResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/AiCrawlerCheckerToolResponse"}},"required":["item"]}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"502":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Check AI crawler accessibility for a domain","tags":["Tools"]}},"/v1/tools/sitemap-visualizer":{"post":{"description":"Discover and analyze the sitemap structure of any public domain. Locates sitemap.xml (or accepts an explicit URL), categorizes URLs by content type, validates structure, and surfaces freshness and depth-distribution insights with sample URLs per category. Optionally include the full URL list (off by default to keep payload bounded). Stateless live check — no project required, no data is persisted. Suitable for content-strategy audits, SEO discovery, and content-volume benchmarking.","operationId":"PublicSitemapVisualizerToolController_analyzeSitemap_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PTSitemapVisualizerRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfSitemapVisualizerToolResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/SitemapVisualizerToolResponse"}},"required":["item"]}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"502":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Analyze sitemap structure of a domain","tags":["Tools"]}},"/v1/tools/agent-adoption/scans":{"post":{"description":"Start an asynchronous AI agent-adoption scan for a public domain. Runs 25 checks across four categories — `discoverability` (robots.txt, sitemap.xml, Link headers), `accessControl` (AI bot rules, content signals, web-bot-auth, robots-allow-all), `contentReadability` (/llms.txt, markdown negotiation, rendering strategy, page size, redirects, agents.md, cache headers), and `agentEndpoints` (OpenAPI catalog, OAuth discovery, MCP server card, A2A agent card, agent skills). Returns sub-second with `item: { id, status: \"queued\", createdAt, expiresAt }` — poll `GET /v1/tools/agent-adoption/scans/{scanId}` until `status` is `completed` or `failed`. Most scans complete in 35–60 seconds; slow or JS-heavy domains can take up to ~3 minutes. Result and error payloads are persisted for 24h, after which the scan auto-deletes and GET returns 404. No project required. Suitable for AI-adoption audits, agent-adoption maturity assessments, and pre-launch agentic-commerce reviews — and the only supported shape for MCP clients (Cursor / Claude Desktop hardcode 60-second tool-call timeouts).","operationId":"PublicAgentAdoptionToolController_createScan_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PTAgentAdoptionRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfAgentAdoptionScanResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/AgentAdoptionScanResponse"}},"required":["item"]}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"502":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Start an async agent-adoption scan","tags":["Tools"]}},"/v1/tools/agent-adoption/scans/{scanId}":{"get":{"description":"Get the current state of an async agent-adoption scan. Returns the scan's lifecycle (`queued` / `running` / `completed` / `failed`) along with `createdAt` and `expiresAt` always, plus `startedAt` once the runner picks it up and `completedAt` once it reaches a terminal state. On `completed` the full canonical scan response is in `item.result` (same shape the legacy sync `/v1/tools/agent-adoption` returned). On `failed` the failure details are in `item.error` with a machine-readable `code` — currently `homepage_fetch_failed` (upstream homepage fetch threw) or `scan_failed` (any other error during scan execution). Scoped to the API key's organization — cross-tenant access, never-existed IDs, expired IDs (24h TTL), and malformed IDs all return 404 `scan_not_found` with an identical envelope to prevent existence-disclosure. Typically sub-second — safe to poll on a 2–5 second interval depending on your timeout budget.","operationId":"PublicAgentAdoptionToolController_getScan_v1","parameters":[{"name":"scanId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfAgentAdoptionScanResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/AgentAdoptionScanResponse"}},"required":["item"]}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Get an async agent-adoption scan by ID","tags":["Tools"]}},"/v1/tools/fetch-url":{"post":{"description":"Fetches the body and headers of any URL with automatic JavaScript rendering and common bot-protection handling. Tune via optional parameters (`bodyNeeded`, `headersNeeded`, `cleanHtml`, `maxTimeoutMs`, `bodyMaxBytes`). Response includes `body`, `headers`, `cleanStats`. The `cleanHtml` flag strips HTML noise (scripts, styles, comments) while preserving text content — significant token-cost reduction for LLM consumption; per-request reduction reported in `cleanStats`. Returns `headersAvailable: false` when advanced behavioral fingerprinting prevents header access. Intended for AI agents and customer integrations that need direct URL content access.","operationId":"PublicFetchUrlToolController_fetchUrl_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PTFetchUrlRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"title":"ItemResponseOfFetchUrlToolResponse","type":"object","properties":{"item":{"$ref":"#/components/schemas/FetchUrlToolResponse"}},"required":["item"]}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"502":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}},"security":[{"CL-API-Key":[]}],"summary":"Fetch URL body and headers with JS-rendering + bot-protection handling","tags":["Tools"]}}},"info":{"title":"CompetLab API","description":"\nWelcome to the CompetLab API documentation. This API provides programmatic access to your competitive intelligence data — technology stacks, content strategy, messaging & positioning, pricing plans, and AI brand visibility across ChatGPT, Claude, and Gemini.\n\n### Who is this for?\n\n- **Developers** building integrations with internal tools, CRMs, or BI platforms\n- **Agencies** building whitelabel competitive dashboards for their clients\n- **AI agents and MCP servers** consuming structured competitive data\n- **Automation platforms** (Zapier, n8n) monitoring competitor changes\n\n### Authentication\n\nAll endpoints require a `CL-API-Key` header. Generate your API key in the CompetLab app under **Your Organization → Settings → API Keys**.\n\n```\nCL-API-Key: cl_live_a1b2c3d4e5f6...\n```\n\nKeys are organization-scoped — one key accesses all projects in your organization. Two permission scopes exist: `read` (current API) and `read_write` (future).\n\nTo manage your keys (create, revoke, set expiration): **Your Organization → Settings → API Keys**.\n\n### Response Format\n\nEvery response follows one of three shapes:\n\n**Single resource:**\n```json\n{ \"item\": { \"id\": \"...\", \"name\": \"...\" } }\n```\n\n**Collection (with optional pagination):**\n```json\n{ \"items\": [...], \"pagination\": { \"page\": 1, \"limit\": 20, \"total\": 47, \"totalPages\": 3, \"hasMore\": true } }\n```\n\n**Error:**\n```json\n{ \"error\": { \"code\": \"project_not_found\", \"message\": \"Project not found\", \"status\": 404 } }\n```\n\nPagination uses `?page=1&limit=20` (1-indexed, default 20, max 100).\n\n### Error Codes\n\nAll errors return a machine-readable `code` field for programmatic handling:\n\n| Code | Status | Description |\n|------|--------|-------------|\n| `api_key_missing` | 401 | No `CL-API-Key` header provided |\n| `api_key_invalid` | 401 | Key not found or malformed |\n| `api_key_revoked` | 401 | Key has been revoked |\n| `api_key_expired` | 401 | Key has expired |\n| `insufficient_scope` | 403 | Key doesn't have the required permission scope |\n| `project_not_found` | 404 | Project doesn't exist or doesn't belong to your organization |\n| `no_data_available` | 404 | No monitoring data available yet for this dimension |\n| `not_found` | 404 | Requested resource not found |\n| `invalid_parameters` | 400 | Invalid query parameters or request format |\n| `rate_limit_exceeded` | 429 | Rate limit exceeded for this API key |\n| `internal_error` | 500 | Unexpected server error — retry or contact support |\n| `bad_gateway` | 502 | Upstream service returned an invalid response — retry with backoff |\n| `service_unavailable` | 503 | Service temporarily unavailable — retry with backoff |\n| `gateway_timeout` | 504 | Upstream service timed out — retry with backoff |\n\n**Note on 5xx responses:** The `message` field for 5xx errors is a static string (`\"Internal server error\"`). Branch on `code` for programmatic handling — do not pattern-match on `message` for 5xx.\n\n### Monitoring Dimensions\n\nCompetLab monitors five dimensions of competitive intelligence:\n\n| Dimension | Route | What it monitors |\n|-----------|-------|-----------------|\n| **Tech & Trust Profile** | `/tech-trust` | Technology stack, security headers, trust signals, DNS, robots.txt |\n| **Content Intelligence** | `/content` | Sitemap structure, URL volume, content categories, URL changes |\n| **Positioning** | `/positioning` | Homepage messaging, value propositions, CTAs, target audience |\n| **Pricing Intelligence** | `/pricing` | Pricing plans, tiers, free trials, enterprise options, promotions |\n| **AI Visibility** | `/ai-visibility` | Brand mentions and rankings across ChatGPT, Claude, and Gemini |\n\nEach dimension has three endpoints: a **dashboard** (latest monitoring data), **history** (paginated past runs), and **run detail** (full data for a specific historical run).\n\n### Strategic Briefing\n\nBeyond the raw per-dimension data, `/strategic-briefing` returns the latest **synthesized** competitive briefing — the as-of read of what changed, what it means, and what to do, with an executive hub, deep-dives, a competitor dossier, and a ranked action plan. It synthesizes a **broader analytical set than the five live-monitored dashboards above** (also covering landscape, funding, hiring/GTM, product launches and more). It is lean by default (request only the `sections` you need — it defaults to the `hub`, which doubles as the navigation map) and always carries methodology `coverage` caveats. See the endpoint for the full `sections` list.\n\n### Quick Start\n\n**Step 1** — Get your API key from **Your Organization → Settings → API Keys** in the [CompetLab app](https://app.competlab.com)\n\n**Step 2** — List your projects:\n```bash\ncurl -H \"CL-API-Key: cl_live_your_key_here\" https://api.competlab.com/v1/projects\n```\n\n**Step 3** — Get the latest pricing intelligence:\n```bash\ncurl -H \"CL-API-Key: cl_live_your_key_here\" https://api.competlab.com/v1/projects/{projectId}/pricing\n```\n\n### Additional Resources\n\n- [OpenAPI JSON Spec](https://api.competlab.com/v1/docs/openapi.json) — Machine-readable API definition for code generators and integrations\n- **API Key Management** — Your Organization → Settings → API Keys in the CompetLab app\n\n### Rate Limits\n\nRate limiting is not enforced in v1. We recommend keeping requests under **60 per minute** as a best practice. Rate limits will be introduced in a future version with proper `429` responses and `Retry-After` headers.\n","version":"1.0","contact":{}},"tags":[],"servers":[{"url":"https://api.competlab.com","description":"Production"}],"components":{"securitySchemes":{"CL-API-Key":{"type":"apiKey","in":"header","name":"CL-API-Key","description":"API key generated in the CompetLab dashboard under Settings → API Keys. Pass as CL-API-Key header."}},"schemas":{"HealthResponse":{"type":"object","properties":{"status":{"type":"string","description":"API status","example":"ok"},"timestamp":{"type":"string","description":"Current server timestamp in ISO-8601 format","example":"2026-03-15T10:00:00.000Z"}},"required":["status","timestamp"]},"ApiErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code in snake_case","example":"project_not_found"},"message":{"type":"string","description":"Human-readable error message","example":"Project not found"},"status":{"type":"number","description":"HTTP status code","example":404}},"required":["code","message","status"]},"ApiErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ApiErrorResponse"}},"required":["error"]},"ProjectListItemResponse":{"type":"object","properties":{"id":{"type":"string","description":"Project ID","example":"507f1f77bcf86cd799439011"},"organizationId":{"type":"string","description":"Organization ID that owns this project","example":"507f1f77bcf86cd799439011"},"name":{"type":"string","description":"Project name","example":"My SaaS Product"},"domain":{"type":"string","description":"Monitored domain","example":"mycompany.com"},"status":{"type":"string","description":"Project status","enum":["market_discovering","active"],"example":"active"},"competitorCount":{"type":"number","description":"Number of monitored competitors","example":5},"lastMonitoredAt":{"type":"object","description":"Most recent completed monitoring run (ISO-8601), or null if no runs yet","example":"2026-03-15T10:00:00.000Z","nullable":true},"createdAt":{"type":"string","description":"Project creation date (ISO-8601)","example":"2026-01-10T08:30:00.000Z"}},"required":["id","organizationId","name","domain","status","competitorCount","lastMonitoredAt","createdAt"]},"DimensionLastRunResponse":{"type":"object","properties":{"lastRunAt":{"type":"object","description":"Timestamp of the last completed run for this dimension (ISO-8601), or null if no runs","example":"2026-03-14T18:30:00.000Z","nullable":true}},"required":["lastRunAt"]},"DimensionFreshnessResponse":{"type":"object","properties":{"techTrust":{"description":"Technology stack, security headers, trust signals, and DNS monitoring","allOf":[{"$ref":"#/components/schemas/DimensionLastRunResponse"}]},"content":{"description":"Website structure, URL discovery, and content change detection","allOf":[{"$ref":"#/components/schemas/DimensionLastRunResponse"}]},"positioning":{"description":"Homepage messaging, value propositions, CTAs, and competitive positioning","allOf":[{"$ref":"#/components/schemas/DimensionLastRunResponse"}]},"pricing":{"description":"Pricing plans, tiers, features, and promotional offers","allOf":[{"$ref":"#/components/schemas/DimensionLastRunResponse"}]},"aiVisibility":{"description":"AI brand mentions across ChatGPT, Claude, and Gemini","allOf":[{"$ref":"#/components/schemas/DimensionLastRunResponse"}]}},"required":["techTrust","content","positioning","pricing","aiVisibility"]},"ProjectDetailResponse":{"type":"object","properties":{"id":{"type":"string","description":"Project ID","example":"507f1f77bcf86cd799439011"},"organizationId":{"type":"string","description":"Organization ID that owns this project","example":"507f1f77bcf86cd799439011"},"name":{"type":"string","description":"Project name","example":"My SaaS Product"},"domain":{"type":"string","description":"Monitored domain","example":"mycompany.com"},"status":{"type":"string","description":"Project status","enum":["market_discovering","active"],"example":"active"},"competitorCount":{"type":"number","description":"Number of monitored competitors","example":5},"lastMonitoredAt":{"type":"object","description":"Most recent completed monitoring run (ISO-8601), or null if no runs yet","example":"2026-03-15T10:00:00.000Z","nullable":true},"createdAt":{"type":"string","description":"Project creation date (ISO-8601)","example":"2026-01-10T08:30:00.000Z"},"dimensions":{"description":"Per-dimension last run timestamps","allOf":[{"$ref":"#/components/schemas/DimensionFreshnessResponse"}]},"prompts":{"description":"AI monitoring prompt texts","example":["Best CRM for small business","Compare CRM platforms"],"type":"array","items":{"type":"string"}},"promptsLastChangedAt":{"type":"object","description":"When prompts were last modified (ISO-8601), or null if never changed","example":"2026-02-20T14:00:00.000Z","nullable":true}},"required":["id","organizationId","name","domain","status","competitorCount","lastMonitoredAt","createdAt","dimensions","prompts","promptsLastChangedAt"]},"CompetitorListItemResponse":{"type":"object","properties":{"id":{"type":"string","description":"Competitor ID","example":"507f1f77bcf86cd799439011"},"domain":{"type":"string","description":"Competitor domain","example":"competitor.com"},"isOwn":{"type":"boolean","description":"Whether this is the project's own domain","example":false},"preparationStatus":{"type":"string","description":"Data preparation status","enum":["pending","in_progress","complete"],"example":"complete"},"createdAt":{"type":"string","description":"When the competitor was created (ISO-8601)","example":"2026-01-15T12:00:00.000Z"}},"required":["id","domain","isOwn","preparationStatus","createdAt"]},"MonitoredPagesResponse":{"type":"object","properties":{"homepage":{"type":"object","description":"Homepage URL, or null if not identified","example":"https://competitor.com/","nullable":true},"pricing":{"type":"object","description":"Pricing page URL, or null if not identified","example":"https://competitor.com/pricing","nullable":true}},"required":["homepage","pricing"]},"CompetitorDetailResponse":{"type":"object","properties":{"id":{"type":"string","description":"Competitor ID","example":"507f1f77bcf86cd799439011"},"domain":{"type":"string","description":"Competitor domain","example":"competitor.com"},"isOwn":{"type":"boolean","description":"Whether this is the project's own domain","example":false},"preparationStatus":{"type":"string","description":"Data preparation status","enum":["pending","in_progress","complete"],"example":"complete"},"createdAt":{"type":"string","description":"When the competitor was created (ISO-8601)","example":"2026-01-15T12:00:00.000Z"},"monitoredPages":{"description":"Monitored page URLs for this competitor","allOf":[{"$ref":"#/components/schemas/MonitoredPagesResponse"}]}},"required":["id","domain","isOwn","preparationStatus","createdAt","monitoredPages"]},"SignalsAvailableUnavailableResponse":{"type":"object","properties":{"available":{"type":"boolean","description":"Always false for this discriminator.","example":false},"reason":{"type":"string","description":"Why signals are unavailable. Known sub-classes are documented; new behavioral-protection categories may be classified over time.","enum":["site_uses_behavioral_protection"],"example":"site_uses_behavioral_protection"}},"required":["available","reason"]},"SummaryCustomerResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Your domain","example":"yoursite.com"},"securityGrade":{"type":"string","description":"Your security grade, or null if check failed","enum":["A","B","C","D","F"],"nullable":true,"example":"B"},"securityScore":{"type":"object","description":"Your security score (0-100), or null if check failed","nullable":true,"example":72},"securitySignalsAvailable":{"description":"Honest-degradation discriminator. Present ONLY when your own domain runs behavioral protection that blocks header inspection (~1.1% of sites). When present, `securityGrade` and `securityScore` above are forced to `null` so dashboards never surface F-grade placeholder values. Absent on healthy scans (the normal path).","allOf":[{"$ref":"#/components/schemas/SignalsAvailableUnavailableResponse"}]},"trustSignalCount":{"type":"number","description":"Number of trust signals detected on your domain","example":8},"techStackCount":{"type":"number","description":"Number of technologies detected on your domain","example":14},"blockedAiBotsCount":{"type":"number","description":"Number of AI bots blocked by your robots.txt","example":0},"allowsAiAccess":{"type":"boolean","description":"Whether your domain allows AI crawler access","example":true}},"required":["domain","securityGrade","securityScore","trustSignalCount","techStackCount","blockedAiBotsCount","allowsAiAccess"]},"SummaryTopSecurityResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Top security competitor domain","example":"rival.com"},"securityGrade":{"type":"string","description":"Their security grade","enum":["A","B","C","D","F"],"example":"A"},"securityScore":{"type":"number","description":"Their security score (0-100)","example":95}},"required":["domain","securityGrade","securityScore"]},"SummaryTopTrustResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Top trust signals competitor domain","example":"other.com"},"trustSignalCount":{"type":"number","description":"Their trust signal count","example":15}},"required":["domain","trustSignalCount"]},"TechTrustDashboardSummaryResponse":{"type":"object","properties":{"competitorsChecked":{"type":"number","description":"Number of competitors checked in this run","example":6},"competitorsSuccessful":{"type":"number","description":"Number of competitors successfully checked","example":5},"customer":{"description":"Your domain's key metrics","allOf":[{"$ref":"#/components/schemas/SummaryCustomerResponse"}]},"topSecurityCompetitor":{"description":"Competitor with the highest security score, or null if no competitors checked","nullable":true,"allOf":[{"$ref":"#/components/schemas/SummaryTopSecurityResponse"}]},"topTrustCompetitor":{"description":"Competitor with the most trust signals, or null if no competitors checked","nullable":true,"allOf":[{"$ref":"#/components/schemas/SummaryTopTrustResponse"}]},"securityScoreGap":{"type":"number","description":"Your security score minus top competitor score (negative = you are behind)","example":-23},"trustSignalGap":{"type":"number","description":"Your trust signal count minus top competitor count (negative = you are behind)","example":-7}},"required":["competitorsChecked","competitorsSuccessful","customer","securityScoreGap","trustSignalGap"]},"SecurityHeadersResponse":{"type":"object","properties":{"grade":{"type":"string","description":"Overall security grade","enum":["A","B","C","D","F"],"example":"A"},"score":{"type":"number","description":"Security score (0-100)","example":85},"hsts":{"type":"boolean","description":"Has HTTP Strict Transport Security header","example":true},"csp":{"type":"boolean","description":"Has Content Security Policy header","example":true},"xFrameOptions":{"type":"boolean","description":"Has X-Frame-Options header","example":true},"xContentTypeOptions":{"type":"boolean","description":"Has X-Content-Type-Options header","example":true},"signalsAvailable":{"description":"Honest-degradation discriminator. Present ONLY when the upstream homepage fetch couldn't recover response headers (~1.1% of sites running behavioral protection that blocks header inspection). When present, ALL OTHER FIELDS in this object — `grade`, `score`, `hsts`, `csp`, `xFrameOptions`, `xContentTypeOptions` — are PLACEHOLDER values (the fallback 'no headers detected' shape), NOT a real 'this site has no security headers' result. Absent on healthy scans (the normal path).","allOf":[{"$ref":"#/components/schemas/SignalsAvailableUnavailableResponse"}]}},"required":["grade","score","hsts","csp","xFrameOptions","xContentTypeOptions"]},"TrustSignalCategoriesResponse":{"type":"object","properties":{"compliance":{"type":"number","description":"Number of compliance signals (SOC2, ISO27001, HIPAA, GDPR, CCPA)","example":3},"reviews":{"type":"number","description":"Number of review platform badges (G2, Capterra, Trustpilot, etc.)","example":4},"socialProof":{"type":"number","description":"Number of social proof signals (customer logos, counts, case studies)","example":2},"certifications":{"type":"number","description":"Number of certifications","example":1}},"required":["compliance","reviews","socialProof","certifications"]},"TrustSignalsResponse":{"type":"object","properties":{"totalCount":{"type":"number","description":"Total number of trust signals detected","example":10},"categories":{"description":"Trust signals broken down by category","allOf":[{"$ref":"#/components/schemas/TrustSignalCategoriesResponse"}]}},"required":["totalCount","categories"]},"TechnologyStackResponse":{"type":"object","properties":{"tech":{"description":"Core technology stack (frameworks, languages, infrastructure)","example":["React","Next.js","TypeScript"],"type":"array","items":{"type":"string"}},"growth":{"description":"Growth and marketing tools (analytics, ads, SEO)","example":["Google Analytics","HubSpot"],"type":"array","items":{"type":"string"}},"engagement":{"description":"Customer engagement tools (chat, support, CRM)","example":["Intercom","Zendesk"],"type":"array","items":{"type":"string"}},"totalCount":{"type":"number","description":"Total number of technologies detected","example":12}},"required":["tech","growth","engagement","totalCount"]},"RobotsTxtResponse":{"type":"object","properties":{"exists":{"type":"boolean","description":"Whether a robots.txt file exists","example":true},"aiBotsBlocked":{"description":"AI bots explicitly blocked in robots.txt","example":["GPTBot","ClaudeBot"],"type":"array","items":{"type":"string"}},"totalRules":{"type":"number","description":"Total number of disallow rules","example":5}},"required":["exists","aiBotsBlocked","totalRules"]},"DnsInfrastructureResponse":{"type":"object","properties":{"emailProvider":{"type":"string","description":"Email service provider","example":"Google Workspace"},"dnsProvider":{"type":"string","description":"DNS hosting provider","example":"Cloudflare"}},"required":["emailProvider","dnsProvider"]},"TechTrustCompetitorResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Competitor domain","example":"competitor.com"},"isOwn":{"type":"boolean","description":"Whether this is the project's own domain","example":false},"securityHeaders":{"description":"Security headers analysis","allOf":[{"$ref":"#/components/schemas/SecurityHeadersResponse"}]},"trustSignals":{"description":"Trust signals and compliance badges","allOf":[{"$ref":"#/components/schemas/TrustSignalsResponse"}]},"technologyStack":{"description":"Detected technology stack","allOf":[{"$ref":"#/components/schemas/TechnologyStackResponse"}]},"robotsTxt":{"description":"Robots.txt analysis and AI bot blocking","allOf":[{"$ref":"#/components/schemas/RobotsTxtResponse"}]},"dnsInfrastructure":{"description":"DNS and email infrastructure","allOf":[{"$ref":"#/components/schemas/DnsInfrastructureResponse"}]}},"required":["domain","isOwn","securityHeaders","trustSignals","technologyStack","robotsTxt","dnsInfrastructure"]},"TechTrustDashboardResponse":{"type":"object","properties":{"lastUpdatedAt":{"type":"string","description":"When this data was last updated (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Run summary with competitive gap analysis","allOf":[{"$ref":"#/components/schemas/TechTrustDashboardSummaryResponse"}]},"competitors":{"description":"Per-competitor tech & trust data","type":"array","items":{"$ref":"#/components/schemas/TechTrustCompetitorResponse"}}},"required":["lastUpdatedAt","summary","competitors"]},"PaginationMeta":{"type":"object","properties":{"page":{"type":"number","description":"Current page number (1-indexed)","example":1},"limit":{"type":"number","description":"Number of items per page","example":20},"total":{"type":"number","description":"Total number of items across all pages","example":47},"totalPages":{"type":"number","description":"Total number of pages","example":3},"hasMore":{"type":"boolean","description":"Whether more pages exist after the current page","example":true}},"required":["page","limit","total","totalPages","hasMore"]},"TechTrustHistoryItemResponse":{"type":"object","properties":{"runId":{"type":"string","description":"Run ID","example":"507f1f77bcf86cd799439011"},"completedAt":{"type":"string","description":"When this run completed (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Run summary statistics","allOf":[{"$ref":"#/components/schemas/TechTrustDashboardSummaryResponse"}]}},"required":["runId","completedAt","summary"]},"TechTrustRunDetailResponse":{"type":"object","properties":{"runId":{"type":"string","description":"Run ID","example":"507f1f77bcf86cd799439011"},"completedAt":{"type":"string","description":"When this run completed (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Run summary statistics","allOf":[{"$ref":"#/components/schemas/TechTrustDashboardSummaryResponse"}]},"competitors":{"description":"Per-competitor tech & trust data for this run","type":"array","items":{"$ref":"#/components/schemas/TechTrustCompetitorResponse"}}},"required":["runId","completedAt","summary","competitors"]},"ContentSummaryCustomerResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Your domain","example":"yoursite.com"},"totalUrls":{"type":"number","description":"Total URLs discovered across all sitemaps","example":350},"strategicUrls":{"type":"number","description":"Strategic URLs (excludes legal/other categories)","example":280},"categorizedCounts":{"type":"object","description":"URL counts broken down by content category","example":{"blog":120,"docs":80,"tools":5,"landing":30,"legal":10,"caseStudies":0,"comparison":3,"integrations":25,"changelog":15,"webinars":2,"other":60}}},"required":["domain","totalUrls","strategicUrls","categorizedCounts"]},"ContentSummaryTopCompetitorResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Top competitor domain by strategic URLs","example":"rival.com"},"strategicUrls":{"type":"number","description":"Their strategic URL count","example":420}},"required":["domain","strategicUrls"]},"ContentGapLeaderResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Leader competitor domain","example":"competitor.com"},"count":{"type":"number","description":"Number of URLs in this category","example":42},"exampleUrls":{"description":"Example URLs for inspiration (3-5)","example":["https://competitor.com/blog/post-1","https://competitor.com/blog/post-2"],"type":"array","items":{"type":"string"}}},"required":["domain","count","exampleUrls"]},"ContentCriticalGapResponse":{"type":"object","properties":{"category":{"type":"string","description":"Content category where you have zero content","example":"caseStudies"},"categoryLabel":{"type":"string","description":"Human-readable category name","example":"Case Studies"},"competitorsWithContent":{"type":"number","description":"Number of competitors that have content in this category","example":3},"leader":{"description":"Competitor leading in this category","allOf":[{"$ref":"#/components/schemas/ContentGapLeaderResponse"}]},"actionHint":{"type":"string","description":"Actionable guidance for addressing this gap","example":"Create 3-5 case studies showcasing customer success stories"}},"required":["category","categoryLabel","competitorsWithContent","leader"]},"ContentSignificantGapResponse":{"type":"object","properties":{"category":{"type":"string","description":"Content category where you are significantly behind","example":"blog"},"categoryLabel":{"type":"string","description":"Human-readable category name","example":"Blog Posts"},"customerCount":{"type":"number","description":"Your URL count in this category","example":5},"competitorAverage":{"type":"number","description":"Average competitor URL count","example":25},"competitorMax":{"type":"number","description":"Maximum competitor URL count","example":42},"gapPercentage":{"type":"number","description":"How far behind you are as a percentage (negative = behind)","example":-80},"leader":{"description":"Competitor leading in this category","allOf":[{"$ref":"#/components/schemas/ContentGapLeaderResponse"}]},"actionHint":{"type":"string","description":"Actionable guidance for addressing this gap","example":"Increase blog output to at least match competitor average of 25 posts"}},"required":["category","categoryLabel","customerCount","competitorAverage","competitorMax","gapPercentage","leader"]},"ContentAdvantageResponse":{"type":"object","properties":{"category":{"type":"string","description":"Content category where you lead","example":"docs"},"categoryLabel":{"type":"string","description":"Human-readable category name","example":"Documentation"},"customerCount":{"type":"number","description":"Your URL count in this category","example":120},"competitorMax":{"type":"number","description":"Maximum competitor URL count","example":45},"leadAmount":{"type":"number","description":"How many more URLs you have than the best competitor","example":75}},"required":["category","categoryLabel","customerCount","competitorMax","leadAmount"]},"ContentOnTrackResponse":{"type":"object","properties":{"category":{"type":"string","description":"Content category where you are competitive","example":"landing"},"categoryLabel":{"type":"string","description":"Human-readable category name","example":"Landing Pages"},"customerCount":{"type":"number","description":"Your URL count in this category","example":30},"competitorMax":{"type":"number","description":"Maximum competitor URL count","example":35},"differencePercent":{"type":"number","description":"Percentage difference from the best competitor","example":-14}},"required":["category","categoryLabel","customerCount","competitorMax","differencePercent"]},"ContentDashboardSummaryResponse":{"type":"object","properties":{"sitemapsChecked":{"type":"number","description":"Number of sitemaps checked in this run","example":8},"sitemapsSuccessful":{"type":"number","description":"Number of sitemaps successfully processed","example":7},"customer":{"description":"Your domain's content metrics","allOf":[{"$ref":"#/components/schemas/ContentSummaryCustomerResponse"}]},"topCompetitor":{"description":"Competitor with the most strategic URLs, or null if no competitors checked","nullable":true,"allOf":[{"$ref":"#/components/schemas/ContentSummaryTopCompetitorResponse"}]},"strategicUrlGap":{"type":"number","description":"Your strategic URL count minus top competitor (negative = you are behind)","example":-140},"overallRank":{"type":"number","description":"Your rank by strategic content among the sites that returned comparable content data — your own site plus `comparableCompetitors` competitors (field size = comparableCompetitors + 1). Null when fewer than two competitors had usable data, or when your own site returned no usable data to rank.","example":3,"nullable":true},"comparableCompetitors":{"type":"number","description":"Competitors (excluding your own site) that returned usable content data — the sample size behind the gap and advantage comparisons. The overall rank is taken over this set plus your own site, so the rank's field size is `comparableCompetitors + 1`.","example":4},"criticalGaps":{"description":"Content categories where you have zero content but competitors do","type":"array","items":{"$ref":"#/components/schemas/ContentCriticalGapResponse"}},"significantGaps":{"description":"Content categories where you are significantly behind (>50%)","type":"array","items":{"$ref":"#/components/schemas/ContentSignificantGapResponse"}},"advantages":{"description":"Content categories where you lead all competitors","type":"array","items":{"$ref":"#/components/schemas/ContentAdvantageResponse"}},"onTrack":{"description":"Content categories where you are competitive (within threshold)","type":"array","items":{"$ref":"#/components/schemas/ContentOnTrackResponse"}},"totalCriticalGaps":{"type":"number","description":"Total number of critical content gaps","example":2},"totalSignificantGaps":{"type":"number","description":"Total number of significant content gaps","example":1},"totalAdvantages":{"type":"number","description":"Total number of content advantages","example":3},"totalOnTrack":{"type":"number","description":"Total number of on-track categories","example":4}},"required":["sitemapsChecked","sitemapsSuccessful","customer","strategicUrlGap","comparableCompetitors","criticalGaps","significantGaps","advantages","onTrack","totalCriticalGaps","totalSignificantGaps","totalAdvantages","totalOnTrack"]},"ContentCompetitorResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Competitor domain","example":"competitor.com"},"isOwn":{"type":"boolean","description":"Whether this is the project's own domain","example":false},"totalUrls":{"type":"number","description":"Total URLs discovered across all sitemaps for this competitor","example":450},"strategicUrls":{"type":"number","description":"Strategic URLs (excludes legal/other categories)","example":380},"categorizedCounts":{"type":"object","description":"URL counts by content category, or null if categorization unavailable","nullable":true,"example":{"blog":150,"docs":100,"tools":10,"landing":40,"legal":15,"caseStudies":8,"comparison":5,"integrations":30,"changelog":20,"webinars":7,"other":65}},"sitemapCount":{"type":"number","description":"Number of sitemaps discovered for this competitor","example":2}},"required":["domain","isOwn","totalUrls","strategicUrls","sitemapCount"]},"ContentDashboardResponse":{"type":"object","properties":{"lastUpdatedAt":{"type":"string","description":"When this data was last updated (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Run summary with content gap analysis","allOf":[{"$ref":"#/components/schemas/ContentDashboardSummaryResponse"}]},"competitors":{"description":"Per-competitor content data","type":"array","items":{"$ref":"#/components/schemas/ContentCompetitorResponse"}}},"required":["lastUpdatedAt","summary","competitors"]},"ContentHistoryItemResponse":{"type":"object","properties":{"runId":{"type":"string","description":"Run ID","example":"507f1f77bcf86cd799439011"},"completedAt":{"type":"string","description":"When this run completed (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Run summary statistics","allOf":[{"$ref":"#/components/schemas/ContentDashboardSummaryResponse"}]}},"required":["runId","completedAt","summary"]},"ContentRunDetailResponse":{"type":"object","properties":{"runId":{"type":"string","description":"Run ID","example":"507f1f77bcf86cd799439011"},"completedAt":{"type":"string","description":"When this run completed (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Run summary statistics","allOf":[{"$ref":"#/components/schemas/ContentDashboardSummaryResponse"}]},"competitors":{"description":"Per-competitor content data for this run","type":"array","items":{"$ref":"#/components/schemas/ContentCompetitorResponse"}}},"required":["runId","completedAt","summary","competitors"]},"ContentChangelogItemResponse":{"type":"object","properties":{"competitorDomain":{"type":"string","description":"Competitor domain","example":"competitor.com"},"sitemapUrl":{"type":"string","description":"Sitemap URL where changes were detected","example":"https://competitor.com/sitemap.xml"},"checkedAt":{"type":"string","description":"When this change was detected (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"totalAdded":{"type":"number","description":"Total number of URLs added","example":5},"totalRemoved":{"type":"number","description":"Total number of URLs removed","example":2},"addedByCategory":{"type":"object","description":"Added URLs grouped by content category. By default each category is capped at 3 sample URLs (numeric totals remain accurate via `addedCounts`). Pass `allUrlsPerCategory=true` to return full URL lists.","example":{"blog":["https://competitor.com/blog/new-post"],"docs":["https://competitor.com/docs/new-guide"]}},"removedByCategory":{"type":"object","description":"Removed URLs grouped by content category. By default each category is capped at 3 sample URLs (numeric totals remain accurate via `removedCounts`). Pass `allUrlsPerCategory=true` to return full URL lists.","example":{"landing":["https://competitor.com/old-landing"]}},"addedCounts":{"type":"object","description":"Count of added URLs per category","example":{"blog":1,"docs":1}},"removedCounts":{"type":"object","description":"Count of removed URLs per category","example":{"landing":1}}},"required":["competitorDomain","sitemapUrl","checkedAt","totalAdded","totalRemoved","addedByCategory","removedByCategory","addedCounts","removedCounts"]},"PositioningSummaryCustomerResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Your domain","example":"yoursite.com"},"messagingStrengthScore":{"type":"number","description":"Messaging strength score (0-100) based on homepage completeness","example":72},"hasSpecificHeadline":{"type":"boolean","description":"Whether your headline includes specific metrics or numbers","example":true},"hasStrongCta":{"type":"boolean","description":"Whether your CTA is strong and specific (not just 'Get Started')","example":true},"showsPricing":{"type":"boolean","description":"Whether pricing is shown on your homepage","example":false},"hasFreeTrial":{"type":"boolean","description":"Whether you offer a free trial","example":true},"primaryCta":{"type":"string","description":"Your primary CTA text","example":"Start Free Trial"},"mainHeadline":{"type":"string","description":"Your main headline","example":"Ship Projects 10x Faster"}},"required":["domain","messagingStrengthScore","hasSpecificHeadline","hasStrongCta","showsPricing","hasFreeTrial","primaryCta","mainHeadline"]},"PositioningSummaryTopCompetitorResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Top messaging competitor domain","example":"rival.com"},"messagingStrengthScore":{"type":"number","description":"Their messaging strength score (0-100)","example":88},"primaryCta":{"type":"string","description":"Their primary CTA text","example":"Try It Free"},"mainHeadline":{"type":"string","description":"Their main headline","example":"The Future of Work"}},"required":["domain","messagingStrengthScore","primaryCta","mainHeadline"]},"PositioningCtaComparisonResponse":{"type":"object","properties":{"yourCta":{"type":"string","description":"Your primary CTA text","example":"Start Free Trial"},"strongestCompetitorCta":{"type":"string","description":"Strongest competitor's CTA text","example":"Get Started — It's Free"},"strongestCompetitorDomain":{"type":"string","description":"Domain of the competitor with the strongest CTA","example":"rival.com"}},"required":["yourCta","strongestCompetitorCta","strongestCompetitorDomain"]},"PositioningPricingComparisonResponse":{"type":"object","properties":{"competitorsShowingPrice":{"type":"number","description":"Number of competitors showing pricing on homepage","example":3},"competitorsWithFreeTrial":{"type":"number","description":"Number of competitors offering a free trial","example":4},"youShowPrice":{"type":"boolean","description":"Whether you show pricing on your homepage","example":false},"youHaveFreeTrial":{"type":"boolean","description":"Whether you offer a free trial","example":true}},"required":["competitorsShowingPrice","competitorsWithFreeTrial","youShowPrice","youHaveFreeTrial"]},"PositioningDashboardSummaryResponse":{"type":"object","properties":{"competitorsChecked":{"type":"number","description":"Number of competitor homepages checked in this run","example":6},"competitorsSuccessful":{"type":"number","description":"Number of competitor homepages successfully analyzed","example":5},"customer":{"description":"Your domain's messaging metrics","allOf":[{"$ref":"#/components/schemas/PositioningSummaryCustomerResponse"}]},"topMessagingCompetitor":{"description":"Competitor with the highest messaging strength score, or null if no competitors checked","nullable":true,"allOf":[{"$ref":"#/components/schemas/PositioningSummaryTopCompetitorResponse"}]},"ctaComparison":{"description":"CTA comparison between you and the strongest competitor, or null if unavailable","nullable":true,"allOf":[{"$ref":"#/components/schemas/PositioningCtaComparisonResponse"}]},"pricingComparison":{"description":"Pricing transparency comparison across competitors","allOf":[{"$ref":"#/components/schemas/PositioningPricingComparisonResponse"}]},"messagingScoreGap":{"type":"number","description":"Your messaging score minus top competitor score (negative = you are behind)","example":-16}},"required":["competitorsChecked","competitorsSuccessful","customer","pricingComparison","messagingScoreGap"]},"PositioningCompetitorContentResponse":{"type":"object","properties":{"pageTitle":{"type":"string","description":"Page title","example":"Acme - The #1 Project Management Tool"},"pageDescription":{"type":"string","description":"Page meta description","example":"Manage projects, track tasks, and collaborate with your team."},"mainHeadline":{"type":"string","description":"Main homepage headline","example":"Ship Projects 10x Faster"},"tagline":{"type":"string","description":"Tagline or subheadline","example":"The all-in-one platform for modern teams"},"valueProposition":{"type":"string","description":"Core value proposition statement","example":"Streamline your workflow with AI-powered project management"},"primaryCTA":{"type":"string","description":"Primary call-to-action text","example":"Start Free Trial"},"secondaryCTA":{"type":"string","description":"Secondary call-to-action text","example":"Book a Demo"},"keyOfferings":{"description":"Key product offerings listed on homepage","example":["Task Management","Time Tracking","Team Collaboration"],"type":"array","items":{"type":"string"}},"targetAudience":{"type":"string","description":"Target audience as described on homepage","example":"Product teams and agencies"},"mainDifferentiator":{"type":"string","description":"Main differentiator or unique selling point","example":"AI-powered automation that saves 5 hours per week"},"pricingMentioned":{"type":"boolean","description":"Whether pricing is mentioned on the homepage","example":true},"startingPrice":{"type":"string","description":"Starting price if mentioned on homepage","example":"$9/month"},"hasFreeTrial":{"type":"boolean","description":"Whether a free trial is offered","example":true},"freeTrialDuration":{"type":"string","description":"Free trial duration if offered","example":"14 days"}},"required":["pageTitle","pageDescription","mainHeadline","tagline","valueProposition","primaryCTA","secondaryCTA","keyOfferings","targetAudience","mainDifferentiator","pricingMentioned","startingPrice","hasFreeTrial","freeTrialDuration"]},"PositioningCompetitorResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Competitor domain","example":"competitor.com"},"isOwn":{"type":"boolean","description":"Whether this is the project's own domain","example":false},"homepageUrl":{"type":"string","description":"Homepage URL that was analyzed","example":"https://competitor.com"},"content":{"description":"Extracted homepage content and messaging","allOf":[{"$ref":"#/components/schemas/PositioningCompetitorContentResponse"}]}},"required":["domain","isOwn","homepageUrl","content"]},"PositioningDashboardResponse":{"type":"object","properties":{"lastUpdatedAt":{"type":"string","description":"When this data was last updated (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Run summary with messaging gap analysis","allOf":[{"$ref":"#/components/schemas/PositioningDashboardSummaryResponse"}]},"competitors":{"description":"Per-competitor positioning data","type":"array","items":{"$ref":"#/components/schemas/PositioningCompetitorResponse"}}},"required":["lastUpdatedAt","summary","competitors"]},"PositioningHistoryItemResponse":{"type":"object","properties":{"runId":{"type":"string","description":"Run ID","example":"507f1f77bcf86cd799439011"},"completedAt":{"type":"string","description":"When this run completed (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Run summary statistics","allOf":[{"$ref":"#/components/schemas/PositioningDashboardSummaryResponse"}]}},"required":["runId","completedAt","summary"]},"PositioningRunDetailResponse":{"type":"object","properties":{"runId":{"type":"string","description":"Run ID","example":"507f1f77bcf86cd799439011"},"completedAt":{"type":"string","description":"When this run completed (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Run summary statistics","allOf":[{"$ref":"#/components/schemas/PositioningDashboardSummaryResponse"}]},"competitors":{"description":"Per-competitor positioning data for this run","type":"array","items":{"$ref":"#/components/schemas/PositioningCompetitorResponse"}}},"required":["runId","completedAt","summary","competitors"]},"PricingSummaryCustomerResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Your domain","example":"yoursite.com"},"popularPlanPrice":{"type":"object","description":"Your popular plan price (numeric), or null if unavailable","example":49,"nullable":true},"popularPlanName":{"type":"object","description":"Your popular plan name, or null if unavailable","example":"Professional","nullable":true},"pricingModel":{"type":"object","description":"Your pricing model type, or null if unavailable","example":"per-seat","nullable":true},"hasFreePlan":{"type":"boolean","description":"Whether you offer a free plan","example":false},"hasFreeTrial":{"type":"boolean","description":"Whether you offer a free trial","example":true},"freeTrialDuration":{"type":"object","description":"Free trial duration, or null if not offered","example":"14 days","nullable":true},"hasEnterprisePricing":{"type":"boolean","description":"Whether you offer enterprise/custom pricing","example":true},"tierCount":{"type":"number","description":"Number of pricing tiers","example":3}},"required":["domain","hasFreePlan","hasFreeTrial","hasEnterprisePricing","tierCount"]},"PricingSummaryPriceCompetitorResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Competitor domain","example":"rival.com"},"price":{"type":"number","description":"Price (numeric)","example":99},"planName":{"type":"string","description":"Plan name","example":"Enterprise"}},"required":["domain","price","planName"]},"PricingDashboardSummaryResponse":{"type":"object","properties":{"competitorsChecked":{"type":"number","description":"Number of competitor pricing pages checked","example":6},"competitorsSuccessful":{"type":"number","description":"Number of competitor pricing pages successfully analyzed","example":5},"customer":{"description":"Your pricing metrics","allOf":[{"$ref":"#/components/schemas/PricingSummaryCustomerResponse"}]},"marketAvgPrice":{"type":"object","description":"Market average price (numeric). Null when the competitor sample is too small to compute a meaningful market average.","example":59,"nullable":true},"pricePositionPercent":{"type":"object","description":"Your price position vs market average (percent; negative = below market). Null when the competitor sample is too small for a meaningful comparison.","example":45,"nullable":true},"topPriceCompetitor":{"description":"Competitor with the highest price. Null when the competitor sample is too small for a meaningful comparison.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PricingSummaryPriceCompetitorResponse"}]},"lowestPriceCompetitor":{"description":"Competitor with the lowest price. Null when the competitor sample is too small for a meaningful comparison.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PricingSummaryPriceCompetitorResponse"}]},"pricingSampleSize":{"type":"number","description":"Count of competitors with parseable popular-plan pricing in this run (used to gate market-comparison fields).","example":4},"pricingIsReliable":{"type":"boolean","description":"True when the competitor pricing sample is large enough to support market-comparison framings.","example":true},"competitorsWithFreePlan":{"type":"number","description":"Number of competitors offering a free plan","example":2},"competitorsWithFreeTrial":{"type":"number","description":"Number of competitors offering a free trial","example":4},"competitorsWithEnterprise":{"type":"number","description":"Number of competitors with enterprise pricing","example":3},"activePromotionCount":{"type":"number","description":"Number of competitors running active promotions","example":1},"hasPriceGap":{"type":"boolean","description":"Whether a significant price gap exists vs market","example":true},"hasFreeTierGap":{"type":"boolean","description":"Whether competitors offer free tier but you don't","example":false},"hasEnterpriseGap":{"type":"boolean","description":"Whether competitors offer enterprise pricing but you don't","example":false},"hasPromotionAlert":{"type":"boolean","description":"Whether competitors are running promotions you should know about","example":true}},"required":["competitorsChecked","competitorsSuccessful","customer","pricingSampleSize","pricingIsReliable","competitorsWithFreePlan","competitorsWithFreeTrial","competitorsWithEnterprise","activePromotionCount","hasPriceGap","hasFreeTierGap","hasEnterpriseGap","hasPromotionAlert"]},"PricingPlanResponse":{"type":"object","properties":{"name":{"type":"string","description":"Plan name","example":"Professional"},"price":{"type":"string","description":"Plan price","example":"$49/month"},"summary":{"type":"string","description":"Brief summary of the plan","example":"Best for growing teams with advanced features"}},"required":["name","price","summary"]},"PricingCompetitorContentResponse":{"type":"object","properties":{"pageTitle":{"type":"string","description":"Page title","example":"Acme Pricing - Plans for Every Team"},"pageDescription":{"type":"string","description":"Page meta description","example":"Choose from flexible pricing plans starting at $9/month."},"mainHeadline":{"type":"string","description":"Main pricing page headline","example":"Simple, Transparent Pricing"},"pricingModel":{"type":"string","description":"Pricing model type","example":"per-seat"},"plans":{"description":"Structured pricing plans extracted from the page","type":"array","items":{"$ref":"#/components/schemas/PricingPlanResponse"}},"popularPlanName":{"type":"string","description":"Name of the recommended/popular plan","example":"Professional"},"hasFreePlan":{"type":"boolean","description":"Whether a free plan is offered","example":true},"freePlanName":{"type":"string","description":"Name of the free plan if offered","example":"Starter"},"hasFreeTrial":{"type":"boolean","description":"Whether a free trial is offered","example":true},"freeTrialDuration":{"type":"string","description":"Free trial duration if offered","example":"14 days"},"billingCycleOffered":{"type":"string","description":"Billing cycles offered","example":"monthly, annual"},"annualDiscountAmount":{"type":"string","description":"Annual discount amount if offered","example":"20%"},"moneyBackGuarantee":{"type":"string","description":"Money-back guarantee details","example":"30-day money-back guarantee"},"hasEnterpriseCustomPricing":{"type":"boolean","description":"Whether enterprise/custom pricing is available","example":true},"enterprisePlanCTA":{"type":"string","description":"Enterprise plan CTA text","example":"Contact Sales"},"pricingPageFeatures":{"type":"string","description":"Key features listed on pricing page (comma-separated)","example":"Unlimited projects, Priority support, SSO"},"hasActivePromotion":{"type":"boolean","description":"Whether an active promotion is running","example":false},"promotionDetails":{"type":"string","description":"Promotion details if active","example":""}},"required":["pageTitle","pageDescription","mainHeadline","pricingModel","plans","popularPlanName","hasFreePlan","freePlanName","hasFreeTrial","freeTrialDuration","billingCycleOffered","annualDiscountAmount","moneyBackGuarantee","hasEnterpriseCustomPricing","enterprisePlanCTA","pricingPageFeatures","hasActivePromotion","promotionDetails"]},"PricingCompetitorResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Competitor domain","example":"competitor.com"},"isOwn":{"type":"boolean","description":"Whether this is the project's own domain","example":false},"pricingUrl":{"type":"string","description":"Pricing page URL that was analyzed","example":"https://competitor.com/pricing"},"pricingLocationType":{"type":"string","description":"How the pricing page was located","example":"crawled"},"content":{"description":"Extracted pricing page content","allOf":[{"$ref":"#/components/schemas/PricingCompetitorContentResponse"}]}},"required":["domain","isOwn","pricingUrl","pricingLocationType","content"]},"PricingDashboardResponse":{"type":"object","properties":{"lastUpdatedAt":{"type":"string","description":"When this data was last updated (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Run summary with pricing gap analysis","allOf":[{"$ref":"#/components/schemas/PricingDashboardSummaryResponse"}]},"competitors":{"description":"Per-competitor pricing data","type":"array","items":{"$ref":"#/components/schemas/PricingCompetitorResponse"}}},"required":["lastUpdatedAt","summary","competitors"]},"PricingHistoryItemResponse":{"type":"object","properties":{"runId":{"type":"string","description":"Run ID","example":"507f1f77bcf86cd799439011"},"completedAt":{"type":"string","description":"When this run completed (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Run summary statistics","allOf":[{"$ref":"#/components/schemas/PricingDashboardSummaryResponse"}]}},"required":["runId","completedAt","summary"]},"PricingRunDetailResponse":{"type":"object","properties":{"runId":{"type":"string","description":"Run ID","example":"507f1f77bcf86cd799439011"},"completedAt":{"type":"string","description":"When this run completed (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Run summary statistics","allOf":[{"$ref":"#/components/schemas/PricingDashboardSummaryResponse"}]},"competitors":{"description":"Per-competitor pricing data for this run","type":"array","items":{"$ref":"#/components/schemas/PricingCompetitorResponse"}}},"required":["runId","completedAt","summary","competitors"]},"AiVisibilityProviderMetricResponse":{"type":"object","properties":{"rank":{"type":"object","description":"Average rank across prompts for this provider (lower is better)","example":2.3,"nullable":true},"mentioned":{"type":"boolean","description":"Whether the customer was mentioned by this provider","example":true},"mentionCount":{"type":"number","description":"Number of mentions across prompts for this provider","example":3}},"required":["mentioned"]},"AiVisibilityPerProviderResponse":{"type":"object","properties":{"openai":{"description":"OpenAI (ChatGPT) metrics","allOf":[{"$ref":"#/components/schemas/AiVisibilityProviderMetricResponse"}]},"claude":{"description":"Anthropic (Claude) metrics","allOf":[{"$ref":"#/components/schemas/AiVisibilityProviderMetricResponse"}]},"gemini":{"description":"Google (Gemini) metrics","allOf":[{"$ref":"#/components/schemas/AiVisibilityProviderMetricResponse"}]}},"required":["openai","claude","gemini"]},"AiVisibilityCustomerMetricsResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Customer domain","example":"mycompany.com"},"mentionRate":{"type":"number","description":"Mention rate as percentage (mentions / total queries * 100)","example":66.7},"avgRank":{"type":"object","description":"Average rank across all providers and prompts (lower is better)","example":2.5,"nullable":true},"mentionCount":{"type":"number","description":"Total number of mentions across all queries","example":6},"aiScore":{"type":"number","description":"AI Visibility Score — weighted 0-100 composite score","example":73},"perProvider":{"description":"Per-provider breakdown","allOf":[{"$ref":"#/components/schemas/AiVisibilityPerProviderResponse"}]}},"required":["domain","mentionRate","mentionCount","aiScore","perProvider"]},"AiVisibilityTopCompetitorResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Top competitor domain","example":"competitor.com"},"name":{"type":"string","description":"Top competitor brand name","example":"Competitor Inc"},"mentionRate":{"type":"number","description":"Top competitor mention rate percentage","example":88.9},"avgRank":{"type":"object","description":"Top competitor average rank (lower is better)","example":1.8,"nullable":true}},"required":["domain","name","mentionRate"]},"AiVisibilityCompetitorRankingResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Competitor domain","example":"competitor.com"},"name":{"type":"string","description":"Competitor brand name","example":"Competitor Inc"},"isOwn":{"type":"boolean","description":"Whether this is the customer own domain","example":false},"openaiAvgRank":{"type":"object","description":"Average rank in OpenAI responses (lower is better)","example":2,"nullable":true},"claudeAvgRank":{"type":"object","description":"Average rank in Claude responses (lower is better)","example":1.7,"nullable":true},"geminiAvgRank":{"type":"object","description":"Average rank in Gemini responses (lower is better)","example":3,"nullable":true},"overallAvgRank":{"type":"object","description":"Overall average rank across all providers (lower is better)","example":2.2,"nullable":true},"mentionCount":{"type":"number","description":"Total mentions across all queries","example":7},"mentionRate":{"type":"number","description":"Mention rate as percentage","example":77.8},"aiScore":{"type":"number","description":"AI Visibility Score (0-100)","example":68}},"required":["domain","name","isOwn","mentionCount","mentionRate","aiScore"]},"AiVisibilityDashboardSummaryResponse":{"type":"object","properties":{"customer":{"description":"Customer metrics","allOf":[{"$ref":"#/components/schemas/AiVisibilityCustomerMetricsResponse"}]},"topCompetitor":{"description":"Top competitor by mention rate","nullable":true,"allOf":[{"$ref":"#/components/schemas/AiVisibilityTopCompetitorResponse"}]},"mentionRateGap":{"type":"number","description":"Gap between customer and top competitor mention rate (negative means customer is behind)","example":-22.2},"totalCompetitorsFound":{"type":"number","description":"Total unique competitors found across AI responses","example":8},"totalQueries":{"type":"number","description":"Total queries executed (3 prompts x 3 providers = 9)","example":9},"totalEntries":{"type":"number","description":"Total brand entries across all query results","example":45},"competitorRankings":{"description":"Per-competitor ranking data","type":"array","items":{"$ref":"#/components/schemas/AiVisibilityCompetitorRankingResponse"}}},"required":["customer","mentionRateGap","totalCompetitorsFound","totalQueries","totalEntries","competitorRankings"]},"AiVisibilityDashboardResponse":{"type":"object","properties":{"lastUpdatedAt":{"type":"string","description":"When this data was last updated (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Summary statistics","allOf":[{"$ref":"#/components/schemas/AiVisibilityDashboardSummaryResponse"}]}},"required":["lastUpdatedAt","summary"]},"AiVisibilityHistoryItemResponse":{"type":"object","properties":{"checkId":{"type":"string","description":"Check ID","example":"507f1f77bcf86cd799439011"},"completedAt":{"type":"string","description":"When this check completed (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Check summary statistics","allOf":[{"$ref":"#/components/schemas/AiVisibilityDashboardSummaryResponse"}]}},"required":["checkId","completedAt","summary"]},"AiVisibilityCheckDetailResponse":{"type":"object","properties":{"checkId":{"type":"string","description":"Check ID","example":"507f1f77bcf86cd799439011"},"completedAt":{"type":"string","description":"When this check completed (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"summary":{"description":"Check summary statistics","allOf":[{"$ref":"#/components/schemas/AiVisibilityDashboardSummaryResponse"}]},"competitors":{"description":"Per-competitor AI visibility rankings for this check","type":"array","items":{"$ref":"#/components/schemas/AiVisibilityCompetitorRankingResponse"}}},"required":["checkId","completedAt","summary","competitors"]},"AiVisibilityTrendDataPointResponse":{"type":"object","properties":{"date":{"type":"string","description":"Data point date (ISO-8601)","example":"2026-03-15T10:00:00.000Z"},"customerMentionRate":{"type":"number","description":"Customer mention rate percentage (0-100)","example":66.7},"topCompetitorMentionRate":{"type":"number","description":"Top competitor mention rate percentage (0-100)","example":88.9},"topCompetitorDomain":{"type":"object","description":"Top competitor domain at this data point","example":"competitor.com","nullable":true},"gap":{"type":"number","description":"Gap between customer and top competitor (negative means customer is behind)","example":-22.2},"customerAiScore":{"type":"object","description":"Customer AI Visibility Score (0-100). A single weighted composite across all providers — null when a provider filter is applied, since no per-provider score exists.","example":73,"nullable":true},"topCompetitorAiScore":{"type":"object","description":"Top competitor AI Visibility Score (0-100). A single weighted composite across all providers — null when a provider filter is applied, since no per-provider score exists.","example":85,"nullable":true}},"required":["date","customerMentionRate","topCompetitorMentionRate","gap"]},"AiProvider":{"type":"string","enum":["openai","claude","gemini"]},"AlertListItemResponse":{"type":"object","properties":{"id":{"type":"string","description":"Alert ID","example":"507f1f77bcf86cd799439011"},"dimension":{"type":"string","description":"Monitoring dimension that generated this alert","enum":["tech-trust","content","positioning","pricing","ai-visibility"],"example":"pricing"},"competitorDomain":{"type":"string","description":"Competitor domain","example":"competitor.com"},"competitorId":{"type":"string","description":"Competitor ID","example":"507f1f77bcf86cd799439012"},"severity":{"type":"string","description":"Alert severity level","enum":["critical","high","medium","info"],"example":"high"},"title":{"type":"string","description":"Alert title describing the detected change","example":"Pricing plan restructure detected"},"actionHint":{"type":"string","description":"Suggested action for the user","example":"Review your pricing strategy to stay competitive"},"gapWarnings":{"description":"Specific competitive gap warnings","example":["Missing free tier","No annual billing discount"],"type":"array","items":{"type":"string"}},"runId":{"type":"string","description":"ID of the monitoring run that generated this alert. Use with the dimension's history endpoint (e.g., GET /v1/projects/{projectId}/pricing/history/{runId}) to retrieve the full data from that monitoring cycle.","example":"507f1f77bcf86cd799439013"},"alertType":{"type":"string","description":"Alert sub-type classifier. Values vary by dimension — e.g., price_change, plan_restructure, feature_toggle (pricing), messaging_shift, positioning_change (positioning), content_growth, content_removal (content), tech_stack_evolution, crawl_strategy (tech-trust), score_shift, provider_change (ai-visibility).","example":"price_change"},"context":{"type":"object","description":"Dimension-specific context data with details about the detected change. Structure varies by alertType — typically includes field-level changes with previousValue/currentValue pairs."},"createdAt":{"type":"string","description":"When the alert was created (ISO-8601)","example":"2026-03-15T10:00:00.000Z"}},"required":["id","dimension","competitorDomain","competitorId","severity","title","actionHint","gapWarnings","runId","createdAt"]},"ScheduleItemResponse":{"type":"object","properties":{"id":{"type":"string","description":"Schedule ID","example":"507f1f77bcf86cd799439011"},"dimension":{"type":"string","description":"Monitoring dimension","example":"tech-trust","enum":["tech-trust","content","positioning","pricing","ai-visibility"]},"enabled":{"type":"boolean","description":"Whether scheduled monitoring is enabled","example":true},"intervalDays":{"type":"number","description":"Monitoring interval in days","example":14},"nextRunAt":{"type":"string","description":"Next scheduled run time (ISO-8601)","example":"2026-03-29T10:00:00.000Z"},"lastRunAt":{"type":"object","description":"Last completed run time (ISO-8601)","example":"2026-03-15T10:00:00.000Z","nullable":true}},"required":["id","dimension","enabled","intervalDays","nextRunAt","lastRunAt"]},"BriefingMetaResponse":{"type":"object","properties":{"runId":{"type":"object","description":"Edition id (the briefing run id). Null when no finished briefing exists.","example":"6a3950c06bda450a1372048e","nullable":true},"briefingDate":{"type":"object","description":"When this edition finished, ISO-8601. Null when no finished briefing exists. Briefings refresh roughly every 30 days.","example":"2026-06-22T15:51:24.443Z","nullable":true},"availability":{"type":"string","description":"Availability of the briefing for this project: `ready` (a finished briefing is returned), `ready-refreshing` (a finished briefing is returned AND a newer edition is being generated right now), `preparing` (the first edition is still being generated — body is null), `none` (no briefing exists yet).","enum":["ready","ready-refreshing","preparing","none"],"example":"ready"}},"required":["availability"]},"BriefingEnvelopeResponse":{"type":"object","properties":{"item":{"type":"object","description":"The requested briefing sections (any of: hub, competitors, actions, deep-<dimension>). Null when no finished briefing exists (see meta.availability).","nullable":true},"meta":{"description":"Edition metadata + availability.","allOf":[{"$ref":"#/components/schemas/BriefingMetaResponse"}]},"coverage":{"type":"object","description":"Methodology and honest-degradation caveats for this edition (e.g. which figures are directional, what counts as noise). Always returned regardless of requested sections — read before quoting any number. Null when no finished briefing exists.","nullable":true},"dimensionHealth":{"type":"object","description":"Per-dimension presence — which deep-<dimension> analyses this edition contains (present | absent). A skipped dimension reads as `absent`, never as an empty finding.","example":{"deep-ai-visibility":"present","deep-pricing":"absent"}}},"required":["meta","dimensionHealth"]},"TechStackEvidenceResponse":{"type":"object","properties":{"kind":{"type":"string","description":"Match source: 'header' = HTTP response header; 'html' = homepage body","enum":["header","html"],"example":"html"},"source":{"type":"string","description":"Human-readable source: header key name (e.g. 'x-vercel-id') or the regex pattern that fired","example":"/_next/static/"},"matched":{"type":"string","description":"The specific text that matched, newline-stripped and truncated for safety","example":"<script src=\"/_next/static/chunks/main-app-abc123.js\""}},"required":["kind","source","matched"]},"TechStackDetectedTechnologyResponse":{"type":"object","properties":{"name":{"type":"string","description":"Canonical technology name (enum value from TechStackTechnology / GrowthStackTechnology / EngagementStackTechnology)","example":"Next.js"},"evidenceCount":{"type":"number","description":"Count of independent matchers that fired for this technology","example":3},"evidence":{"description":"One entry per matcher that fired — lets consumers show 'why did this match?'","type":"array","items":{"$ref":"#/components/schemas/TechStackEvidenceResponse"}}},"required":["name","evidenceCount","evidence"]},"PartialDetectionResponse":{"type":"object","properties":{"headersAvailable":{"type":"boolean","description":"Always false for this discriminator.","example":false},"reason":{"type":"string","description":"Why headers were unavailable. HTML matcher detection (~85% of rules) still ran; header-dependent rules (~24 rules) are absent from the response.","enum":["site_uses_behavioral_protection"],"example":"site_uses_behavioral_protection"}},"required":["headersAvailable","reason"]},"TechStackToolResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Normalized domain, as actually requested (post-normalizeDomain)","example":"competlab.com"},"finalUrl":{"type":"string","description":"Final URL after redirects (from N8N response)","example":"https://competlab.com/"},"fetchedAt":{"type":"string","description":"ISO-8601 timestamp of when detection completed","example":"2026-05-16T14:30:00.000Z"},"totalTechnologies":{"type":"number","description":"Total count of detected technologies across all three stacks","example":12},"techStack":{"description":"TECH STACK category — hosting, CDN, frameworks, CMS, auth, payments, cookie consent","type":"array","items":{"$ref":"#/components/schemas/TechStackDetectedTechnologyResponse"}},"growthStack":{"description":"GROWTH STACK category — analytics, tag managers, session recording, marketing, CRM, advertising, A/B","type":"array","items":{"$ref":"#/components/schemas/TechStackDetectedTechnologyResponse"}},"engagementStack":{"description":"ENGAGEMENT STACK category — customer support, forms, video, monitoring","type":"array","items":{"$ref":"#/components/schemas/TechStackDetectedTechnologyResponse"}},"partialDetection":{"description":"Present ONLY when response headers couldn't be recovered (~1.1% of sites running behavioral protection that blocks header inspection). Detection from HTML matchers (~85% of rules) still ran and populates the three stack arrays; header-dependent tech (~24 rules) is absent. When present, missing tech should NOT be interpreted as 'site doesn't use it.'","allOf":[{"$ref":"#/components/schemas/PartialDetectionResponse"}]}},"required":["domain","finalUrl","fetchedAt","totalTechnologies","techStack","growthStack","engagementStack"]},"TechStackScanErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code","enum":["homepage_fetch_failed","scan_failed"],"example":"homepage_fetch_failed"},"message":{"type":"string","description":"Human-readable error message","example":"Homepage fetch failed"}},"required":["code","message"]},"TechStackScanResponse":{"type":"object","properties":{"id":{"type":"string","description":"Scan ID (24-char hex Mongo ObjectId). Use to poll GET /scans/:scanId.","example":"6638e9a1b2c3d4e5f6a7b8c9"},"status":{"type":"string","description":"Current lifecycle state. Poll until `completed` or `failed`.","enum":["queued","running","completed","failed"],"example":"queued"},"createdAt":{"type":"string","description":"ISO-8601 timestamp when the scan was created.","example":"2026-05-17T14:30:00.000Z"},"expiresAt":{"type":"string","description":"ISO-8601 timestamp when the doc auto-deletes (createdAt + 24h). After this, GET returns 404.","example":"2026-05-18T14:30:00.000Z"},"startedAt":{"type":"string","description":"ISO-8601 timestamp when the background runner began scanning. Set once status leaves `queued`.","example":"2026-05-17T14:30:00.412Z"},"completedAt":{"type":"string","description":"ISO-8601 timestamp when the scan reached a terminal state (completed or failed).","example":"2026-05-17T14:30:45.218Z"},"result":{"description":"Full scan result. Present only when `status === \"completed\"`. Same shape as the legacy sync `/v1/tools/tech-stack` response.","allOf":[{"$ref":"#/components/schemas/TechStackToolResponse"}]},"error":{"description":"Error details. Present only when `status === \"failed\"`.","allOf":[{"$ref":"#/components/schemas/TechStackScanErrorResponse"}]}},"required":["id","status","createdAt","expiresAt"]},"PTTechStackRequestDto":{"type":"object","properties":{}},"TrustSignalsVerdictResponse":{"type":"object","properties":{"tier":{"type":"string","description":"Tier verdict — describes homepage TRUST SIGNAL COVERAGE, not company market tier","enum":["comprehensive","substantial","moderate","minimal"],"example":"substantial"},"score":{"type":"number","description":"Total trust score (0-100, capped)","example":38},"benchmarkForTier":{"type":"number","description":"Tier mean score from CompetLab SaaS Trust Benchmarks","example":34},"benchmarkComparison":{"type":"string","description":"How this domain compares to peers at the same tier","enum":["above-average","at-average","below-average"],"example":"above-average"},"summary":{"type":"string","description":"One-line human-readable verdict","example":"Substantial trust coverage — strong social proof and some compliance signals, above-average for tier"}},"required":["tier","score","benchmarkForTier","benchmarkComparison","summary"]},"TrustSignalsCategoryScoreResponse":{"type":"object","properties":{"score":{"type":"number","description":"Points earned in this category (post-cap, post-weight)","example":18},"max":{"type":"number","description":"Maximum possible points in this category","example":25},"signalsFound":{"type":"number","description":"Count of distinct signals detected in this category","example":3}},"required":["score","max","signalsFound"]},"TrustSignalsCategoryScoresResponse":{"type":"object","properties":{"enterpriseReadiness":{"description":"Enterprise readiness — compliance, trust center, privacy posture","allOf":[{"$ref":"#/components/schemas/TrustSignalsCategoryScoreResponse"}]},"thirdPartyValidation":{"description":"Third-party validation — G2, Capterra, Trustpilot, Gartner, etc.","allOf":[{"$ref":"#/components/schemas/TrustSignalsCategoryScoreResponse"}]},"socialProof":{"description":"Social proof — customer logos, case studies, testimonials, count claims","allOf":[{"$ref":"#/components/schemas/TrustSignalsCategoryScoreResponse"}]},"brandAuthority":{"description":"Brand authority — press, awards, funding, partner badges","allOf":[{"$ref":"#/components/schemas/TrustSignalsCategoryScoreResponse"}]},"riskReversal":{"description":"Risk reversal — free trial, freemium, no-credit-card","allOf":[{"$ref":"#/components/schemas/TrustSignalsCategoryScoreResponse"}]}},"required":["enterpriseReadiness","thirdPartyValidation","socialProof","brandAuthority","riskReversal"]},"TrustSignalsEvidenceResponse":{"type":"object","properties":{"kind":{"type":"string","description":"Match source: 'header' = HTTP response header; 'html' = homepage body","enum":["header","html"],"example":"html"},"source":{"type":"string","description":"Human-readable source: header key name or the regex pattern that fired","example":"trustpilot.com"},"matched":{"type":"string","description":"The specific text that matched, newline-stripped and truncated for safety","example":"<a href=\"https://www.trustpilot.com/review/example.com\">"}},"required":["kind","source","matched"]},"TrustSignalsDetectedSignalResponse":{"type":"object","properties":{"signal":{"type":"string","description":"Canonical trust signal name (enum value from PTTrustSignal)","example":"SOC 2"},"category":{"type":"string","description":"Buyer-concern category this signal belongs to","enum":["enterpriseReadiness","thirdPartyValidation","socialProof","brandAuthority","riskReversal"],"example":"enterpriseReadiness"},"weight":{"type":"number","description":"Points this signal contributed to the total score (post-cap)","example":8},"confidence":{"type":"string","description":"Confidence band — reflects regex specificity, not business weight","enum":["high","medium","low"],"example":"high"},"evidenceCount":{"type":"number","description":"Count of independent matchers that fired for this signal","example":2},"evidence":{"description":"One entry per matcher that fired — lets consumers show 'why did this match?'","type":"array","items":{"$ref":"#/components/schemas/TrustSignalsEvidenceResponse"}},"extractedValue":{"type":"object","description":"Optional extracted value — e.g., customer count number, case study count","example":50000}},"required":["signal","category","weight","confidence","evidenceCount","evidence"]},"TrustSignalsSuspiciousPatternResponse":{"type":"object","properties":{"type":{"type":"string","description":"Type of asymmetry detected on the page","enum":["unverified-compliance-claim","count-vs-logo-mismatch","unlinked-press-claim","stale-review-widget"],"example":"unverified-compliance-claim"},"severity":{"type":"string","description":"Severity of the discrepancy","enum":["low","medium","high"],"example":"high"},"description":{"type":"string","description":"Human-readable description of the pattern","example":"SOC 2 text found on homepage but no link to attestation or trust center"},"ciInsight":{"type":"string","description":"Short actionable competitive intelligence insight — under 25 words","example":"Likely SOC 2 claim without proof — competitive opportunity if you have attestation linked"},"evidence":{"description":"Evidence supporting the pattern detection","type":"array","items":{"$ref":"#/components/schemas/TrustSignalsEvidenceResponse"}}},"required":["type","severity","description","ciInsight","evidence"]},"TrustSignalsGapResponse":{"type":"object","properties":{"signal":{"type":"string","description":"Canonical trust signal name that is missing","example":"Customer logos"},"category":{"type":"string","description":"Buyer-concern category this gap belongs to","enum":["enterpriseReadiness","thirdPartyValidation","socialProof","brandAuthority","riskReversal"],"example":"socialProof"},"benchmarkPrevalence":{"type":"string","description":"Human-readable prevalence among peers at the same tier","example":"87% of substantial-tier peers have this"},"ciInsight":{"type":"string","description":"Short actionable insight on closing the gap","example":"Add customer logos to homepage — table stakes for substantial-tier SaaS positioning"}},"required":["signal","category","benchmarkPrevalence","ciInsight"]},"TrustSignalsMetaResponse":{"type":"object","properties":{"signalsEvaluated":{"type":"number","description":"Total number of canonical trust signals the detector evaluates","example":38},"benchmarkSource":{"type":"string","description":"Benchmark dataset identifier — quarter and sample size","example":"CompetLab SaaS Trust Benchmarks 2026-Q2 (n=247)"},"scanDurationMs":{"type":"number","description":"Total scan duration in milliseconds","example":2840}},"required":["signalsEvaluated","benchmarkSource","scanDurationMs"]},"TrustSignalsToolResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Normalized domain, as actually requested (post-normalizeDomain)","example":"competlab.com"},"finalUrl":{"type":"string","description":"Final URL after redirects (from N8N response)","example":"https://competlab.com/"},"fetchedAt":{"type":"string","description":"ISO-8601 timestamp of when detection completed","example":"2026-05-16T14:30:00.000Z"},"signalsAvailable":{"description":"Honest-degradation discriminator. Present ONLY when the upstream fetch couldn't recover response headers (~1.1% of sites running behavioral protection that blocks header inspection). When present, ALL OTHER FIELDS IN THIS RESPONSE — `verdict`, `categoryScores`, `signalsDetected`, `suspiciousPatterns`, `gapsVsBenchmark` — are PLACEHOLDER values, NOT a 'zero trust signals' result. Headers from the site couldn't be inspected; trust-signal evaluation depends on them. Absent on healthy scans (the normal path).","allOf":[{"$ref":"#/components/schemas/SignalsAvailableUnavailableResponse"}]},"verdict":{"description":"Overall verdict — tier, score, benchmark comparison, human-readable summary. ⚠️ When `signalsAvailable.available === false`, these fields are PLACEHOLDER values (tier: 'minimal', score: 0) and MUST NOT be used for tier-distribution analytics or competitive ranking. Consumers MUST check `signalsAvailable` first.","allOf":[{"$ref":"#/components/schemas/TrustSignalsVerdictResponse"}]},"categoryScores":{"description":"Per-category breakdown — score, max, and signals found in each of the 5 categories","allOf":[{"$ref":"#/components/schemas/TrustSignalsCategoryScoresResponse"}]},"signalsDetected":{"description":"All trust signals detected on the homepage, with evidence","type":"array","items":{"$ref":"#/components/schemas/TrustSignalsDetectedSignalResponse"}},"suspiciousPatterns":{"description":"Asymmetry detection — claims without proof, count/logo mismatches, unlinked press, etc.","type":"array","items":{"$ref":"#/components/schemas/TrustSignalsSuspiciousPatternResponse"}},"gapsVsBenchmark":{"description":"Missing signals relative to tier benchmark — drives competitive insights","type":"array","items":{"$ref":"#/components/schemas/TrustSignalsGapResponse"}},"meta":{"description":"Scan metadata — signals evaluated, benchmark source, scan duration","allOf":[{"$ref":"#/components/schemas/TrustSignalsMetaResponse"}]}},"required":["domain","finalUrl","fetchedAt","verdict","categoryScores","signalsDetected","suspiciousPatterns","gapsVsBenchmark","meta"]},"TrustSignalsScanErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code","enum":["homepage_fetch_failed","scan_failed"],"example":"homepage_fetch_failed"},"message":{"type":"string","description":"Human-readable error message","example":"Homepage fetch failed"}},"required":["code","message"]},"TrustSignalsScanResponse":{"type":"object","properties":{"id":{"type":"string","description":"Scan ID (24-char hex Mongo ObjectId). Use to poll GET /scans/:scanId.","example":"6638e9a1b2c3d4e5f6a7b8c9"},"status":{"type":"string","description":"Current lifecycle state. Poll until `completed` or `failed`.","enum":["queued","running","completed","failed"],"example":"queued"},"createdAt":{"type":"string","description":"ISO-8601 timestamp when the scan was created.","example":"2026-05-17T14:30:00.000Z"},"expiresAt":{"type":"string","description":"ISO-8601 timestamp when the doc auto-deletes (createdAt + 24h). After this, GET returns 404.","example":"2026-05-18T14:30:00.000Z"},"startedAt":{"type":"string","description":"ISO-8601 timestamp when the background runner began scanning. Set once status leaves `queued`.","example":"2026-05-17T14:30:00.412Z"},"completedAt":{"type":"string","description":"ISO-8601 timestamp when the scan reached a terminal state (completed or failed).","example":"2026-05-17T14:30:45.218Z"},"result":{"description":"Full scan result. Present only when `status === \"completed\"`. Same shape as the legacy sync `/v1/tools/trust-signals` response.","allOf":[{"$ref":"#/components/schemas/TrustSignalsToolResponse"}]},"error":{"description":"Error details. Present only when `status === \"failed\"`.","allOf":[{"$ref":"#/components/schemas/TrustSignalsScanErrorResponse"}]}},"required":["id","status","createdAt","expiresAt"]},"PTTrustSignalsRequestDto":{"type":"object","properties":{}},"AiCrawlerCheckerCrawlerResultResponse":{"type":"object","properties":{"userAgent":{"type":"string","description":"Robots.txt user-agent token for this crawler","example":"GPTBot"},"displayName":{"type":"string","description":"Human-readable display name","example":"GPTBot"},"operator":{"type":"string","description":"Operating organization","example":"OpenAI"},"category":{"type":"string","description":"Crawler purpose category","enum":["training","retrieval","hybrid"],"example":"training"},"status":{"type":"string","description":"Per-crawler access status derived from robots.txt rules","enum":["allowed","blocked","conditional"],"example":"blocked"},"matchingDirective":{"type":"object","description":"Raw robots.txt line that triggered the status, or null if no directive matched","example":"Disallow: /","nullable":true}},"required":["userAgent","displayName","operator","category","status","matchingDirective"]},"AiCrawlerCheckerRobotsTxtResponse":{"type":"object","properties":{"found":{"type":"boolean","description":"Whether the robots.txt file was successfully fetched","example":true},"content":{"type":"string","description":"Raw text content of the robots.txt file when fetched successfully","example":"User-agent: GPTBot\nDisallow: /\n\nUser-agent: *\nAllow: /\n"},"statusCode":{"type":"number","description":"HTTP status code of the robots.txt fetch","example":200}},"required":["found"]},"AiCrawlerCheckerMetaTagResultResponse":{"type":"object","properties":{"name":{"type":"string","description":"Meta tag name (currently always 'robots')","example":"robots"},"content":{"type":"string","description":"Directive value, e.g. 'noai', 'noimageai', 'noml', 'noimageml'","example":"noai, noimageai"}},"required":["name","content"]},"AiCrawlerCheckerHeadersResponse":{"type":"object","properties":{"xRobotsTag":{"type":"string","description":"Value of the X-Robots-Tag header from the homepage response","example":"noai, noimageai"}}},"AiCrawlerCheckerLlmsTxtResultResponse":{"type":"object","properties":{"found":{"type":"boolean","description":"Whether the file was found at /llms.txt or /llms-full.txt","example":true},"sectionCount":{"type":"number","description":"Count of markdown section headers (`# foo` lines)","example":12},"linkCount":{"type":"number","description":"Count of markdown inline links `[text](url)`","example":47},"approxTokens":{"type":"number","description":"Rough token estimate (chars / 4, ceil)","example":1850}},"required":["found"]},"AiCrawlerCheckerAccessibilityResponse":{"type":"object","properties":{"score":{"type":"number","description":"0-100 weighted composite accessibility score","example":65},"label":{"type":"string","description":"Coarse-grained accessibility label","enum":["Fully Open","Mostly Open","Mixed Access","Mostly Blocked"],"example":"Mixed Access"},"interpretation":{"type":"string","description":"Human-readable interpretation of the score","example":"Selective access — training bots blocked, retrieval bots allowed. Common pattern for content-led brands protecting IP while staying answer-engine visible."},"color":{"type":"string","description":"UI hint color for the score","enum":["teal","blue","orange","red"],"example":"orange"}},"required":["score","label","interpretation","color"]},"AiCrawlerCheckerStrategyResponse":{"type":"object","properties":{"type":{"type":"string","description":"Stable machine-readable strategy type","enum":["block-nothing","block-training-allow-retrieval","block-everything","block-retrieval-allow-training","mixed"],"example":"block-training-allow-retrieval"},"label":{"type":"string","description":"Human-readable strategy label","example":"Block training, allow retrieval"},"description":{"type":"string","description":"Description of the detected strategy","example":"You're blocking AI model training crawlers (GPTBot, ClaudeBot) while allowing retrieval bots (ChatGPT-User, PerplexityBot). Protects IP, maintains answer-engine visibility."}},"required":["type","label","description"]},"AiCrawlerCheckerIndustryPositionResponse":{"type":"object","properties":{"industryLabel":{"type":"string","description":"Human-readable industry label","example":"SaaS / Tech"},"industryAvgBlockRate":{"type":"number","description":"Average percentage of sites in this industry blocking at least one AI bot","example":42},"typicalScoreRange":{"description":"Typical accessibility score range for this industry [min, max]","example":[55,80],"type":"array","items":{"type":"number"}},"position":{"type":"string","description":"Where this domain sits relative to the typical score range","enum":["below-average","average","above-average"],"example":"average"},"insight":{"type":"string","description":"Human-readable sentence explaining the position in industry context","example":"Your access score of 65 sits in the typical SaaS / Tech range (55–80). 42% of peers block at least one AI bot."}},"required":["industryLabel","industryAvgBlockRate","typicalScoreRange","position","insight"]},"AiCrawlerCheckerRecommendationResponse":{"type":"object","properties":{"id":{"type":"string","description":"Stable machine-readable id (e.g. 'ip-protection', 'visibility-risk')","example":"ip-protection"},"title":{"type":"string","description":"Short recommendation title","example":"Add llms.txt for retrieval-bot context"},"description":{"type":"string","description":"Recommendation detail","example":"ChatGPT-User and PerplexityBot can fetch your homepage but lack a curated context file. Add /llms.txt with key pages and definitions to improve citation quality."},"priority":{"type":"string","description":"Priority for the recommendation","enum":["high","medium","low"],"example":"medium"}},"required":["id","title","description","priority"]},"AiCrawlerCheckerToolResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Normalized domain, as actually analyzed (post-normalizeDomain)","example":"competlab.com"},"fetchedAt":{"type":"string","description":"ISO-8601 timestamp of when the scan completed","example":"2026-05-16T14:30:00.000Z"},"industry":{"type":"string","description":"Industry echoed back — defaults to 'other' if caller didn't supply one","enum":["news-media","arts-entertainment","law-government","finance-healthcare","saas-tech","ecommerce","other"],"example":"saas-tech"},"crawlers":{"description":"All 21 catalog entries with derived per-crawler status","type":"array","items":{"$ref":"#/components/schemas/AiCrawlerCheckerCrawlerResultResponse"}},"robotsTxt":{"description":"robots.txt fetch result","allOf":[{"$ref":"#/components/schemas/AiCrawlerCheckerRobotsTxtResponse"}]},"metaTags":{"description":"AI-related meta robots directives captured from the homepage","type":"array","items":{"$ref":"#/components/schemas/AiCrawlerCheckerMetaTagResultResponse"}},"headers":{"description":"Values captured from homepage response headers","allOf":[{"$ref":"#/components/schemas/AiCrawlerCheckerHeadersResponse"}]},"llmsTxt":{"description":"/llms.txt stats (AI search file spec)","allOf":[{"$ref":"#/components/schemas/AiCrawlerCheckerLlmsTxtResultResponse"}]},"llmsFullTxt":{"description":"/llms-full.txt stats (AI search file spec)","allOf":[{"$ref":"#/components/schemas/AiCrawlerCheckerLlmsTxtResultResponse"}]},"accessibility":{"description":"Accessibility verdict — score + label + interpretation","allOf":[{"$ref":"#/components/schemas/AiCrawlerCheckerAccessibilityResponse"}]},"strategy":{"description":"Detected strategy — opt-in/opt-out pattern across crawler categories","allOf":[{"$ref":"#/components/schemas/AiCrawlerCheckerStrategyResponse"}]},"industryPosition":{"description":"Industry-context positioning — benchmark percentile and insight","allOf":[{"$ref":"#/components/schemas/AiCrawlerCheckerIndustryPositionResponse"}]},"recommendations":{"description":"Prioritized recommendations for closing gaps","type":"array","items":{"$ref":"#/components/schemas/AiCrawlerCheckerRecommendationResponse"}},"robotsSnippet":{"type":"string","description":"Ready-to-paste robots.txt patch for the detected blocked crawlers","example":"User-agent: GPTBot\nDisallow: /\n\nUser-agent: ClaudeBot\nDisallow: /\n"}},"required":["domain","fetchedAt","industry","crawlers","robotsTxt","metaTags","headers","llmsTxt","llmsFullTxt","accessibility","strategy","industryPosition","recommendations","robotsSnippet"]},"PTAiCrawlerCheckerRequestDto":{"type":"object","properties":{}},"SitemapVisualizerSitemapInfoResponse":{"type":"object","properties":{"url":{"type":"string","description":"Absolute URL of the fetched sitemap resource","example":"https://competlab.com/sitemap.xml"},"type":{"type":"string","description":"Sitemap resource shape","enum":["index","urlset"],"example":"urlset"},"urlCount":{"type":"number","description":"Count of URLs collected from this sitemap (post 10k-cap)","example":247},"actualUrlCount":{"type":"number","description":"Count of URLs this sitemap actually declared (pre 10k-cap)","example":247}},"required":["url","type","urlCount","actualUrlCount"]},"SitemapVisualizerMetricsResponse":{"type":"object","properties":{"totalUrls":{"type":"number","description":"Count of URLs analyzed (post 10k-cap)","example":247},"totalActualUrls":{"type":"number","description":"True upstream URL count before the 10k cap","example":247},"totalSitemaps":{"type":"number","description":"Number of sitemap resources fetched","example":3},"categoriesFound":{"type":"number","description":"Number of distinct content categories with at least one URL","example":6},"maxDepth":{"type":"number","description":"Maximum path depth observed","example":4},"avgDepth":{"type":"object","description":"Average pathname depth across all URLs. Null when urls[] is empty.","nullable":true,"example":2.6}},"required":["totalUrls","totalActualUrls","totalSitemaps","categoriesFound","maxDepth","avgDepth"]},"SitemapVisualizerCategorizedUrlResponse":{"type":"object","properties":{"url":{"type":"string","description":"Absolute URL of the page","example":"https://competlab.com/blog/competitive-intelligence-guide"},"category":{"type":"string","description":"Content-category classification (forked taxonomy, kebab-case)","enum":["blog","docs","tools","landing","legal","case-studies","comparison","integrations","changelog","webinars","careers","other"],"example":"blog"},"depth":{"type":"number","description":"Path depth — segment count of URL.pathname after filtering empty parts","example":2},"lastmod":{"type":"object","description":"Value of <lastmod> from the source XML if present, else null","nullable":true,"example":"2026-04-12"}},"required":["url","category","depth","lastmod"]},"SitemapVisualizerCategoryBreakdownResponse":{"type":"object","properties":{"count":{"type":"number","description":"Number of URLs in this category","example":47},"percentage":{"type":"number","description":"Percentage of total URLs (0-100, one decimal place)","example":18.4}},"required":["count","percentage"]},"SitemapVisualizerCategoriesResponse":{"type":"object","properties":{"blog":{"description":"Blog posts and editorial content","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerCategoryBreakdownResponse"}]},"docs":{"description":"Product documentation","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerCategoryBreakdownResponse"}]},"tools":{"description":"Free tools and utilities","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerCategoryBreakdownResponse"}]},"landing":{"description":"Landing / marketing pages","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerCategoryBreakdownResponse"}]},"legal":{"description":"Legal pages — privacy, terms, DPA, etc.","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerCategoryBreakdownResponse"}]},"case-studies":{"description":"Customer case studies","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerCategoryBreakdownResponse"}]},"comparison":{"description":"Comparison pages (X vs Y)","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerCategoryBreakdownResponse"}]},"integrations":{"description":"Integration pages","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerCategoryBreakdownResponse"}]},"changelog":{"description":"Changelog / release notes","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerCategoryBreakdownResponse"}]},"webinars":{"description":"Webinars and events","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerCategoryBreakdownResponse"}]},"careers":{"description":"Careers / hiring pages","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerCategoryBreakdownResponse"}]},"other":{"description":"Uncategorized pages","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerCategoryBreakdownResponse"}]}},"required":["blog","docs","tools","landing","legal","case-studies","comparison","integrations","changelog","webinars","careers","other"]},"SitemapVisualizerValidationCheckResponse":{"type":"object","properties":{"passed":{"type":"boolean","description":"Whether the validation check passed","example":true},"message":{"type":"string","description":"Human-readable reason","example":"Found valid sitemap at /sitemap.xml"}},"required":["passed","message"]},"SitemapVisualizerValidationResultResponse":{"type":"object","properties":{"sitemapFound":{"description":"Whether a sitemap was discovered (via /sitemap.xml, robots.txt, or provided URL)","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerValidationCheckResponse"}]},"validXml":{"description":"Whether the discovered XML parsed successfully","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerValidationCheckResponse"}]},"nonEmpty":{"description":"Whether the sitemap contained at least one URL","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerValidationCheckResponse"}]},"validIndex":{"description":"Whether sitemap index referenced valid child sitemaps (if applicable)","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerValidationCheckResponse"}]}},"required":["sitemapFound","validXml","nonEmpty","validIndex"]},"SitemapVisualizerFreshnessBucketsResponse":{"type":"object","properties":{"fresh":{"type":"number","description":"URLs last modified within the last 3 months (0-90 days)","example":32},"recent":{"type":"number","description":"URLs last modified 3-6 months ago (90-180 days)","example":18},"aging":{"type":"number","description":"URLs last modified 6-12 months ago (180-360 days)","example":41},"stale":{"type":"number","description":"URLs last modified more than a year ago (>360 days)","example":122},"noDate":{"type":"number","description":"URLs missing the <lastmod> tag","example":34}},"required":["fresh","recent","aging","stale","noDate"]},"SitemapVisualizerDepthDistributionResponse":{"type":"object","properties":{"0":{"type":"number","description":"URLs at path depth 0 (home pages)","example":1},"1":{"type":"number","description":"URLs at path depth 1","example":24},"2":{"type":"number","description":"URLs at path depth 2","example":87},"3":{"type":"number","description":"URLs at path depth 3","example":92},"4+":{"type":"number","description":"URLs at path depth 4 or deeper","example":43}},"required":["0","1","2","3","4+"]},"SitemapVisualizerInsightsResponse":{"type":"object","properties":{"freshness":{"description":"Bucketization of URLs by content freshness","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerFreshnessBucketsResponse"}]},"depthDistribution":{"description":"URL count grouped by path depth (0 = home, '4+' = 4+ segments)","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerDepthDistributionResponse"}]},"stalePageCount":{"type":"object","description":"Count of URLs older than ~6 months (180 days). Null when no <lastmod> data is present at all.","nullable":true,"example":163},"sampleUrlsByCategory":{"type":"object","description":"Up to N sample URLs per populated category, largest categories first. Keys are content categories; absent keys mean the category had zero URLs.","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"blog":["https://competlab.com/blog/competitive-intelligence-guide","https://competlab.com/blog/ai-visibility-tracking"],"docs":["https://competlab.com/docs/getting-started"],"case-studies":["https://competlab.com/case-studies/acme"]}},"summary":{"type":"string","description":"Deterministic, rule-based interpretation string (1-3 sentences)","example":"247 URLs across 6 content categories. Blog dominates at 18% with fresh content (32 URLs in the last 3 months). 163 pages are stale (>6 months), concentrated in the docs and legal categories — possible refresh opportunity."}},"required":["freshness","depthDistribution","stalePageCount","sampleUrlsByCategory","summary"]},"SitemapVisualizerToolResponse":{"type":"object","properties":{"domain":{"type":"string","description":"Normalized domain, as actually analyzed (post-normalizeDomain)","example":"competlab.com"},"fetchedAt":{"type":"string","description":"ISO-8601 timestamp of scan completion","example":"2026-05-16T14:30:00.000Z"},"status":{"type":"string","description":"Coarse status — 'ok'/'partial' for success, 'not-found'/'access-denied'/'invalid' as first-class envelope states","enum":["ok","partial","not-found","access-denied","invalid"],"example":"ok"},"source":{"type":"string","description":"How the sitemap was discovered","enum":["sitemap-xml","robots-txt","provided","none"],"example":"sitemap-xml"},"sitemaps":{"description":"All sitemap resources fetched or attempted","type":"array","items":{"$ref":"#/components/schemas/SitemapVisualizerSitemapInfoResponse"}},"truncated":{"type":"boolean","description":"True if the URL list was capped at 10,000 or child-sitemap fan-out hit the 20-child cap","example":false},"accessDenied":{"type":"boolean","description":"True if the root sitemap returned 401/403","example":false},"metrics":{"description":"Quantitative metrics — URL counts, sitemap count, category count, depth stats","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerMetricsResponse"}]},"urls":{"description":"Raw categorized URLs. Present only when request had includeUrls: true. Capped at 10,000; check `truncated` flag.","type":"array","items":{"$ref":"#/components/schemas/SitemapVisualizerCategorizedUrlResponse"}},"categories":{"description":"Per-category breakdown. Every category key is populated (count may be 0).","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerCategoriesResponse"}]},"validation":{"description":"Quality checks for sitemap discovery and parsing","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerValidationResultResponse"}]},"insights":{"description":"AI-consumable insight layer — freshness, depth distribution, stale-page count, category samples, summary","allOf":[{"$ref":"#/components/schemas/SitemapVisualizerInsightsResponse"}]}},"required":["domain","fetchedAt","status","source","sitemaps","truncated","accessDenied","metrics","categories","validation","insights"]},"PTSitemapVisualizerRequestDto":{"type":"object","properties":{}},"AgentAdoptionScannerResponse":{"type":"object","properties":{"name":{"type":"string","description":"Scanner brand string (constant per implementation)","example":"CompetLab Agent-Adoption Scanner"},"version":{"type":"string","description":"Semver-ish version tag of the scanner emitting this response","example":"0.8.0"}},"required":["name","version"]},"AgentAdoptionNextLevelResponse":{"type":"object","properties":{"level":{"type":"number","description":"Target level number","example":2},"levelName":{"type":"string","description":"Target level name","example":"AI-Aware"},"requirements":{"type":"array","description":"Checks that must pass to advance (AND semantics)","example":["content-signals"],"items":{"type":"string","enum":["robots-txt-exists","sitemap-exists","link-headers","ai-bot-rules","content-signals","web-bot-auth","robots-allow-all","llms-txt-exists","llms-txt-valid","llms-txt-size","llms-txt-has-optional-section","markdown-url-support","markdown-negotiation","rendering-strategy","page-size-html","http-status-codes","redirect-behavior","agents-md-detection","cache-header-hygiene","api-catalog","oauth-discovery","oauth-protected-resource","mcp-server-card","a2a-agent-card","agent-skills"]}}},"required":["level","levelName","requirements"]},"AgentAdoptionFixPromptResponse":{"type":"object","properties":{"full":{"type":"string","description":"Full paste-to-Claude-Code/Cursor remediation markdown","example":"# Fix: Add llms.txt\n\nCreate a `/llms.txt` file at your site root..."}},"required":["full"]},"AgentAdoptionEvidenceRequestResponse":{"type":"object","properties":{"url":{"type":"string","description":"Request URL","example":"https://competlab.com/robots.txt"},"method":{"type":"string","description":"HTTP method","example":"GET"},"headers":{"type":"object","description":"Sanitized request headers (auth/session headers stripped)","example":{"user-agent":"CompetLab-AgentAdoptionScanner/0.8.0"},"additionalProperties":{"type":"string"}}},"required":["url","method"]},"AgentAdoptionEvidenceResponsePayload":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":200},"statusText":{"type":"string","description":"HTTP status text","example":"OK"},"headers":{"type":"object","description":"Sanitized response headers (auth/session headers stripped)","example":{"content-type":"text/plain","cache-control":"max-age=3600"},"additionalProperties":{"type":"string"}},"bodyPreview":{"type":"string","description":"Truncated body preview for the response","example":"User-agent: *\nAllow: /\n\nSitemap: https://competlab.com/sitemap.xml"}},"required":["status","statusText"]},"AgentAdoptionEvidenceFindingResponse":{"type":"object","properties":{"outcome":{"type":"string","description":"Outcome of the trace step","enum":["positive","negative","neutral"],"example":"positive"},"summary":{"type":"string","description":"Short summary of the finding","example":"robots.txt found with valid user-agent declarations"}},"required":["outcome","summary"]},"AgentAdoptionEvidenceResponse":{"type":"object","properties":{"action":{"type":"string","description":"Trace action kind","enum":["fetch","parse","conclude"],"example":"fetch"},"label":{"type":"string","description":"Human-readable label for this trace step","example":"Fetch robots.txt"},"request":{"description":"Request details (only for fetch actions)","allOf":[{"$ref":"#/components/schemas/AgentAdoptionEvidenceRequestResponse"}]},"response":{"description":"Response details (only for fetch actions)","allOf":[{"$ref":"#/components/schemas/AgentAdoptionEvidenceResponsePayload"}]},"finding":{"description":"Finding summary (only for parse/conclude actions)","allOf":[{"$ref":"#/components/schemas/AgentAdoptionEvidenceFindingResponse"}]}},"required":["action","label"]},"AgentAdoptionCheckResponse":{"type":"object","properties":{"id":{"type":"string","description":"Check identifier, kebab-case (matches 25-check v1 scorecard)","enum":["robots-txt-exists","sitemap-exists","link-headers","ai-bot-rules","content-signals","web-bot-auth","robots-allow-all","llms-txt-exists","llms-txt-valid","llms-txt-size","llms-txt-has-optional-section","markdown-url-support","markdown-negotiation","rendering-strategy","page-size-html","http-status-codes","redirect-behavior","agents-md-detection","cache-header-hygiene","api-catalog","oauth-discovery","oauth-protected-resource","mcp-server-card","a2a-agent-card","agent-skills"],"example":"robots-txt-exists"},"category":{"type":"string","description":"Top-level category this check belongs to","enum":["discoverability","accessControl","contentReadability","agentEndpoints"],"example":"discoverability"},"status":{"type":"string","description":"Tri-state check result; 'neutral' is informational","enum":["pass","fail","neutral"],"example":"pass"},"scored":{"type":"boolean","description":"Whether the check is scored. false = informational — excluded from both numerator and denominator.","example":true},"weight":{"type":"number","description":"Weight on the 0-10 tier scale (Critical 10 / High 7 / Medium 4 / Low 2). 0 for informational checks.","example":10},"message":{"type":"string","description":"Declarative, verdict-phrased — 'what is the verdict + why'","example":"robots.txt found at https://competlab.com/robots.txt with 3 user-agent rules"},"description":{"type":"string","description":"Constant per-check one-sentence 'what this measures' (scan-invariant)","example":"Verifies a /robots.txt file exists and is fetchable."},"durationMs":{"type":"number","description":"Per-check duration in milliseconds","example":142},"dependsOn":{"type":"array","description":"Check IDs this check depends on — skipped when deps did not pass","example":[],"items":{"type":"string","enum":["robots-txt-exists","sitemap-exists","link-headers","ai-bot-rules","content-signals","web-bot-auth","robots-allow-all","llms-txt-exists","llms-txt-valid","llms-txt-size","llms-txt-has-optional-section","markdown-url-support","markdown-negotiation","rendering-strategy","page-size-html","http-status-codes","redirect-behavior","agents-md-detection","cache-header-hygiene","api-catalog","oauth-discovery","oauth-protected-resource","mcp-server-card","a2a-agent-card","agent-skills"]}},"specUrls":{"description":"Authoritative spec URLs (RFCs, W3C drafts, vendor docs). Always present so consumers can link to docs regardless of verdict.","example":["https://www.rfc-editor.org/rfc/rfc9309","https://developers.google.com/search/docs/crawling-indexing/robots/intro"],"type":"array","items":{"type":"string"}},"details":{"type":"object","description":"Typed per-check structured metrics. Shape varies by check id (discriminated by 'kind' === check.id). Undefined when the check has no meaningful programmatic metrics beyond `message`.","additionalProperties":true,"example":{"kind":"robots-txt-exists","userAgentCount":3,"sitemapDirectives":["https://competlab.com/sitemap.xml"]}},"fixPrompt":{"description":"Paste-to-Claude remediation. Emitted ONLY when request sent includeFixPrompts: true AND check is failed + scored.","allOf":[{"$ref":"#/components/schemas/AgentAdoptionFixPromptResponse"}]},"evidence":{"description":"Full HTTP trace. Emitted ONLY when request sent debugMode: true.","type":"array","items":{"$ref":"#/components/schemas/AgentAdoptionEvidenceResponse"}}},"required":["id","category","status","scored","weight","message","description","durationMs","dependsOn","specUrls"]},"AgentAdoptionCategoryReportResponse":{"type":"object","properties":{"category":{"type":"string","description":"Category identifier","enum":["discoverability","accessControl","contentReadability","agentEndpoints"],"example":"discoverability"},"description":{"type":"string","description":"One-sentence customer-value description of what the category covers","example":"Whether AI agents can find your site through standard discovery mechanisms (robots.txt, sitemaps, link headers)."},"score":{"type":"number","description":"0..100 integer category subscore","example":75},"passed":{"type":"number","description":"Count of scored checks that passed in this category","example":5},"failed":{"type":"number","description":"Count of scored checks that failed in this category","example":1},"neutral":{"type":"number","description":"Count of checks that were neutral / informational","example":0},"checks":{"description":"All checks belonging to this category","type":"array","items":{"$ref":"#/components/schemas/AgentAdoptionCheckResponse"}}},"required":["category","description","score","passed","failed","neutral","checks"]},"AgentAdoptionClusterVerdictResponse":{"type":"object","properties":{"name":{"type":"string","description":"Cluster verdict name","enum":["htmlPath","spaRenderingCap","noViablePathCap"],"example":"htmlPath"},"kind":{"type":"string","description":"Verdict kind. 'coefficient' scales per-check weights; 'cap' clamps the final overall score.","enum":["coefficient","cap"],"example":"coefficient"},"triggered":{"type":"boolean","description":"Whether the verdict fired for this scan","example":true},"coefficient":{"type":"number","description":"Present when kind === 'coefficient'. Multiplier in 0..1 — 1 = no penalty.","example":1},"appliesTo":{"type":"array","description":"Present when kind === 'coefficient'. Check IDs whose weight is scaled.","example":["rendering-strategy","page-size-html"],"items":{"type":"string","enum":["robots-txt-exists","sitemap-exists","link-headers","ai-bot-rules","content-signals","web-bot-auth","robots-allow-all","llms-txt-exists","llms-txt-valid","llms-txt-size","llms-txt-has-optional-section","markdown-url-support","markdown-negotiation","rendering-strategy","page-size-html","http-status-codes","redirect-behavior","agents-md-detection","cache-header-hygiene","api-catalog","oauth-discovery","oauth-protected-resource","mcp-server-card","a2a-agent-card","agent-skills"]}},"capScore":{"type":"number","description":"Present when kind === 'cap' AND triggered. Final score is forced ≤ this value.","example":50},"message":{"type":"string","description":"One-line human-readable verdict","example":"Standard HTML path detected — no rendering penalties applied."}},"required":["name","kind","triggered","message"]},"AgentAdoptionFetchCountersResponse":{"type":"object","properties":{"total":{"type":"number","description":"Total fetches attempted","example":28},"success":{"type":"number","description":"2xx status codes","example":22},"wafBlocked":{"type":"number","description":"403 + 429 responses (WAF challenge signals)","example":0},"notFound":{"type":"number","description":"404-only responses","example":5},"failed":{"type":"number","description":"Network / TLS / timeout / other 4xx-5xx failures","example":1}},"required":["total","success","wafBlocked","notFound","failed"]},"AgentAdoptionHeavyFetchCountersResponse":{"type":"object","properties":{"total":{"type":"number","description":"Total heavy-fetch operations attempted","example":2},"success":{"type":"number","description":"Successful heavy-fetch operations","example":2},"unavailable":{"type":"number","description":"Heavy-fetch operations the service could not complete (upstream unavailable or timed out)","example":0}},"required":["total","success","unavailable"]},"AgentAdoptionCountersResponse":{"type":"object","properties":{"fetches":{"description":"Per-scan lightweight HTTP fetch counters","allOf":[{"$ref":"#/components/schemas/AgentAdoptionFetchCountersResponse"}]},"heavyFetchCalls":{"description":"Per-scan heavy-fetch counters (used when the lightweight fetch is blocked or when JavaScript-rendered HTML is required)","allOf":[{"$ref":"#/components/schemas/AgentAdoptionHeavyFetchCountersResponse"}]}},"required":["fetches","heavyFetchCalls"]},"AgentAdoptionMetaResponse":{"type":"object","properties":{"checksEvaluated":{"type":"number","description":"Count of checks that produced a result (pass/fail/neutral). Dep-skipped checks DO count.","example":25},"checksSkipped":{"type":"number","description":"Count of v1 checks that did not run at all in this scan (e.g., future checks not yet implemented). Does NOT include dep-skipped checks.","example":0},"scanDurationMs":{"type":"number","description":"Total wall-clock scan duration in milliseconds","example":8420},"counters":{"description":"Per-scan counters — fetches + n8n calls. Visible in all modes.","allOf":[{"$ref":"#/components/schemas/AgentAdoptionCountersResponse"}]}},"required":["checksEvaluated","checksSkipped","scanDurationMs","counters"]},"AgentAdoptionToolResponse":{"type":"object","properties":{"specVersion":{"type":"string","description":"Spec version this output conforms to","example":"1.0.0"},"profile":{"type":"string","description":"Profile name this scanner output reflects","example":"b2b-saas"},"scanner":{"description":"Scanner identity — name + version","allOf":[{"$ref":"#/components/schemas/AgentAdoptionScannerResponse"}]},"domain":{"type":"string","description":"Normalized domain, as actually requested","example":"competlab.com"},"finalUrl":{"type":"string","description":"Final URL after redirects (from the upstream homepage fetch)","example":"https://competlab.com/"},"scannedAt":{"type":"string","description":"ISO-8601 timestamp of when the scan completed","example":"2026-05-16T14:30:00.000Z"},"score":{"type":"number","description":"0..100 integer overall score. Informational checks excluded; capped when a cluster cap verdict fires. Decorative — does NOT drive `level`.","example":72},"level":{"type":"number","description":"Numeric level tier. Gate-based — see nextLevel.requirements.","example":2},"levelName":{"type":"string","description":"Human-readable level name paired with level","example":"AI-Aware"},"nextLevel":{"description":"Next-level gate — absent when at top of known ladder (L3+ gates unknown in v1)","allOf":[{"$ref":"#/components/schemas/AgentAdoptionNextLevelResponse"}]},"categoryReports":{"description":"4 category reports — locked order: discoverability → accessControl → contentReadability → agentEndpoints","type":"array","items":{"$ref":"#/components/schemas/AgentAdoptionCategoryReportResponse"}},"clusters":{"description":"Cross-check scoring-layer verdicts (coefficients + caps). Always present — even non-triggered. Order locked: htmlPath → spaRenderingCap → noViablePathCap.","type":"array","items":{"$ref":"#/components/schemas/AgentAdoptionClusterVerdictResponse"}},"meta":{"description":"Envelope meta — scan duration, evaluated/skipped check counts, counters","allOf":[{"$ref":"#/components/schemas/AgentAdoptionMetaResponse"}]}},"required":["specVersion","profile","scanner","domain","finalUrl","scannedAt","score","level","levelName","categoryReports","clusters","meta"]},"AgentAdoptionScanErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code","enum":["homepage_fetch_failed","scan_failed"],"example":"homepage_fetch_failed"},"message":{"type":"string","description":"Human-readable error message","example":"Homepage fetch failed"}},"required":["code","message"]},"AgentAdoptionScanResponse":{"type":"object","properties":{"id":{"type":"string","description":"Scan ID (24-char hex Mongo ObjectId). Use to poll GET /scans/:scanId.","example":"6638e9a1b2c3d4e5f6a7b8c9"},"status":{"type":"string","description":"Current lifecycle state. Poll until `completed` or `failed`.","enum":["queued","running","completed","failed"],"example":"queued"},"createdAt":{"type":"string","description":"ISO-8601 timestamp when the scan was created.","example":"2026-05-17T14:30:00.000Z"},"expiresAt":{"type":"string","description":"ISO-8601 timestamp when the doc auto-deletes (createdAt + 24h). After this, GET returns 404.","example":"2026-05-18T14:30:00.000Z"},"startedAt":{"type":"string","description":"ISO-8601 timestamp when the background runner began scanning. Set once status leaves `queued`.","example":"2026-05-17T14:30:00.412Z"},"completedAt":{"type":"string","description":"ISO-8601 timestamp when the scan reached a terminal state (completed or failed).","example":"2026-05-17T14:30:45.218Z"},"result":{"description":"Full scan result. Present only when `status === \"completed\"`. Same shape as the legacy sync `/v1/tools/agent-adoption` response.","allOf":[{"$ref":"#/components/schemas/AgentAdoptionToolResponse"}]},"error":{"description":"Error details. Present only when `status === \"failed\"`.","allOf":[{"$ref":"#/components/schemas/AgentAdoptionScanErrorResponse"}]}},"required":["id","status","createdAt","expiresAt"]},"PTAgentAdoptionRequestDto":{"type":"object","properties":{}},"FetchUrlCleanStatsResponse":{"type":"object","properties":{"originalSize":{"type":"number","description":"Original HTML body size in bytes (pre-cleanup)","example":248532},"cleanedSize":{"type":"number","description":"Cleaned HTML body size in bytes (post-cleanup)","example":41218},"reductionPercent":{"type":"number","description":"Reduction percentage (0–100, one decimal place)","example":83.4},"originalSizeKB":{"type":"number","description":"Original size in kilobytes (convenience)","example":242.7},"cleanedSizeKB":{"type":"number","description":"Cleaned size in kilobytes (convenience)","example":40.3},"savedKB":{"type":"number","description":"Bytes saved expressed as kilobytes (convenience)","example":202.4}},"required":["originalSize","cleanedSize","reductionPercent","originalSizeKB","cleanedSizeKB","savedKB"]},"FetchUrlToolResponse":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code returned by the target after the cascade resolved","example":200},"body":{"type":"string","description":"Response body. Present when the request had `bodyNeeded: true`.","example":"<!DOCTYPE html><html>…</html>"},"headers":{"type":"object","description":"Response headers, lower-cased keys. Present when the request had `headersNeeded: true` AND `headersAvailable` is `true`.","additionalProperties":{"type":"string"},"example":{"content-type":"text/html; charset=utf-8","strict-transport-security":"max-age=63072000"}},"headersAvailable":{"type":"boolean","description":"Honest-degradation discriminator. `true` when headers were observed end-to-end; `false` when the target site uses advanced behavioral fingerprinting that prevents header access — `headers` will be absent in that case.","example":true},"contentType":{"type":"string","description":"Content-type of the resolved response. Present when the request had `bodyNeeded: true`.","enum":["text/html","text/plain","application/xml","application/json"],"example":"text/html"},"cleanStats":{"description":"HTML cleanup reduction stats. Present when the request had `cleanHtml: true` AND the resolved content-type is `text/html`.","allOf":[{"$ref":"#/components/schemas/FetchUrlCleanStatsResponse"}]},"finalUrl":{"type":"string","description":"Resolved URL after any redirects","example":"https://stripe.com/"},"durationMs":{"type":"number","description":"End-to-end fetch duration in milliseconds","example":1842}},"required":["statusCode","finalUrl","durationMs"]},"PTFetchUrlRequestDto":{"type":"object","properties":{"url":{"type":"string","description":"Target URL to fetch. Must use http:// or https:// and resolve to a public host.","example":"https://stripe.com"},"bodyNeeded":{"type":"boolean","description":"Include `body` and `contentType` in the response. Defaults to service-controlled value when omitted.","example":true},"headersNeeded":{"type":"boolean","description":"Include `headers` and `headersAvailable` in the response. Defaults to service-controlled value when omitted. When the target site uses advanced behavioral fingerprinting, `headersAvailable` will be `false` and `headers` will be absent.","example":true},"cleanHtml":{"type":"boolean","description":"When `true` and the response content-type is `text/html`, strip HTML noise (scripts, styles, comments) while preserving text content. Significant token-cost reduction for LLM consumption — per-request reduction reported in `cleanStats`. Requires `bodyNeeded`.","example":false},"maxTimeoutMs":{"type":"number","description":"Caller-side timeout budget in milliseconds. Accepted range 1000–120000. Defaults to service-controlled value when omitted.","example":60000,"minimum":1000,"maximum":120000},"bodyMaxBytes":{"type":"number","description":"Per-request response body cap in bytes. Accepted range 1024–104857600 (1 KiB – 100 MiB). Oversize responses are rejected pre-buffer. Defaults to service-controlled value when omitted.","example":5242880,"minimum":1024,"maximum":104857600}},"required":["url"]}}}}