{ "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 — plus AI-generated competitive analysis when available.", "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 — plus AI-generated content strategy insights when available. 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 — plus AI-generated positioning insights when available.", "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 — plus AI-generated pricing insights when available.", "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 — plus AI-generated competitive insights when available. 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. 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}/analysis/action-plan": { "get": { "description": "Get the aggregated competitive action plan for a project. Combines AI-generated insights and recommended actions from all five monitoring dimensions (Tech & Trust, Content, Positioning, Pricing, AI Visibility). Returns competitive insights prioritized by severity, actionable recommendations with effort/impact ratings, and per-dimension analysis freshness timestamps. Use this endpoint to build competitive intelligence dashboards or feed action items into project management tools. Dimensions return null in dimensionStatus until their first analysis completes. Insights and actions accumulate progressively as each dimension finishes its monitoring cycle.", "operationId": "PublicAnalysisController_getActionPlan_v1", "parameters": [ { "name": "projectId", "required": true, "in": "path", "description": "Project ID", "schema": { "example": "507f1f77bcf86cd799439011" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "title": "ItemResponseOfActionPlanApiResponse", "type": "object", "properties": { "item": { "$ref": "#/components/schemas/ActionPlanApiResponse" } }, "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 aggregated competitive action plan", "tags": ["Analysis"] } }, "/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/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-readiness 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-ready 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"] } } }, "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 data + analysis in one call), **history** (paginated past runs), and **run detail** (full data for a specific historical run).\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" }, "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", "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" }, "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", "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" ] }, "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 }, "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 } }, "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" ] }, "AnalysisInsightResponse": { "type": "object", "properties": { "type": { "type": "string", "description": "Insight category", "enum": [ "security", "technology", "infrastructure", "trust", "robots", "messaging", "homepage", "pricing", "company", "content", "ai_visibility" ], "example": "security" }, "priority": { "type": "string", "description": "Priority level", "enum": ["critical", "high", "medium", "low"], "example": "high" }, "title": { "type": "string", "description": "Insight title", "example": "Security posture gap detected" }, "description": { "type": "string", "description": "Detailed insight description", "example": "Competitor X has stronger security headers..." } }, "required": ["type", "priority", "title", "description"] }, "AnalysisActionResponse": { "type": "object", "properties": { "type": { "type": "string", "description": "Action category", "enum": [ "security", "technology", "infrastructure", "trust", "robots", "messaging", "homepage", "pricing", "company", "content", "ai_visibility" ], "example": "security" }, "title": { "type": "string", "description": "Action title", "example": "Implement HSTS header" }, "description": { "type": "string", "description": "Detailed action description", "example": "Add Strict-Transport-Security header..." }, "effort": { "type": "string", "description": "Implementation effort level", "enum": ["trivial", "low", "medium", "high"], "example": "low" }, "impact": { "type": "string", "description": "Expected business impact", "enum": ["low", "medium", "high", "critical"], "example": "high" }, "timeframe": { "type": "string", "description": "Suggested implementation timeframe", "example": "1-2 weeks" } }, "required": [ "type", "title", "description", "effort", "impact", "timeframe" ] }, "TechTrustAnalysisResponse": { "type": "object", "properties": { "insights": { "description": "Competitive insights from AI analysis", "type": "array", "items": { "$ref": "#/components/schemas/AnalysisInsightResponse" } }, "actions": { "description": "Recommended competitive actions", "type": "array", "items": { "$ref": "#/components/schemas/AnalysisActionResponse" } } }, "required": ["insights", "actions"] }, "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" } }, "analysis": { "description": "AI-generated competitive analysis, or null if no analysis available", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TechTrustAnalysisResponse" } ] } }, "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 among all competitors by strategic URL count", "example": 3 }, "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", "overallRank", "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" ] }, "ContentAnalysisResponse": { "type": "object", "properties": { "insights": { "description": "Competitive insights from content analysis", "type": "array", "items": { "$ref": "#/components/schemas/AnalysisInsightResponse" } }, "actions": { "description": "Recommended competitive actions", "type": "array", "items": { "$ref": "#/components/schemas/AnalysisActionResponse" } } }, "required": ["insights", "actions"] }, "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" } }, "analysis": { "description": "AI-generated competitive analysis, or null if no analysis available", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContentAnalysisResponse" } ] } }, "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"] }, "PositioningAnalysisResponse": { "type": "object", "properties": { "insights": { "description": "Competitive insights from positioning analysis", "type": "array", "items": { "$ref": "#/components/schemas/AnalysisInsightResponse" } }, "actions": { "description": "Recommended competitive actions", "type": "array", "items": { "$ref": "#/components/schemas/AnalysisActionResponse" } } }, "required": ["insights", "actions"] }, "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" } }, "analysis": { "description": "AI-generated competitive analysis, or null if no analysis available", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PositioningAnalysisResponse" } ] } }, "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), or null if unavailable", "example": 59, "nullable": true }, "pricePositionPercent": { "type": "number", "description": "Your price position as percentile (0-100, higher = more expensive)", "example": 45 }, "topPriceCompetitor": { "description": "Competitor with the highest price, or null if unavailable", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PricingSummaryPriceCompetitorResponse" } ] }, "lowestPriceCompetitor": { "description": "Competitor with the lowest price, or null if unavailable", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PricingSummaryPriceCompetitorResponse" } ] }, "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", "pricePositionPercent", "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" ] }, "PricingAnalysisResponse": { "type": "object", "properties": { "insights": { "description": "Competitive insights from pricing analysis", "type": "array", "items": { "$ref": "#/components/schemas/AnalysisInsightResponse" } }, "actions": { "description": "Recommended competitive actions", "type": "array", "items": { "$ref": "#/components/schemas/AnalysisActionResponse" } } }, "required": ["insights", "actions"] }, "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" } }, "analysis": { "description": "AI-generated competitive analysis, or null if no analysis available", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PricingAnalysisResponse" } ] } }, "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" ] }, "AiVisibilityAnalysisResponse": { "type": "object", "properties": { "insights": { "description": "AI-generated competitive insights aggregated from all providers", "type": "array", "items": { "$ref": "#/components/schemas/AnalysisInsightResponse" } }, "actions": { "description": "AI-generated recommended actions aggregated from all providers", "type": "array", "items": { "$ref": "#/components/schemas/AnalysisActionResponse" } } }, "required": ["insights", "actions"] }, "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" } ] }, "analysis": { "description": "AI-generated analysis (null if no analysis has been run)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AiVisibilityAnalysisResponse" } ] } }, "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": "number", "description": "Customer AI Visibility Score (0-100)", "example": 73 }, "topCompetitorAiScore": { "type": "number", "description": "Top competitor AI Visibility Score (0-100)", "example": 85 } }, "required": [ "date", "customerMentionRate", "topCompetitorMentionRate", "gap", "customerAiScore", "topCompetitorAiScore" ] }, "AiProvider": { "type": "string", "enum": ["openai", "claude", "gemini"] }, "InsightType": { "type": "string", "enum": [ "security", "technology", "infrastructure", "trust", "robots", "messaging", "homepage", "pricing", "company", "content", "ai_visibility" ], "description": "Insight category" }, "InsightPriority": { "type": "string", "enum": ["critical", "high", "medium", "low"], "description": "Priority level" }, "ActionPlanInsightResponse": { "type": "object", "properties": { "type": { "description": "Insight category", "example": "security", "allOf": [{ "$ref": "#/components/schemas/InsightType" }] }, "priority": { "description": "Priority level", "example": "high", "allOf": [{ "$ref": "#/components/schemas/InsightPriority" }] }, "title": { "type": "string", "description": "Short insight title (5-10 words)", "example": "Security posture gap detected" }, "description": { "type": "string", "description": "Detailed insight description with specific data", "example": "Competitor X has implemented HSTS and CSP headers while your site lacks both, creating a measurable security gap." }, "evidence": { "type": "string", "description": "Supporting data point or evidence for this insight", "example": "3 of 4 competitors have A+ security grades vs your B- grade" }, "relatedCompetitors": { "description": "Domains of competitors related to this insight", "example": ["competitor1.com", "competitor2.com"], "type": "array", "items": { "type": "string" } } }, "required": ["type", "priority", "title", "description"] }, "ActionEffort": { "type": "string", "enum": ["trivial", "low", "medium", "high"], "description": "Implementation effort level" }, "ActionImpact": { "type": "string", "enum": ["low", "medium", "high", "critical"], "description": "Expected business impact" }, "ActionPlanActionResponse": { "type": "object", "properties": { "type": { "description": "Action category", "example": "pricing", "allOf": [{ "$ref": "#/components/schemas/InsightType" }] }, "title": { "type": "string", "description": "Imperative action title (5-10 words)", "example": "Introduce annual billing discount" }, "description": { "type": "string", "description": "What to do and why", "example": "Competitors offer 15-20% annual billing discounts while you only offer monthly pricing, reducing price competitiveness for committed buyers." }, "effort": { "description": "Implementation effort level", "example": "medium", "allOf": [{ "$ref": "#/components/schemas/ActionEffort" }] }, "impact": { "description": "Expected business impact", "example": "high", "allOf": [{ "$ref": "#/components/schemas/ActionImpact" }] }, "timeframe": { "type": "string", "description": "Suggested implementation timeframe", "example": "2-4 weeks" }, "rationale": { "type": "string", "description": "Why this action matters for competitive positioning", "example": "Annual billing discounts are standard among top competitors and drive higher customer lifetime value through longer commitments." } }, "required": [ "type", "title", "description", "effort", "impact", "timeframe" ] }, "DimensionAnalysisStatusResponse": { "type": "object", "properties": { "analysisCompletedAt": { "type": "string", "description": "When the analysis completed (ISO-8601)", "example": "2026-03-15T10:00:00.000Z" } }, "required": ["analysisCompletedAt"] }, "ActionPlanDimensionStatusResponse": { "type": "object", "properties": { "techTrust": { "description": "Tech & Trust dimension analysis status", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionAnalysisStatusResponse" } ] }, "content": { "description": "Content Intelligence dimension analysis status", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionAnalysisStatusResponse" } ] }, "positioning": { "description": "Positioning dimension analysis status", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionAnalysisStatusResponse" } ] }, "pricing": { "description": "Pricing Intelligence dimension analysis status", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionAnalysisStatusResponse" } ] }, "aiVisibility": { "description": "AI Visibility dimension analysis status", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DimensionAnalysisStatusResponse" } ] } } }, "ActionPlanApiResponse": { "type": "object", "properties": { "planGeneratedAt": { "type": "object", "description": "When the most recent dimension analysis completed (ISO-8601). Null if no analysis has run yet.", "example": "2026-03-15T10:00:00.000Z", "nullable": true }, "insights": { "description": "Competitive insights aggregated from all monitoring dimensions", "type": "array", "items": { "$ref": "#/components/schemas/ActionPlanInsightResponse" } }, "actions": { "description": "Recommended competitive actions aggregated from all monitoring dimensions", "type": "array", "items": { "$ref": "#/components/schemas/ActionPlanActionResponse" } }, "dimensionStatus": { "description": "Per-dimension analysis completion status (null if no analysis has run for that dimension)", "allOf": [ { "$ref": "#/components/schemas/ActionPlanDimensionStatusResponse" } ] } }, "required": ["insights", "actions", "dimensionStatus"] }, "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" ] }, "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": "