{ "openapi": "3.0.0", "info": { "title": "Promptwatch API v2", "description": "API v2 for customer integrations with Promptwatch monitoring platform. This version provides improved structure, additional endpoints, and enhanced functionality.", "version": "2.0.0", "contact": { "name": "Promptwatch Support", "email": "team@promptwatch.com", "url": "https://promptwatch.com" }, "license": { "name": "Commercial", "url": "https://promptwatch.com/terms-and-conditions" } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for authentication. Get yours from the Promptwatch dashboard under Settings > API Keys." } }, "parameters": { "ProjectId": { "name": "X-Project-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Project ID to operate on. Required when using an organization-level API key (except for GET /projects and POST /projects routes), optional (ignored) for project-level keys." } }, "schemas": {} }, "paths": { "/auth/validate": { "get": { "operationId": "validateApiKey", "summary": "Validate API Key", "tags": [ "Authentication" ], "description": "Validate an API key and get associated project/organization details. For organization-level keys, optionally provide X-Project-Id header to validate access to a specific project.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "header", "name": "x-project-id", "required": false, "description": "Project ID to validate (required for organization-level keys when accessing project resources)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "valid": true, "keyType": "organization", "project": { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "Example Project", "slug": "example-project" }, "organization": { "id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", "name": "Example Org", "slug": "example-org" }, "apiKey": { "id": "550e8400-e29b-41d4-a716-446655440001", "name": "CI integration", "createdAt": "2026-03-01T12:00:00.000Z", "lastUsedAt": "2026-03-30T08:15:22.000Z" }, "availableProjects": null }, "properties": { "valid": { "type": "boolean", "description": "Whether the API key is valid" }, "keyType": { "type": "string", "enum": [ "project", "organization" ], "description": "Type of API key - project-level or organization-level" }, "project": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Project ID" }, "name": { "type": "string", "description": "Project name" }, "slug": { "type": "string", "description": "Project slug" } }, "required": [ "id", "name", "slug" ], "description": "Project details. For org keys, only present when X-Project-Id header is provided." }, "organization": { "type": "object", "properties": { "id": { "type": "string", "description": "Organization ID" }, "name": { "type": "string", "description": "Organization name" }, "slug": { "type": "string", "description": "Organization slug" } }, "required": [ "id", "name", "slug" ] }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "description": "API key ID" }, "name": { "type": "string", "description": "API key name" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the API key was created" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the API key was last used" } }, "required": [ "id", "name", "createdAt" ] }, "availableProjects": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Project ID" }, "name": { "type": "string", "description": "Project name" }, "slug": { "type": "string", "description": "Project slug" } }, "required": [ "id", "name", "slug" ] }, "description": "List of available projects. Only present for organization-level keys when no X-Project-Id header is provided." } }, "required": [ "valid", "keyType", "organization", "apiKey" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "valid": false, "message": "Invalid API key." }, "properties": { "valid": { "type": "boolean", "description": "Whether the API key is valid", "enum": [ false ] }, "message": { "type": "string", "description": "Error message" } }, "required": [ "valid", "message" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/content-gap/stats": { "get": { "operationId": "getContentGapStats", "summary": "Content Gap Stats", "tags": [ "Content Gap" ], "description": "Get aggregate content coverage statistics for the project", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } } ] }, "in": "query", "name": "promptTypes", "required": false, "description": "Prompt type filter; repeat the parameter for multiple values" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Only count analyses with createdAt on or after this day (UTC)." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "Only count analyses with createdAt on or before this day (UTC)." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "totalPromptsWithCoverage": 180, "totalPromptsWithoutCoverage": 42, "averageCoverageScore": 0.61, "distribution": { "low": 35, "medium": 52, "good": 78, "excellent": 57 }, "byPromptType": [ { "category": "ORGANIC", "averageScore": 0.58, "count": 90, "totalPrompts": 120 }, { "category": "BRAND_SPECIFIC", "averageScore": 0.72, "count": 40, "totalPrompts": 55 } ], "byIntentType": [ { "category": "INFORMATIONAL", "averageScore": 0.62, "count": 100, "totalPrompts": 140 }, { "category": "COMMERCIAL", "averageScore": 0.55, "count": 35, "totalPrompts": 50 } ] }, "properties": { "totalPromptsWithCoverage": { "type": "number", "description": "Prompts with at least one coverage score" }, "totalPromptsWithoutCoverage": { "type": "number", "description": "Prompts with no coverage score yet" }, "averageCoverageScore": { "type": "number", "nullable": true, "description": "Mean score across scored prompts" }, "distribution": { "type": "object", "description": "Count of prompts per score band", "properties": { "low": { "type": "number", "description": "Low band count" }, "medium": { "type": "number", "description": "Medium band count" }, "good": { "type": "number", "description": "Good band count" }, "excellent": { "type": "number", "description": "Excellent band count" } }, "required": [ "low", "medium", "good", "excellent" ] }, "byPromptType": { "type": "array", "description": "Breakdown by prompt type", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ], "description": "Prompt type" }, "averageScore": { "type": "number", "nullable": true, "description": "Mean score in this bucket" }, "count": { "type": "number", "description": "Scored prompts in this bucket" }, "totalPrompts": { "type": "number", "description": "All prompts in this bucket" } }, "required": [ "category", "averageScore", "count", "totalPrompts" ] } }, "byIntentType": { "type": "array", "description": "Breakdown by intent type", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ], "description": "Intent type" }, "averageScore": { "type": "number", "nullable": true, "description": "Mean score in this bucket" }, "count": { "type": "number", "description": "Scored prompts in this bucket" }, "totalPrompts": { "type": "number", "description": "All prompts in this bucket" } }, "required": [ "category", "averageScore", "count", "totalPrompts" ] } } }, "required": [ "totalPromptsWithCoverage", "totalPromptsWithoutCoverage", "averageCoverageScore", "distribution", "byPromptType", "byIntentType" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "CONTENT_GAP_PROMPT_NOT_FOUND", "message": "Prompt not found" }, "properties": { "code": { "type": "string", "description": "Domain error code", "enum": [ "CONTENT_GAP_PROMPT_NOT_FOUND", "CONTENT_GAP_PROJECT_MISSING", "CONTENT_GAP_WEBSITE_NOT_CONFIGURED", "INTERNAL_ERROR" ] }, "message": { "type": "string", "description": "Human-readable explanation" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/content-gap/prompts": { "get": { "operationId": "getContentGapPrompts", "summary": "List Content Gap Prompts", "tags": [ "Content Gap" ], "description": "Get paginated list of prompts with content gap scores", "parameters": [ { "schema": { "type": "integer", "default": 1, "minimum": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number (1-based)" }, { "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }, "in": "query", "name": "size", "required": false, "description": "Page size" }, { "schema": { "type": "string" }, "in": "query", "name": "query", "required": false, "description": "Free-text filter on prompt text" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } } ] }, "in": "query", "name": "promptTypes", "required": false, "description": "Prompt type filter; repeat the parameter for multiple values" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ] }, { "type": "array", "items": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ] } } ] }, "in": "query", "name": "intentTypes", "required": false, "description": "Intent type filter; repeat the parameter for multiple values" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "array", "items": { "type": "string", "format": "uuid" } } ] }, "in": "query", "name": "tagIds", "required": false, "description": "Filter by prompt tag IDs. Matches prompts with any of the given tags (OR). Repeat for multiple: tagIds=uuid1&tagIds=uuid2" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "array", "items": { "type": "string", "format": "uuid" } } ] }, "in": "query", "name": "topicIds", "required": false, "description": "Filter by prompt topic IDs. Matches prompts with any of the given topics (OR). Repeat for multiple: topicIds=uuid1&topicIds=uuid2" }, { "schema": { "type": "boolean" }, "in": "query", "name": "hasCoverage", "required": false, "description": "When true, only prompts with a coverage score" }, { "schema": { "type": "string", "enum": [ "contentCoverageScore", "createdAt" ] }, "in": "query", "name": "sortBy", "required": false, "description": "Sort field" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortOrder", "required": false, "description": "Sort direction" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Latest gap per prompt is chosen only among runs with createdAt on or after this day (UTC)." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "Latest gap per prompt is chosen only among runs with createdAt on or before this day (UTC)." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "items": [ { "id": "6ba7b823-9dad-11d1-80b4-00c04fd430c8", "prompt": "Best CRM for 50-person services firms?", "type": "ORGANIC", "intent": "COMMERCIAL", "languageCode": "en-US", "createdAt": "2026-03-01T10:00:00.000Z", "responseCount": 24, "latestContentGap": { "id": "6ba7b824-9dad-11d1-80b4-00c04fd430c8", "score": 0.63, "date": "2026-03-28T12:00:00.000Z", "sitemapTotalUrls": 500, "sitemapCrawledUrls": 412, "queryFanoutsCount": 6 } }, { "id": "6ba7b825-9dad-11d1-80b4-00c04fd430c8", "prompt": "How does Example Brand compare on integrations?", "type": "COMPETITOR_COMPARISON", "intent": "INFORMATIONAL", "languageCode": "en-US", "createdAt": "2026-03-10T15:30:00.000Z", "responseCount": 12, "latestContentGap": null } ], "total": 222, "page": 1, "size": 25, "totalPages": 9 }, "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Prompt identifier" }, "prompt": { "type": "string", "description": "Prompt text" }, "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ], "nullable": true, "description": "Prompt type" }, "intent": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ], "nullable": true, "description": "Intent type" }, "languageCode": { "type": "string", "nullable": true, "description": "BCP 47 language tag" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the prompt was created" }, "responseCount": { "type": "number", "description": "Monitor responses collected for this prompt" }, "latestContentGap": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Coverage run identifier" }, "score": { "type": "number", "description": "Content coverage score for this run" }, "date": { "type": "string", "format": "date-time", "description": "When this run completed" }, "sitemapTotalUrls": { "type": "number", "description": "URLs discovered in sitemap" }, "sitemapCrawledUrls": { "type": "number", "description": "URLs successfully crawled" }, "queryFanoutsCount": { "type": "number", "nullable": true, "description": "Query expansion count" } }, "required": [ "id", "score", "date", "sitemapTotalUrls", "sitemapCrawledUrls", "queryFanoutsCount" ], "additionalProperties": false, "nullable": true, "description": "Most recent coverage run, if any" } }, "required": [ "id", "prompt", "type", "intent", "languageCode", "createdAt", "responseCount", "latestContentGap" ], "additionalProperties": false }, "description": "Page of prompts" }, "page": { "type": "integer", "description": "Page number (1-based)" }, "size": { "type": "integer", "description": "Page size" }, "total": { "type": "integer", "description": "Total items matching the request" }, "totalPages": { "type": "integer", "description": "Total pages for this page size" } }, "required": [ "items", "total", "page", "size", "totalPages" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "CONTENT_GAP_PROMPT_NOT_FOUND", "message": "Prompt not found" }, "properties": { "code": { "type": "string", "description": "Domain error code", "enum": [ "CONTENT_GAP_PROMPT_NOT_FOUND", "CONTENT_GAP_PROJECT_MISSING", "CONTENT_GAP_WEBSITE_NOT_CONFIGURED", "INTERNAL_ERROR" ] }, "message": { "type": "string", "description": "Human-readable explanation" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/content-gap/prompts/{promptId}/latest": { "get": { "operationId": "getContentGapLatest", "summary": "Latest Content Coverage", "tags": [ "Content Gap" ], "description": "Get the latest content coverage result for a prompt. Returns null if the prompt exists but has no content coverage yet.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "promptId", "required": true, "description": "Prompt identifier" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "nullable": true, "type": "object", "example": { "id": "6ba7b826-9dad-11d1-80b4-00c04fd430c8", "contentCoverageScore": 0.64, "explanation": "Illustrative: key product claims are partially supported on-site.", "report": "## Coverage summary\n\nExample markdown sections only.", "sources": [ { "url": "https://docs.example.com/security", "title": "Security overview", "snippet": "Illustrative snippet text." } ], "queryFanouts": [ "crm for agencies", "compare CRM features" ], "sitemapTotalUrls": 500, "sitemapCrawledUrls": 412, "createdAt": "2026-03-28T12:00:00.000Z", "recommendations": [ { "id": "6ba7b827-9dad-11d1-80b4-00c04fd430c8", "title": "Add integration comparison table", "action": "CREATE", "details": "Illustrative recommendation body.", "priority": 1, "impact": "HIGH", "effort": "MODERATE", "contentType": "ARTICLE", "queryFanouts": [ "crm integrations" ], "suggestedSections": [ "Overview", "FAQ" ], "targetSources": [ { "url": "https://competitor.example/compare", "title": "Competitor page", "snippet": "Illustrative." } ] } ] }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Coverage run identifier" }, "contentCoverageScore": { "type": "number", "description": "Aggregate coverage score" }, "explanation": { "type": "string", "description": "Plain-language summary" }, "report": { "type": "string", "description": "Markdown report body" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Source page URL" }, "title": { "type": "string", "description": "Page title" }, "snippet": { "type": "string", "description": "Relevant excerpt" } }, "required": [ "url", "title", "snippet" ], "additionalProperties": false }, "description": "Cited URLs from analysis" }, "queryFanouts": { "type": "array", "items": { "type": "string" }, "description": "Expanded queries used in analysis" }, "sitemapTotalUrls": { "type": "number", "description": "URLs in sitemap at run time" }, "sitemapCrawledUrls": { "type": "number", "description": "URLs crawled for this run" }, "createdAt": { "type": "string", "format": "date-time", "description": "When this run completed" }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Resource identifier" }, "title": { "type": "string", "description": "Recommendation headline" }, "action": { "type": "string", "enum": [ "CREATE", "OPTIMIZE" ], "description": "Suggested action" }, "details": { "type": "string", "description": "Rationale and next steps" }, "priority": { "type": "number", "description": "Sort order (lower is higher priority)" }, "impact": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW" ], "nullable": true, "description": "Expected impact" }, "effort": { "type": "string", "enum": [ "QUICK_WIN", "MODERATE", "SIGNIFICANT" ], "nullable": true, "description": "Implementation effort" }, "contentType": { "type": "string", "enum": [ "ARTICLE", "BLOG_POST", "OPINION", "LISTICLE", "HOW_TO", "REVIEW", "COMPARISON", "CASE_STUDY", "INTERVIEW", "DOCUMENTATION", "WIKI", "PRODUCT_PAGE", "LANDING_PAGE", "PRESS_RELEASE", "GENERIC_CONTENT", "PRODUCT_COMPARISON" ], "nullable": true, "description": "Suggested content format" }, "queryFanouts": { "type": "array", "items": { "type": "string" }, "description": "Related query variants" }, "suggestedSections": { "type": "array", "items": { "type": "string" }, "description": "Proposed outline sections" }, "targetSources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Source page URL" }, "title": { "type": "string", "description": "Page title" }, "snippet": { "type": "string", "description": "Relevant excerpt" } }, "required": [ "url", "title", "snippet" ], "additionalProperties": false }, "description": "Sources to reference or beat" } }, "required": [ "id", "title", "action", "details", "priority", "targetSources", "queryFanouts", "suggestedSections" ], "additionalProperties": false }, "description": "Structured recommendations" } }, "required": [ "id", "contentCoverageScore", "explanation", "report", "sources", "queryFanouts", "sitemapTotalUrls", "sitemapCrawledUrls", "createdAt", "recommendations" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "CONTENT_GAP_PROMPT_NOT_FOUND", "message": "Prompt not found" }, "properties": { "code": { "type": "string", "description": "Domain error code", "enum": [ "CONTENT_GAP_PROMPT_NOT_FOUND", "CONTENT_GAP_PROJECT_MISSING", "CONTENT_GAP_WEBSITE_NOT_CONFIGURED", "INTERNAL_ERROR" ] }, "message": { "type": "string", "description": "Human-readable explanation" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "CONTENT_GAP_PROMPT_NOT_FOUND", "message": "Prompt not found" }, "properties": { "code": { "type": "string", "description": "Domain error code", "enum": [ "CONTENT_GAP_PROMPT_NOT_FOUND", "CONTENT_GAP_PROJECT_MISSING", "CONTENT_GAP_WEBSITE_NOT_CONFIGURED", "INTERNAL_ERROR" ] }, "message": { "type": "string", "description": "Human-readable explanation" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/content-gap/prompts/{promptId}/latest/recommendations": { "get": { "operationId": "getContentGapRecommendations", "summary": "Content Recommendations", "tags": [ "Content Gap" ], "description": "Get content recommendations from the latest content gap analysis for a prompt", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "promptId", "required": true, "description": "Prompt identifier" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "promptId": "6ba7b823-9dad-11d1-80b4-00c04fd430c8", "prompt": "Best CRM for 50-person services firms?", "contentCoverageScore": 0.64, "recommendations": [ { "id": "6ba7b827-9dad-11d1-80b4-00c04fd430c8", "title": "Publish integrations matrix", "action": "OPTIMIZE", "details": "Illustrative detail text.", "priority": 2, "impact": "MEDIUM", "effort": "QUICK_WIN", "contentType": "LISTICLE", "queryFanouts": [ "crm integrations list" ], "suggestedSections": [ "Compare", "Sources" ], "targetSources": [ { "url": "https://docs.example.com/integrations", "title": "Integrations", "snippet": "Illustrative." } ] } ] }, "properties": { "promptId": { "type": "string", "format": "uuid", "description": "Prompt identifier" }, "prompt": { "type": "string", "description": "Prompt text" }, "contentCoverageScore": { "type": "number", "nullable": true, "description": "Latest score; null if never analyzed" }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Resource identifier" }, "title": { "type": "string", "description": "Recommendation headline" }, "action": { "type": "string", "enum": [ "CREATE", "OPTIMIZE" ], "description": "Suggested action" }, "details": { "type": "string", "description": "Rationale and next steps" }, "priority": { "type": "number", "description": "Sort order (lower is higher priority)" }, "impact": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW" ], "nullable": true, "description": "Expected impact" }, "effort": { "type": "string", "enum": [ "QUICK_WIN", "MODERATE", "SIGNIFICANT" ], "nullable": true, "description": "Implementation effort" }, "contentType": { "type": "string", "enum": [ "ARTICLE", "BLOG_POST", "OPINION", "LISTICLE", "HOW_TO", "REVIEW", "COMPARISON", "CASE_STUDY", "INTERVIEW", "DOCUMENTATION", "WIKI", "PRODUCT_PAGE", "LANDING_PAGE", "PRESS_RELEASE", "GENERIC_CONTENT", "PRODUCT_COMPARISON" ], "nullable": true, "description": "Suggested content format" }, "queryFanouts": { "type": "array", "items": { "type": "string" }, "description": "Related query variants" }, "suggestedSections": { "type": "array", "items": { "type": "string" }, "description": "Proposed outline sections" }, "targetSources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Source page URL" }, "title": { "type": "string", "description": "Page title" }, "snippet": { "type": "string", "description": "Relevant excerpt" } }, "required": [ "url", "title", "snippet" ], "additionalProperties": false }, "description": "Sources to reference or beat" } }, "required": [ "id", "title", "action", "details", "priority", "targetSources", "queryFanouts", "suggestedSections" ], "additionalProperties": false }, "description": "Recommendations from the latest run" } }, "required": [ "promptId", "prompt", "contentCoverageScore", "recommendations" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "CONTENT_GAP_PROMPT_NOT_FOUND", "message": "Prompt not found" }, "properties": { "code": { "type": "string", "description": "Domain error code", "enum": [ "CONTENT_GAP_PROMPT_NOT_FOUND", "CONTENT_GAP_PROJECT_MISSING", "CONTENT_GAP_WEBSITE_NOT_CONFIGURED", "INTERNAL_ERROR" ] }, "message": { "type": "string", "description": "Human-readable explanation" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "CONTENT_GAP_PROMPT_NOT_FOUND", "message": "Prompt not found" }, "properties": { "code": { "type": "string", "description": "Domain error code", "enum": [ "CONTENT_GAP_PROMPT_NOT_FOUND", "CONTENT_GAP_PROJECT_MISSING", "CONTENT_GAP_WEBSITE_NOT_CONFIGURED", "INTERNAL_ERROR" ] }, "message": { "type": "string", "description": "Human-readable explanation" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/content": { "get": { "operationId": "listContent", "summary": "List content", "tags": [ "Content" ], "description": "Lists content documents for the project with pagination. Response rows are summary fields only; use GET /content/:id for the full document.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number (1-based)." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "in": "query", "name": "size", "required": false, "description": "Page size (max 100); matches other v2 list endpoints." }, { "schema": { "type": "string", "enum": [ "createdAt", "updatedAt" ], "default": "createdAt" }, "in": "query", "name": "orderBy", "required": false, "description": "Sort field." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "in": "query", "name": "sortOrder", "required": false, "description": "Sort direction." }, { "schema": { "type": "string", "enum": [ "CREATE", "OPTIMIZE" ] }, "in": "query", "name": "mode", "required": false, "description": "Filter by CREATE vs OPTIMIZE." }, { "schema": { "type": "string", "enum": [ "DRAFT", "PENDING", "IN_PROGRESS", "COMPLETED", "FAILED", "STOPPED" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by generation status." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "documents": [ { "id": "6ba7b82c-9dad-11d1-80b4-00c04fd430c8", "status": "COMPLETED", "mode": "CREATE", "type": "ARTICLE", "title": "Illustrative GEO checklist article", "promptId": "6ba7b823-9dad-11d1-80b4-00c04fd430c8", "prompt": "How do I track AI search visibility?", "createdAt": "2026-03-20T10:00:00.000Z", "updatedAt": "2026-03-20T10:08:00.000Z", "completedAt": "2026-03-20T10:08:00.000Z" }, { "id": "6ba7b82d-9dad-11d1-80b4-00c04fd430c8", "status": "FAILED", "mode": "OPTIMIZE", "type": null, "title": null, "promptId": "6ba7b825-9dad-11d1-80b4-00c04fd430c8", "prompt": "How does Example Brand compare on integrations?", "createdAt": "2026-03-21T09:00:00.000Z", "updatedAt": "2026-03-21T09:02:00.000Z", "completedAt": null } ], "total": 2, "page": 1, "size": 25, "totalPages": 1 }, "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "DRAFT", "PENDING", "IN_PROGRESS", "COMPLETED", "FAILED", "STOPPED" ], "description": "PENDING: queued for generation; IN_PROGRESS: AI is actively generating content; COMPLETED: generation finished successfully; FAILED: generation encountered an error; STOPPED: generation was manually stopped by the user (may contain partial content)." }, "mode": { "type": "string", "enum": [ "CREATE", "OPTIMIZE" ], "description": "CREATE: new content from a prompt; OPTIMIZE: rewrite of an existing page." }, "type": { "type": "string", "enum": [ "ARTICLE", "BLOG_POST", "OPINION", "LISTICLE", "HOW_TO", "REVIEW", "COMPARISON", "CASE_STUDY", "INTERVIEW", "DOCUMENTATION", "WIKI", "PRODUCT_PAGE", "LANDING_PAGE", "PRESS_RELEASE", "GENERIC_CONTENT", "PRODUCT_COMPARISON" ], "nullable": true, "description": "Content format (CREATE mode only)." }, "title": { "type": "string", "nullable": true, "description": "Document title; null until generation completes." }, "promptId": { "type": "string", "format": "uuid", "nullable": true, "description": "Linked monitor prompt id." }, "prompt": { "type": "string", "nullable": true, "description": "Linked LLM prompt text; null if the prompt was removed." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "status", "mode", "type", "title", "promptId", "prompt", "createdAt", "updatedAt", "completedAt" ], "additionalProperties": false }, "description": "Documents for the current page (no full markdown body)." }, "total": { "type": "integer", "minimum": 0, "description": "Total documents matching filters (all pages)." }, "page": { "type": "integer", "minimum": 1 }, "size": { "type": "integer", "minimum": 1, "description": "Page length (same as request `size`)." }, "totalPages": { "type": "integer", "minimum": 0, "description": "Ceil(total / size)." } }, "required": [ "documents", "total", "page", "size", "totalPages" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "CONTENT_NOT_FOUND", "message": "Content document not found" }, "properties": { "code": { "type": "string", "description": "Machine-readable error code", "enum": [ "CONTENT_NOT_FOUND", "CONTENT_DRAFT_NOT_FOUND", "CONTENT_INVALID_PROMPT", "CONTENT_INVALID_PERSONA", "CONTENT_PAGE_FETCH_FAILED", "CONTENT_PAGE_NOT_FOUND", "CONTENT_PAGE_NO_CONTENT", "CONTENT_INVALID_TONE", "CONTENT_RECOMMENDATION_NOT_FOUND", "CONTENT_GENERATION_FAILED", "INTERNAL_ERROR" ], "example": "CONTENT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Content document not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "CONTENT_NOT_FOUND", "message": "Content document not found" } }, "example2": { "value": { "code": "CONTENT_INVALID_PROMPT", "message": "Prompt not found or does not belong to this project" } }, "example3": { "value": { "code": "CONTENT_GENERATION_FAILED", "message": "Failed to start content generation" } } } } } } } } }, "/content/create": { "post": { "operationId": "createContent", "summary": "Create content", "tags": [ "Content" ], "description": "Starts AI content generation (CREATE or OPTIMIZE). Returns the new document id with status PENDING; use GET /content/:id to poll for status, fields, and body.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "description": "Create new content from a prompt (not optimizing an existing page).", "enum": [ "CREATE" ] }, "promptId": { "type": "string", "format": "uuid", "description": "LLM prompt to anchor generation on (list via GET /prompts)." }, "personaId": { "type": "string", "format": "uuid", "description": "Persona for voice and audience (list via GET /personas)." }, "type": { "type": "string", "enum": [ "ARTICLE", "BLOG_POST", "OPINION", "LISTICLE", "HOW_TO", "REVIEW", "COMPARISON", "CASE_STUDY", "INTERVIEW", "DOCUMENTATION", "WIKI", "PRODUCT_PAGE", "LANDING_PAGE", "PRESS_RELEASE", "GENERIC_CONTENT", "PRODUCT_COMPARISON" ], "description": "Output format. Supports article/blog formats plus on-site citation-aligned formats such as HOW_TO, REVIEW, COMPARISON, CASE_STUDY, DOCUMENTATION, WIKI, PRODUCT_PAGE, LANDING_PAGE, and PRESS_RELEASE." }, "contentLength": { "type": "string", "enum": [ "SHORT", "MEDIUM", "LONG" ], "description": "Target length. SHORT ≈ 200–500 words; MEDIUM ≈ 500–1,000; LONG ≈ 1,000–3,000." }, "contentGapRecommendationId": { "type": "string", "format": "uuid", "description": "Optional recommendation from GET /content-gap/prompts/:promptId/latest/recommendations." }, "toneOfVoice": { "type": "string", "enum": [ "PROFESSIONAL", "CASUAL", "TECHNICAL", "CONVERSATIONAL", "NEUTRAL", "AUTHORITATIVE", "FRIENDLY", "PERSUASIVE", "FORMAL", "WITTY", "CUSTOM" ], "description": "Tone override; if omitted, the project default is used. CUSTOM requires customToneOfVoice." }, "customToneOfVoice": { "type": "string", "description": "Required when toneOfVoice is CUSTOM; ignored otherwise." }, "languageCode": { "type": "string", "enum": [ "en-US", "en-GB", "en-IN", "en-AU", "en-CA", "en-NZ", "nl-NL", "nl-BE", "es-ES", "es-MX", "es-AR", "es-CO", "es-CL", "es-PE", "es-VE", "ca-ES", "fr-FR", "fr-CA", "de-DE", "de-AT", "de-CH", "cs-CZ", "sk-SK", "no-NO", "sv-SE", "da-DK", "it-IT", "fi-FI", "pl-PL", "hu-HU", "ro-RO", "lt-LT", "lv-LV", "uk-UA", "el-GR", "tr-TR", "ar-SA", "ar-EG", "ar-AE", "he-IL", "pt-PT", "pt-BR", "ja-JP", "id-ID", "vi-VN", "th-TH", "km-KH", "en-KH", "ko-KR", "hi-IN", "ru-RU", "kk-KZ", "ms-MY", "fil-PH", "zh-SG", "zh-TW", "zh-HK" ], "description": "BCP-47 language code from the supported enum (e.g. \"en-US\", \"es-ES\"). Overrides the project default. Omit to use the project default or en-US." }, "imageArtisticStyle": { "type": "string", "enum": [ "photo-realistic", "flat-illustration", "watercolor", "3d-render", "minimalist", "isometric", "editorial", "abstract" ], "nullable": true, "description": "Visual style for AI-generated featured images when the generate-article-image tool is enabled. Null inherits the project default." }, "imagePromptInstructions": { "type": "string", "maxLength": 200, "nullable": true, "description": "Additional instructions for the image generator (max 200 chars). Null inherits the project default." }, "blockedWords": { "type": "array", "items": { "type": "string" }, "description": "Words or phrases the generated content must not contain. Overrides the project's default blocked-words list." } }, "required": [ "mode", "promptId", "personaId", "type", "contentLength" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "description": "Rewrite existing site page content; page must be in the project sitemap with markdown.", "enum": [ "OPTIMIZE" ] }, "promptId": { "type": "string", "format": "uuid", "description": "LLM prompt to anchor optimization (list via GET /prompts)." }, "personaId": { "type": "string", "format": "uuid", "description": "Persona for voice and audience (list via GET /personas)." }, "optimizationLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "description": "LOW (Conservative): light edits; MEDIUM (Balanced): rewrite sections; HIGH (Full Rewrite): rebuild for maximum impact." }, "url": { "type": "string", "format": "uri", "description": "Canonical page URL to load from the sitemap / page index." }, "contentGapRecommendationId": { "type": "string", "format": "uuid", "description": "Optional recommendation from GET /content-gap/prompts/:promptId/latest/recommendations." }, "toneOfVoice": { "type": "string", "enum": [ "PROFESSIONAL", "CASUAL", "TECHNICAL", "CONVERSATIONAL", "NEUTRAL", "AUTHORITATIVE", "FRIENDLY", "PERSUASIVE", "FORMAL", "WITTY", "CUSTOM" ], "description": "Tone override; if omitted, project default. CUSTOM requires customToneOfVoice." }, "customToneOfVoice": { "type": "string", "description": "Required when toneOfVoice is CUSTOM." }, "languageCode": { "type": "string", "enum": [ "en-US", "en-GB", "en-IN", "en-AU", "en-CA", "en-NZ", "nl-NL", "nl-BE", "es-ES", "es-MX", "es-AR", "es-CO", "es-CL", "es-PE", "es-VE", "ca-ES", "fr-FR", "fr-CA", "de-DE", "de-AT", "de-CH", "cs-CZ", "sk-SK", "no-NO", "sv-SE", "da-DK", "it-IT", "fi-FI", "pl-PL", "hu-HU", "ro-RO", "lt-LT", "lv-LV", "uk-UA", "el-GR", "tr-TR", "ar-SA", "ar-EG", "ar-AE", "he-IL", "pt-PT", "pt-BR", "ja-JP", "id-ID", "vi-VN", "th-TH", "km-KH", "en-KH", "ko-KR", "hi-IN", "ru-RU", "kk-KZ", "ms-MY", "fil-PH", "zh-SG", "zh-TW", "zh-HK" ], "description": "BCP-47 language code from the supported enum (e.g. \"en-US\", \"es-ES\"). Overrides the project default. Omit to use the project default or en-US." }, "imageArtisticStyle": { "type": "string", "enum": [ "photo-realistic", "flat-illustration", "watercolor", "3d-render", "minimalist", "isometric", "editorial", "abstract" ], "nullable": true, "description": "Visual style for AI-generated featured images when the generate-article-image tool is enabled. Null inherits the project default." }, "imagePromptInstructions": { "type": "string", "maxLength": 200, "nullable": true, "description": "Additional instructions for the image generator (max 200 chars). Null inherits the project default." }, "blockedWords": { "type": "array", "items": { "type": "string" }, "description": "Words or phrases the generated content must not contain. Overrides the project's default blocked-words list." } }, "required": [ "mode", "promptId", "personaId", "optimizationLevel", "url" ], "additionalProperties": false } ] } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "6ba7b82c-9dad-11d1-80b4-00c04fd430c8", "status": "PENDING" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Document id; poll GET /content/:id until terminal status." }, "status": { "type": "string", "enum": [ "PENDING" ], "description": "Always PENDING immediately after enqueue; use GET /content/:id for updates." } }, "required": [ "id", "status" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "CONTENT_NOT_FOUND", "message": "Content document not found" }, "properties": { "code": { "type": "string", "description": "Machine-readable error code", "enum": [ "CONTENT_NOT_FOUND", "CONTENT_DRAFT_NOT_FOUND", "CONTENT_INVALID_PROMPT", "CONTENT_INVALID_PERSONA", "CONTENT_PAGE_FETCH_FAILED", "CONTENT_PAGE_NOT_FOUND", "CONTENT_PAGE_NO_CONTENT", "CONTENT_INVALID_TONE", "CONTENT_RECOMMENDATION_NOT_FOUND", "CONTENT_GENERATION_FAILED", "INTERNAL_ERROR" ], "example": "CONTENT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Content document not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "CONTENT_NOT_FOUND", "message": "Content document not found" } }, "example2": { "value": { "code": "CONTENT_INVALID_PROMPT", "message": "Prompt not found or does not belong to this project" } }, "example3": { "value": { "code": "CONTENT_GENERATION_FAILED", "message": "Failed to start content generation" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "402": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Payment Required", "message": "Cannot create prompt. Your organization has 50 of 50 active prompts. Please upgrade your plan to continue.", "current": 50, "limit": 50, "available": 0 }, "properties": { "error": { "type": "string", "description": "Fixed error label", "enum": [ "Payment Required" ] }, "message": { "type": "string", "description": "Explanation including usage and limit" }, "current": { "type": "integer", "description": "Current usage for this quota" }, "limit": { "type": "integer", "description": "Maximum allowed on the current plan" }, "available": { "type": "integer", "description": "Remaining quota (0 when blocked)" } }, "required": [ "error", "message", "current", "limit", "available" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "CONTENT_NOT_FOUND", "message": "Content document not found" }, "properties": { "code": { "type": "string", "description": "Machine-readable error code", "enum": [ "CONTENT_NOT_FOUND", "CONTENT_DRAFT_NOT_FOUND", "CONTENT_INVALID_PROMPT", "CONTENT_INVALID_PERSONA", "CONTENT_PAGE_FETCH_FAILED", "CONTENT_PAGE_NOT_FOUND", "CONTENT_PAGE_NO_CONTENT", "CONTENT_INVALID_TONE", "CONTENT_RECOMMENDATION_NOT_FOUND", "CONTENT_GENERATION_FAILED", "INTERNAL_ERROR" ], "example": "CONTENT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Content document not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "CONTENT_NOT_FOUND", "message": "Content document not found" } }, "example2": { "value": { "code": "CONTENT_INVALID_PROMPT", "message": "Prompt not found or does not belong to this project" } }, "example3": { "value": { "code": "CONTENT_GENERATION_FAILED", "message": "Failed to start content generation" } } } } } } } } }, "/content/{id}": { "get": { "operationId": "getContent", "summary": "Get content by id", "tags": [ "Content" ], "description": "Returns one content document by id (status, body, and metadata). Use after POST /content/create to poll until generation finishes; see response field descriptions for partial vs final content.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Document id from create response." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "6ba7b82c-9dad-11d1-80b4-00c04fd430c8", "status": "IN_PROGRESS", "mode": "CREATE", "type": "ARTICLE", "title": "Illustrative draft title", "promptId": "6ba7b823-9dad-11d1-80b4-00c04fd430c8", "prompt": "Best CRM for 50-person services firms?", "description": "Short brief for writers (illustrative).", "content": "## Section\n\nPartial markdown body…", "contentLength": "MEDIUM", "optimizationLevel": null, "url": null, "toneOfVoice": "PROFESSIONAL", "customToneOfVoice": null, "languageCode": "en-US", "imageArtisticStyle": null, "imagePromptInstructions": null, "blockedWords": [], "createdAt": "2026-03-29T14:00:00.000Z", "updatedAt": "2026-03-29T14:05:00.000Z", "startedAt": "2026-03-29T14:00:30.000Z", "completedAt": null, "failedAt": null, "failedReason": null, "stoppedAt": null }, "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "DRAFT", "PENDING", "IN_PROGRESS", "COMPLETED", "FAILED", "STOPPED" ], "description": "PENDING: queued for generation; IN_PROGRESS: AI is actively generating content; COMPLETED: generation finished successfully; FAILED: generation encountered an error; STOPPED: generation was manually stopped by the user (may contain partial content)." }, "mode": { "type": "string", "enum": [ "CREATE", "OPTIMIZE" ] }, "type": { "type": "string", "enum": [ "ARTICLE", "BLOG_POST", "OPINION", "LISTICLE", "HOW_TO", "REVIEW", "COMPARISON", "CASE_STUDY", "INTERVIEW", "DOCUMENTATION", "WIKI", "PRODUCT_PAGE", "LANDING_PAGE", "PRESS_RELEASE", "GENERIC_CONTENT", "PRODUCT_COMPARISON" ], "nullable": true, "description": "Set for CREATE mode." }, "title": { "type": "string", "nullable": true, "description": "Document title. Null while PENDING; may appear during IN_PROGRESS as a partial or working title; final once COMPLETED." }, "promptId": { "type": "string", "format": "uuid", "nullable": true, "description": "Linked monitor prompt id (same as POST /content/create `promptId`)." }, "prompt": { "type": "string", "nullable": true, "description": "Linked LLM prompt text from GET /prompts; null if the prompt was removed." }, "description": { "type": "string", "nullable": true }, "content": { "type": "string", "nullable": true, "description": "Markdown body. Null while PENDING; partially written during IN_PROGRESS (content streams in progressively and is incomplete); final once COMPLETED. STOPPED documents may contain partial content." }, "contentLength": { "type": "string", "enum": [ "SHORT", "MEDIUM", "LONG" ], "nullable": true }, "optimizationLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "nullable": true }, "url": { "type": "string", "format": "uri", "nullable": true, "description": "Optimize target URL (OPTIMIZE mode)." }, "toneOfVoice": { "type": "string", "enum": [ "PROFESSIONAL", "CASUAL", "TECHNICAL", "CONVERSATIONAL", "NEUTRAL", "AUTHORITATIVE", "FRIENDLY", "PERSUASIVE", "FORMAL", "WITTY", "CUSTOM" ], "nullable": true }, "customToneOfVoice": { "type": "string", "nullable": true }, "languageCode": { "type": "string", "enum": [ "en-US", "en-GB", "en-IN", "en-AU", "en-CA", "en-NZ", "nl-NL", "nl-BE", "es-ES", "es-MX", "es-AR", "es-CO", "es-CL", "es-PE", "es-VE", "ca-ES", "fr-FR", "fr-CA", "de-DE", "de-AT", "de-CH", "cs-CZ", "sk-SK", "no-NO", "sv-SE", "da-DK", "it-IT", "fi-FI", "pl-PL", "hu-HU", "ro-RO", "lt-LT", "lv-LV", "uk-UA", "el-GR", "tr-TR", "ar-SA", "ar-EG", "ar-AE", "he-IL", "pt-PT", "pt-BR", "ja-JP", "id-ID", "vi-VN", "th-TH", "km-KH", "en-KH", "ko-KR", "hi-IN", "ru-RU", "kk-KZ", "ms-MY", "fil-PH", "zh-SG", "zh-TW", "zh-HK" ], "nullable": true }, "imageArtisticStyle": { "type": "string", "enum": [ "photo-realistic", "flat-illustration", "watercolor", "3d-render", "minimalist", "isometric", "editorial", "abstract" ], "nullable": true }, "imagePromptInstructions": { "type": "string", "nullable": true }, "blockedWords": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "failedAt": { "type": "string", "format": "date-time", "nullable": true }, "failedReason": { "type": "string", "nullable": true }, "stoppedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "status", "mode", "type", "title", "promptId", "prompt", "description", "content", "contentLength", "optimizationLevel", "url", "toneOfVoice", "customToneOfVoice", "languageCode", "imageArtisticStyle", "imagePromptInstructions", "blockedWords", "createdAt", "updatedAt", "startedAt", "completedAt", "failedAt", "failedReason", "stoppedAt" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "CONTENT_NOT_FOUND", "message": "Content document not found" }, "properties": { "code": { "type": "string", "description": "Machine-readable error code", "enum": [ "CONTENT_NOT_FOUND", "CONTENT_DRAFT_NOT_FOUND", "CONTENT_INVALID_PROMPT", "CONTENT_INVALID_PERSONA", "CONTENT_PAGE_FETCH_FAILED", "CONTENT_PAGE_NOT_FOUND", "CONTENT_PAGE_NO_CONTENT", "CONTENT_INVALID_TONE", "CONTENT_RECOMMENDATION_NOT_FOUND", "CONTENT_GENERATION_FAILED", "INTERNAL_ERROR" ], "example": "CONTENT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Content document not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "CONTENT_NOT_FOUND", "message": "Content document not found" } }, "example2": { "value": { "code": "CONTENT_INVALID_PROMPT", "message": "Prompt not found or does not belong to this project" } }, "example3": { "value": { "code": "CONTENT_GENERATION_FAILED", "message": "Failed to start content generation" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "CONTENT_NOT_FOUND", "message": "Content document not found" }, "properties": { "code": { "type": "string", "description": "Machine-readable error code", "enum": [ "CONTENT_NOT_FOUND", "CONTENT_DRAFT_NOT_FOUND", "CONTENT_INVALID_PROMPT", "CONTENT_INVALID_PERSONA", "CONTENT_PAGE_FETCH_FAILED", "CONTENT_PAGE_NOT_FOUND", "CONTENT_PAGE_NO_CONTENT", "CONTENT_INVALID_TONE", "CONTENT_RECOMMENDATION_NOT_FOUND", "CONTENT_GENERATION_FAILED", "INTERNAL_ERROR" ], "example": "CONTENT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Content document not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "CONTENT_NOT_FOUND", "message": "Content document not found" } }, "example2": { "value": { "code": "CONTENT_INVALID_PROMPT", "message": "Prompt not found or does not belong to this project" } }, "example3": { "value": { "code": "CONTENT_GENERATION_FAILED", "message": "Failed to start content generation" } } } } } } } } }, "/models": { "get": { "operationId": "listModels", "summary": "List Models", "tags": [ "Models" ], "description": "List all available LLM models supported by Promptwatch", "parameters": [ { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeDeprecated", "required": false, "description": "Include deprecated models in the response" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "models": [ { "id": "gpt-4.1", "label": "GPT-4.1", "provider": "openai", "providerName": "OpenAI", "modelName": "GPT-4.1", "apiIdentifier": "gpt-4.1", "description": "Illustrative catalog row for OpenAPI docs only.", "searchEnabled": true, "liveSearch": true, "deprecated": false }, { "id": "claude-sonnet-4-20250514", "label": "Claude Sonnet 4", "provider": "anthropic", "providerName": "Anthropic", "modelName": "Claude Sonnet 4", "apiIdentifier": "claude-sonnet-4-20250514", "description": "Illustrative catalog row for OpenAPI docs only.", "searchEnabled": true, "liveSearch": false, "deprecated": false } ], "total": 2 }, "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Model ID" }, "label": { "type": "string", "description": "Human-readable model label" }, "provider": { "type": "string", "description": "Provider identifier (e.g., openai, anthropic)" }, "providerName": { "type": "string", "description": "Human-readable provider name" }, "modelName": { "type": "string", "description": "Model name" }, "apiIdentifier": { "type": "string", "description": "API identifier for the model" }, "description": { "type": "string", "description": "Model description" }, "searchEnabled": { "type": "boolean", "description": "Whether search is enabled for this model" }, "liveSearch": { "type": "boolean", "description": "Whether this model supports live search" }, "deprecated": { "type": "boolean", "description": "Whether the model is deprecated" } }, "required": [ "id", "label", "provider", "providerName", "modelName", "apiIdentifier", "description" ] }, "description": "List of available models" }, "total": { "type": "integer", "description": "Total number of models returned" } }, "required": [ "models", "total" ] } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/monitors": { "get": { "operationId": "listMonitors", "summary": "List Monitors", "tags": [ "Monitors" ], "description": "Get all active monitors for the current project with average visibility and response counts in a date range", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date (YYYY-MM-DD). Defaults to 7 days ago." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date (YYYY-MM-DD). Defaults to today." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "example": [ { "id": "6ba7b818-9dad-11d1-80b4-00c04fd430c8", "name": "North America — core keywords", "description": "Illustrative monitor for API docs only.", "active": true, "models": [ "openai/gpt-4.1", "anthropic/claude-sonnet-4-20250514" ], "languageCode": "en-US", "countryCode": "US", "promptCount": 48, "responseCount": 620, "responseCountInRange": 92, "averageVisibility": 54.25, "personaName": "Marketing manager", "personaDescription": null, "personaAgeRange": null, "personaEducationLevel": null, "createdAt": "2026-01-12T10:00:00.000Z", "updatedAt": "2026-03-30T09:30:00.000Z" }, { "id": "6ba7b819-9dad-11d1-80b4-00c04fd430c8", "name": "EU — localized prompts", "description": null, "active": true, "models": [ "openai/gpt-4.1-mini" ], "languageCode": "en-GB", "countryCode": "GB", "promptCount": 22, "responseCount": 180, "responseCountInRange": 44, "averageVisibility": 47.9, "personaName": null, "personaDescription": null, "personaAgeRange": null, "personaEducationLevel": null, "createdAt": "2026-02-01T11:00:00.000Z", "updatedAt": "2026-03-29T16:45:00.000Z" } ], "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Monitor unique identifier" }, "name": { "type": "string", "description": "Monitor name" }, "description": { "type": "string", "nullable": true, "description": "Monitor description" }, "active": { "type": "boolean", "description": "Whether the monitor is active" }, "models": { "type": "array", "items": { "type": "string" }, "description": "List of LLM models being monitored" }, "languageCode": { "type": "string", "description": "Language code for the monitor" }, "countryCode": { "type": "string", "description": "Country code for the monitor" }, "promptCount": { "type": "number", "description": "Number of prompts in this monitor" }, "responseCount": { "type": "number", "description": "Total number of responses across all prompts" }, "responseCountInRange": { "type": "number", "description": "Number of responses created within the selected date range" }, "averageVisibility": { "type": "number", "nullable": false, "description": "Average visibility score for the monitor within the selected date range" }, "personaName": { "type": "string", "nullable": true, "description": "Persona name used for the monitor" }, "personaDescription": { "type": "string", "nullable": true, "description": "Persona description" }, "personaAgeRange": { "type": "string", "nullable": true, "description": "Persona age range" }, "personaEducationLevel": { "type": "string", "nullable": true, "description": "Persona education level" }, "createdAt": { "type": "string", "format": "date-time", "description": "Monitor creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Monitor last update timestamp" } }, "required": [ "id", "name", "active", "models", "languageCode", "countryCode", "promptCount", "responseCount", "averageVisibility", "createdAt", "updatedAt" ], "additionalProperties": false } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "MONITOR_NOT_FOUND", "MONITOR_FORBIDDEN", "MONITOR_INVALID_PERSONA", "PROMPT_BATCH_LIMIT_REACHED", "INTERNAL_ERROR" ], "example": "MONITOR_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Monitor not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" } }, "example2": { "value": { "code": "MONITOR_FORBIDDEN", "message": "Not authorized to access this monitor" } }, "example3": { "value": { "code": "MONITOR_INVALID_PERSONA", "message": "Invalid persona or persona does not belong to this project" } }, "example4": { "value": { "code": "PROMPT_BATCH_LIMIT_REACHED", "message": "generatePrompts total amount cannot exceed 50 per request" } }, "example5": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } }, "post": { "operationId": "createMonitor", "summary": "Create Monitor", "tags": [ "Monitors" ], "description": "Create a new monitor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "models" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Monitor name" }, "description": { "type": "string", "nullable": true, "description": "Monitor description" }, "models": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "List of LLM models to monitor" }, "languageCode": { "type": "string", "default": "en-US", "description": "Language code" }, "countryCode": { "type": "string", "default": "US", "description": "Country code" }, "stateCode": { "type": "string", "nullable": true, "description": "State code" }, "cityCode": { "type": "string", "nullable": true, "description": "City code" }, "personaId": { "type": "string", "format": "uuid", "nullable": true, "description": "Persona ID" }, "initialPrompts": { "type": "array", "items": { "type": "object", "required": [ "prompt", "type", "intent", "keywords" ], "properties": { "prompt": { "type": "string" }, "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, "intent": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "TRANSACTIONAL", "NAVIGATIONAL", "COMMERCIAL" ] }, "keywords": { "type": "array", "items": { "type": "string" } } } }, "description": "Initial prompts to create with the monitor" }, "generatePrompts": { "type": "array", "maxItems": 3, "items": { "type": "object", "additionalProperties": false, "required": [ "amount" ], "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Number of prompts to generate in this batch (1-50)" }, "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ], "description": "Optional bias for the prompt type the generator should favor" }, "instructions": { "type": "string", "maxLength": 500, "description": "Optional free-form steering for this batch (max 500 chars)" } } }, "description": "Optional array of generation batches (max 3, one per prompt type). Each entry triggers one independent call to the prompt generator (batches run in parallel; no prompt text from other batches or from initialPrompts is passed as context). Per-entry amount is 1-50; the sum across all entries must also be <= 50." } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "example": { "id": "6ba7b818-9dad-11d1-80b4-00c04fd430c8", "name": "North America — core keywords", "description": "Illustrative monitor for API docs only.", "active": true, "models": [ "openai/gpt-4.1", "anthropic/claude-sonnet-4-20250514" ], "languageCode": "en-US", "countryCode": "US", "promptCount": 48, "responseCount": 620, "responseCountInRange": 92, "averageVisibility": 54.25, "personaName": "Marketing manager", "personaDescription": null, "personaAgeRange": null, "personaEducationLevel": null, "createdAt": "2026-01-12T10:00:00.000Z", "updatedAt": "2026-03-30T09:30:00.000Z" }, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Monitor unique identifier" }, "name": { "type": "string", "description": "Monitor name" }, "description": { "type": "string", "nullable": true, "description": "Monitor description" }, "active": { "type": "boolean", "description": "Whether the monitor is active" }, "models": { "type": "array", "items": { "type": "string" }, "description": "List of LLM models being monitored" }, "languageCode": { "type": "string", "description": "Language code for the monitor" }, "countryCode": { "type": "string", "description": "Country code for the monitor" }, "promptCount": { "type": "number", "description": "Number of prompts in this monitor" }, "responseCount": { "type": "number", "description": "Total number of responses across all prompts" }, "responseCountInRange": { "type": "number", "description": "Number of responses created within the selected date range" }, "averageVisibility": { "type": "number", "nullable": false, "description": "Average visibility score for the monitor within the selected date range" }, "personaName": { "type": "string", "nullable": true, "description": "Persona name used for the monitor" }, "personaDescription": { "type": "string", "nullable": true, "description": "Persona description" }, "personaAgeRange": { "type": "string", "nullable": true, "description": "Persona age range" }, "personaEducationLevel": { "type": "string", "nullable": true, "description": "Persona education level" }, "createdAt": { "type": "string", "format": "date-time", "description": "Monitor creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Monitor last update timestamp" } }, "required": [ "id", "name", "active", "models", "languageCode", "countryCode", "promptCount", "responseCount", "averageVisibility", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "MONITOR_NOT_FOUND", "MONITOR_FORBIDDEN", "MONITOR_INVALID_PERSONA", "PROMPT_BATCH_LIMIT_REACHED", "INTERNAL_ERROR" ], "example": "MONITOR_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Monitor not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" } }, "example2": { "value": { "code": "MONITOR_FORBIDDEN", "message": "Not authorized to access this monitor" } }, "example3": { "value": { "code": "MONITOR_INVALID_PERSONA", "message": "Invalid persona or persona does not belong to this project" } }, "example4": { "value": { "code": "PROMPT_BATCH_LIMIT_REACHED", "message": "generatePrompts total amount cannot exceed 50 per request" } }, "example5": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "402": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Payment Required", "message": "Cannot create prompt. Your organization has 50 of 50 active prompts. Please upgrade your plan to continue.", "current": 50, "limit": 50, "available": 0 }, "properties": { "error": { "type": "string", "description": "Fixed error label", "enum": [ "Payment Required" ] }, "message": { "type": "string", "description": "Explanation including usage and limit" }, "current": { "type": "integer", "description": "Current usage for this quota" }, "limit": { "type": "integer", "description": "Maximum allowed on the current plan" }, "available": { "type": "integer", "description": "Remaining quota (0 when blocked)" } }, "required": [ "error", "message", "current", "limit", "available" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "MONITOR_NOT_FOUND", "MONITOR_FORBIDDEN", "MONITOR_INVALID_PERSONA", "PROMPT_BATCH_LIMIT_REACHED", "INTERNAL_ERROR" ], "example": "MONITOR_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Monitor not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" } }, "example2": { "value": { "code": "MONITOR_FORBIDDEN", "message": "Not authorized to access this monitor" } }, "example3": { "value": { "code": "MONITOR_INVALID_PERSONA", "message": "Invalid persona or persona does not belong to this project" } }, "example4": { "value": { "code": "PROMPT_BATCH_LIMIT_REACHED", "message": "generatePrompts total amount cannot exceed 50 per request" } }, "example5": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/monitors/{id}": { "get": { "operationId": "getMonitor", "summary": "Get Monitor", "tags": [ "Monitors" ], "description": "Get a single monitor by ID with full details", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date (YYYY-MM-DD). Defaults to 7 days ago." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date (YYYY-MM-DD). Defaults to today." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Monitor ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "example": { "id": "6ba7b818-9dad-11d1-80b4-00c04fd430c8", "name": "North America — core keywords", "description": "Illustrative monitor for API docs only.", "active": true, "models": [ "openai/gpt-4.1", "anthropic/claude-sonnet-4-20250514" ], "languageCode": "en-US", "countryCode": "US", "promptCount": 48, "responseCount": 620, "responseCountInRange": 92, "averageVisibility": 54.25, "personaName": "Marketing manager", "personaDescription": null, "personaAgeRange": null, "personaEducationLevel": null, "createdAt": "2026-01-12T10:00:00.000Z", "updatedAt": "2026-03-30T09:30:00.000Z" }, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Monitor unique identifier" }, "name": { "type": "string", "description": "Monitor name" }, "description": { "type": "string", "nullable": true, "description": "Monitor description" }, "active": { "type": "boolean", "description": "Whether the monitor is active" }, "models": { "type": "array", "items": { "type": "string" }, "description": "List of LLM models being monitored" }, "languageCode": { "type": "string", "description": "Language code for the monitor" }, "countryCode": { "type": "string", "description": "Country code for the monitor" }, "promptCount": { "type": "number", "description": "Number of prompts in this monitor" }, "responseCount": { "type": "number", "description": "Total number of responses across all prompts" }, "responseCountInRange": { "type": "number", "description": "Number of responses created within the selected date range" }, "averageVisibility": { "type": "number", "nullable": false, "description": "Average visibility score for the monitor within the selected date range" }, "personaName": { "type": "string", "nullable": true, "description": "Persona name used for the monitor" }, "personaDescription": { "type": "string", "nullable": true, "description": "Persona description" }, "personaAgeRange": { "type": "string", "nullable": true, "description": "Persona age range" }, "personaEducationLevel": { "type": "string", "nullable": true, "description": "Persona education level" }, "createdAt": { "type": "string", "format": "date-time", "description": "Monitor creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Monitor last update timestamp" } }, "required": [ "id", "name", "active", "models", "languageCode", "countryCode", "promptCount", "responseCount", "averageVisibility", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "MONITOR_NOT_FOUND", "MONITOR_FORBIDDEN", "MONITOR_INVALID_PERSONA", "PROMPT_BATCH_LIMIT_REACHED", "INTERNAL_ERROR" ], "example": "MONITOR_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Monitor not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" } }, "example2": { "value": { "code": "MONITOR_FORBIDDEN", "message": "Not authorized to access this monitor" } }, "example3": { "value": { "code": "MONITOR_INVALID_PERSONA", "message": "Invalid persona or persona does not belong to this project" } }, "example4": { "value": { "code": "PROMPT_BATCH_LIMIT_REACHED", "message": "generatePrompts total amount cannot exceed 50 per request" } }, "example5": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "MONITOR_NOT_FOUND", "MONITOR_FORBIDDEN", "MONITOR_INVALID_PERSONA", "PROMPT_BATCH_LIMIT_REACHED", "INTERNAL_ERROR" ], "example": "MONITOR_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Monitor not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" } }, "example2": { "value": { "code": "MONITOR_FORBIDDEN", "message": "Not authorized to access this monitor" } }, "example3": { "value": { "code": "MONITOR_INVALID_PERSONA", "message": "Invalid persona or persona does not belong to this project" } }, "example4": { "value": { "code": "PROMPT_BATCH_LIMIT_REACHED", "message": "generatePrompts total amount cannot exceed 50 per request" } }, "example5": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "MONITOR_NOT_FOUND", "MONITOR_FORBIDDEN", "MONITOR_INVALID_PERSONA", "PROMPT_BATCH_LIMIT_REACHED", "INTERNAL_ERROR" ], "example": "MONITOR_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Monitor not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" } }, "example2": { "value": { "code": "MONITOR_FORBIDDEN", "message": "Not authorized to access this monitor" } }, "example3": { "value": { "code": "MONITOR_INVALID_PERSONA", "message": "Invalid persona or persona does not belong to this project" } }, "example4": { "value": { "code": "PROMPT_BATCH_LIMIT_REACHED", "message": "generatePrompts total amount cannot exceed 50 per request" } }, "example5": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } }, "put": { "operationId": "updateMonitor", "summary": "Update Monitor", "tags": [ "Monitors" ], "description": "Update an existing monitor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Monitor name" }, "description": { "type": "string", "nullable": true, "description": "Monitor description" }, "models": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "List of LLM models to monitor" }, "active": { "type": "boolean", "description": "Whether the monitor is active" }, "languageCode": { "type": "string", "description": "Language code" }, "countryCode": { "type": "string", "description": "Country code" }, "stateCode": { "type": "string", "nullable": true, "description": "State code" }, "cityCode": { "type": "string", "nullable": true, "description": "City code" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Monitor ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "example": { "id": "6ba7b818-9dad-11d1-80b4-00c04fd430c8", "name": "North America — core keywords", "description": "Illustrative monitor for API docs only.", "active": true, "models": [ "openai/gpt-4.1", "anthropic/claude-sonnet-4-20250514" ], "languageCode": "en-US", "countryCode": "US", "promptCount": 48, "responseCount": 620, "responseCountInRange": 92, "averageVisibility": 54.25, "personaName": "Marketing manager", "personaDescription": null, "personaAgeRange": null, "personaEducationLevel": null, "createdAt": "2026-01-12T10:00:00.000Z", "updatedAt": "2026-03-30T09:30:00.000Z" }, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Monitor unique identifier" }, "name": { "type": "string", "description": "Monitor name" }, "description": { "type": "string", "nullable": true, "description": "Monitor description" }, "active": { "type": "boolean", "description": "Whether the monitor is active" }, "models": { "type": "array", "items": { "type": "string" }, "description": "List of LLM models being monitored" }, "languageCode": { "type": "string", "description": "Language code for the monitor" }, "countryCode": { "type": "string", "description": "Country code for the monitor" }, "promptCount": { "type": "number", "description": "Number of prompts in this monitor" }, "responseCount": { "type": "number", "description": "Total number of responses across all prompts" }, "responseCountInRange": { "type": "number", "description": "Number of responses created within the selected date range" }, "averageVisibility": { "type": "number", "nullable": false, "description": "Average visibility score for the monitor within the selected date range" }, "personaName": { "type": "string", "nullable": true, "description": "Persona name used for the monitor" }, "personaDescription": { "type": "string", "nullable": true, "description": "Persona description" }, "personaAgeRange": { "type": "string", "nullable": true, "description": "Persona age range" }, "personaEducationLevel": { "type": "string", "nullable": true, "description": "Persona education level" }, "createdAt": { "type": "string", "format": "date-time", "description": "Monitor creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Monitor last update timestamp" } }, "required": [ "id", "name", "active", "models", "languageCode", "countryCode", "promptCount", "responseCount", "averageVisibility", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "MONITOR_NOT_FOUND", "MONITOR_FORBIDDEN", "MONITOR_INVALID_PERSONA", "PROMPT_BATCH_LIMIT_REACHED", "INTERNAL_ERROR" ], "example": "MONITOR_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Monitor not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" } }, "example2": { "value": { "code": "MONITOR_FORBIDDEN", "message": "Not authorized to access this monitor" } }, "example3": { "value": { "code": "MONITOR_INVALID_PERSONA", "message": "Invalid persona or persona does not belong to this project" } }, "example4": { "value": { "code": "PROMPT_BATCH_LIMIT_REACHED", "message": "generatePrompts total amount cannot exceed 50 per request" } }, "example5": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "402": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Payment Required", "message": "Cannot create prompt. Your organization has 50 of 50 active prompts. Please upgrade your plan to continue.", "current": 50, "limit": 50, "available": 0 }, "properties": { "error": { "type": "string", "description": "Fixed error label", "enum": [ "Payment Required" ] }, "message": { "type": "string", "description": "Explanation including usage and limit" }, "current": { "type": "integer", "description": "Current usage for this quota" }, "limit": { "type": "integer", "description": "Maximum allowed on the current plan" }, "available": { "type": "integer", "description": "Remaining quota (0 when blocked)" } }, "required": [ "error", "message", "current", "limit", "available" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "MONITOR_NOT_FOUND", "MONITOR_FORBIDDEN", "MONITOR_INVALID_PERSONA", "PROMPT_BATCH_LIMIT_REACHED", "INTERNAL_ERROR" ], "example": "MONITOR_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Monitor not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" } }, "example2": { "value": { "code": "MONITOR_FORBIDDEN", "message": "Not authorized to access this monitor" } }, "example3": { "value": { "code": "MONITOR_INVALID_PERSONA", "message": "Invalid persona or persona does not belong to this project" } }, "example4": { "value": { "code": "PROMPT_BATCH_LIMIT_REACHED", "message": "generatePrompts total amount cannot exceed 50 per request" } }, "example5": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "MONITOR_NOT_FOUND", "MONITOR_FORBIDDEN", "MONITOR_INVALID_PERSONA", "PROMPT_BATCH_LIMIT_REACHED", "INTERNAL_ERROR" ], "example": "MONITOR_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Monitor not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" } }, "example2": { "value": { "code": "MONITOR_FORBIDDEN", "message": "Not authorized to access this monitor" } }, "example3": { "value": { "code": "MONITOR_INVALID_PERSONA", "message": "Invalid persona or persona does not belong to this project" } }, "example4": { "value": { "code": "PROMPT_BATCH_LIMIT_REACHED", "message": "generatePrompts total amount cannot exceed 50 per request" } }, "example5": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } }, "delete": { "operationId": "deleteMonitor", "summary": "Delete Monitor", "tags": [ "Monitors" ], "description": "Soft-delete a monitor", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Monitor ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "Default Response" }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "MONITOR_NOT_FOUND", "MONITOR_FORBIDDEN", "MONITOR_INVALID_PERSONA", "PROMPT_BATCH_LIMIT_REACHED", "INTERNAL_ERROR" ], "example": "MONITOR_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Monitor not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" } }, "example2": { "value": { "code": "MONITOR_FORBIDDEN", "message": "Not authorized to access this monitor" } }, "example3": { "value": { "code": "MONITOR_INVALID_PERSONA", "message": "Invalid persona or persona does not belong to this project" } }, "example4": { "value": { "code": "PROMPT_BATCH_LIMIT_REACHED", "message": "generatePrompts total amount cannot exceed 50 per request" } }, "example5": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "MONITOR_NOT_FOUND", "MONITOR_FORBIDDEN", "MONITOR_INVALID_PERSONA", "PROMPT_BATCH_LIMIT_REACHED", "INTERNAL_ERROR" ], "example": "MONITOR_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Monitor not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "MONITOR_NOT_FOUND", "message": "Monitor not found" } }, "example2": { "value": { "code": "MONITOR_FORBIDDEN", "message": "Not authorized to access this monitor" } }, "example3": { "value": { "code": "MONITOR_INVALID_PERSONA", "message": "Invalid persona or persona does not belong to this project" } }, "example4": { "value": { "code": "PROMPT_BATCH_LIMIT_REACHED", "message": "generatePrompts total amount cannot exceed 50 per request" } }, "example5": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/page-tracker": { "get": { "operationId": "listTrackedPages", "summary": "List Tracked Pages", "tags": [ "Page Tracker" ], "description": "List tracked pages for the project with optional URL search", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number (1-based)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "in": "query", "name": "size", "required": false, "description": "Page size" }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false, "description": "Filter by URL substring" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "pages": [ { "id": "6ba7b822-9dad-11d1-80b4-00c04fd430c8", "url": "https://example.com/pricing", "title": "Pricing", "domainName": "example.com", "createdAt": "2026-03-15T10:00:00.000Z" } ], "total": 1, "page": 1, "size": 10, "totalPages": 1 }, "properties": { "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Tracked page identifier" }, "url": { "type": "string", "description": "Canonical page URL" }, "title": { "type": "string", "nullable": true, "description": "Page title" }, "domainName": { "type": "string", "description": "Page domain" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp (ISO 8601)" } }, "required": [ "id", "url", "title", "domainName", "createdAt" ], "additionalProperties": false }, "description": "Tracked pages for the project" }, "total": { "type": "integer", "description": "Total items matching the request" }, "page": { "type": "integer", "description": "Page number (1-based)" }, "size": { "type": "integer", "description": "Page size" }, "totalPages": { "type": "integer", "description": "Total pages for this page size" } }, "required": [ "pages", "total", "page", "size", "totalPages" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TRACKED_PAGE_NOT_FOUND", "message": "Tracked page not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TRACKED_PAGE_NOT_FOUND", "TRACKED_PAGE_ALREADY_EXISTS", "DATE_RANGE_IN_FUTURE", "INTERNAL_ERROR" ], "example": "TRACKED_PAGE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Tracked page not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } }, "post": { "operationId": "addTrackedPages", "summary": "Add Tracked Pages", "tags": [ "Page Tracker" ], "description": "Track one or more URLs. Returns a structured result with added, skipped (already tracked), and failed (invalid URL) arrays. Responds 207 Multi-Status to reflect mixed per-URL outcomes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "urls" ], "properties": { "urls": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "description": "URLs to track (max 100 per request). Invalid URLs are captured in the failed[] array rather than rejected." } }, "additionalProperties": false } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "207": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "added": [ { "url": "https://example.com/pricing", "urlId": "6ba7b822-9dad-11d1-80b4-00c04fd430c8", "trackedPageId": "7ca8c933-abad-22e2-91c5-11d15ge541d9" } ], "skipped": [ { "url": "https://example.com/about", "reason": "ALREADY_EXISTS" } ], "failed": [ { "url": "not-a-url", "reason": "INVALID_URL" } ] }, "properties": { "added": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The canonical URL that was added" }, "urlId": { "type": "string", "description": "Internal URL identifier" }, "trackedPageId": { "type": "string", "description": "Tracked page identifier (use for GET/:id, DELETE/:id)" } }, "required": [ "url", "urlId", "trackedPageId" ], "additionalProperties": false }, "description": "URLs successfully added to tracking" }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL that was skipped" }, "reason": { "type": "string", "enum": [ "ALREADY_EXISTS" ], "description": "Reason the URL was skipped" } }, "required": [ "url", "reason" ], "additionalProperties": false }, "description": "URLs already tracked by this project" }, "failed": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL that failed" }, "reason": { "type": "string", "enum": [ "INVALID_URL" ], "description": "Reason the URL failed" } }, "required": [ "url", "reason" ], "additionalProperties": false }, "description": "URLs that could not be tracked" } }, "required": [ "added", "skipped", "failed" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TRACKED_PAGE_NOT_FOUND", "message": "Tracked page not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TRACKED_PAGE_NOT_FOUND", "TRACKED_PAGE_ALREADY_EXISTS", "DATE_RANGE_IN_FUTURE", "INTERNAL_ERROR" ], "example": "TRACKED_PAGE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Tracked page not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/page-tracker/{id}/responses": { "get": { "operationId": "listTrackedPageResponses", "summary": "List Tracked Page Responses", "tags": [ "Page Tracker" ], "description": "Paginated responses that cited this tracked page. Date range uses inclusive UTC calendar days. When both startDate and endDate are omitted, the default range is today only (00:00:00.000Z through 23:59:59.999Z on the current UTC date). When only one bound is omitted, the missing bound defaults to today.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number (1-based)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "in": "query", "name": "size", "required": false, "description": "Page size" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "First inclusive UTC calendar day (YYYY-MM-DD). Defaults to today when omitted. Future dates return 400 DATE_RANGE_IN_FUTURE." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "Last inclusive UTC calendar day (YYYY-MM-DD). Defaults to today when omitted. Future dates return 400 DATE_RANGE_IN_FUTURE." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tracked page identifier" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "responses": [ { "id": "550e8400-e29b-41d4-a716-446655440003", "content": "Illustrative snippet of model output…", "model": "claude-sonnet-4-20250514", "provider": "anthropic", "visibilityScore": 65, "sentimentScore": null, "sentiment": "NEUTRAL", "toneOfVoice": null, "mentionedOurBrand": false, "competitorMentions": [], "citationCount": 0, "prompt": { "id": "6ba7b816-9dad-11d1-80b4-00c04fd430c8", "prompt": "How do I export a weekly visibility report?", "type": "BRAND_SPECIFIC", "intent": "INFORMATIONAL", "llmMonitor": { "id": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "name": "US English monitor" } }, "createdAt": "2026-03-28T10:00:00.000Z" } ], "total": 128, "page": 1, "size": 10, "totalPages": 13 }, "properties": { "responses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "LLM response identifier" }, "content": { "type": "string", "description": "The LLM response content" }, "model": { "type": "string", "description": "Model used for this response" }, "provider": { "type": "string", "description": "LLM provider" }, "visibilityScore": { "type": "number", "nullable": true, "description": "Visibility score for this response" }, "sentimentScore": { "type": "number", "nullable": true, "description": "Sentiment score for this response" }, "sentiment": { "type": "string", "enum": [ "POSITIVE", "NEGATIVE", "NEUTRAL" ], "nullable": true, "description": "Sentiment classification" }, "toneOfVoice": { "type": "string", "nullable": true, "description": "Detected tone of voice" }, "mentionedOurBrand": { "type": "boolean", "description": "Whether the project's brand was mentioned" }, "competitorMentions": { "type": "array", "items": { "type": "string" }, "description": "List of competitor brands mentioned" }, "citationCount": { "type": "number", "description": "Total number of citations in response" }, "brandMentions": { "type": "array", "items": { "type": "object", "properties": { "brandName": { "type": "string", "description": "Canonical brand name" }, "brandDomain": { "type": "string", "nullable": true, "description": "Primary brand domain" }, "relation": { "type": "string", "enum": [ "SELF", "DIRECT_COMPETITOR", "OTHER", "IGNORED" ], "description": "Brand relation to the project" }, "visibilityScore": { "type": "number", "description": "Visibility score for this brand mention (0-100)" }, "position": { "type": "number", "nullable": true, "description": "Position in the response (1st, 2nd, etc.)" }, "sentiment": { "type": "string", "enum": [ "POSITIVE", "NEGATIVE", "NEUTRAL" ], "nullable": true, "description": "Sentiment toward this brand in the response" }, "toneOfVoice": { "type": "string", "nullable": true, "description": "Detected tone of voice for this brand" } }, "required": [ "brandName", "relation", "visibilityScore" ], "additionalProperties": false }, "description": "Brands detected in this response with per-brand metrics" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Citation URL" }, "domain": { "type": "string", "description": "Citation domain" }, "rank": { "type": "number", "nullable": true, "description": "Page rank of the cited URL (single response only)" }, "title": { "type": "string", "nullable": true, "description": "Citation title" }, "sourceType": { "type": "string", "enum": [ "NEWS", "BLOG", "CORPORATE", "ACADEMIC", "GOVERNMENT", "WIKI", "INSTAGRAM", "TIKTOK", "X", "REDDIT", "YOUTUBE", "FACEBOOK", "LINKEDIN", "GITHUB", "STACKOVERFLOW", "MEDIUM", "SUBSTACK", "HACKERNEWS", "QUORA", "OTHER" ], "nullable": true, "description": "Source type classification of the cited URL" }, "contentType": { "type": "string", "enum": [ "NEWS_ARTICLE", "OPINION", "LISTICLE", "HOW_TO", "REVIEW", "COMPARISON", "CASE_STUDY", "INTERVIEW", "VIDEO", "PODCAST", "INFOGRAPHIC", "RESEARCH_PAPER", "REPORT", "DOCUMENTATION", "WIKI", "PRODUCT_PAGE", "LANDING_PAGE", "FORUM_POST", "SOCIAL_POST", "COMMENT", "QA", "PRESS_RELEASE", "FAQ", "GLOSSARY", "OTHER" ], "nullable": true, "description": "Content type classification of the cited URL" } }, "required": [ "url", "domain" ], "additionalProperties": false }, "description": "Citations in this response" }, "prompt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Prompt this response belongs to" }, "prompt": { "type": "string", "description": "Prompt text" }, "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ], "description": "Prompt classification" }, "intent": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ], "nullable": true, "description": "Search intent label when set" }, "llmMonitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Monitor identifier" }, "name": { "type": "string", "description": "Monitor display name" } }, "required": [ "id", "name" ], "description": "Monitor that owns the prompt" } }, "required": [ "id", "prompt", "type", "llmMonitor" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Response creation timestamp" } }, "required": [ "id", "content", "model", "provider", "mentionedOurBrand", "competitorMentions", "citationCount", "brandMentions", "citations", "prompt", "createdAt" ], "additionalProperties": false }, "description": "Array of responses" }, "total": { "type": "integer", "description": "Total items matching the request" }, "page": { "type": "integer", "description": "Page number (1-based)" }, "size": { "type": "integer", "description": "Page size" }, "totalPages": { "type": "integer", "description": "Total pages for this page size" } }, "required": [ "responses", "total", "page", "size", "totalPages" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TRACKED_PAGE_NOT_FOUND", "message": "Tracked page not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TRACKED_PAGE_NOT_FOUND", "TRACKED_PAGE_ALREADY_EXISTS", "DATE_RANGE_IN_FUTURE", "INTERNAL_ERROR" ], "example": "TRACKED_PAGE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Tracked page not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TRACKED_PAGE_NOT_FOUND", "message": "Tracked page not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TRACKED_PAGE_NOT_FOUND", "TRACKED_PAGE_ALREADY_EXISTS", "DATE_RANGE_IN_FUTURE", "INTERNAL_ERROR" ], "example": "TRACKED_PAGE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Tracked page not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TRACKED_PAGE_NOT_FOUND", "message": "Tracked page not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TRACKED_PAGE_NOT_FOUND", "TRACKED_PAGE_ALREADY_EXISTS", "DATE_RANGE_IN_FUTURE", "INTERNAL_ERROR" ], "example": "TRACKED_PAGE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Tracked page not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/page-tracker/{id}/prompts": { "get": { "operationId": "listTrackedPagePrompts", "summary": "List Tracked Page Prompts", "tags": [ "Page Tracker" ], "description": "Paginated prompts whose responses cited this tracked page. Date range uses inclusive UTC calendar days. When both startDate and endDate are omitted, the default range is today only (00:00:00.000Z through 23:59:59.999Z on the current UTC date). When only one bound is omitted, the missing bound defaults to today.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number (1-based)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "in": "query", "name": "size", "required": false, "description": "Page size" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "First inclusive UTC calendar day (YYYY-MM-DD). Defaults to today when omitted. Future dates return 400 DATE_RANGE_IN_FUTURE." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "Last inclusive UTC calendar day (YYYY-MM-DD). Defaults to today when omitted. Future dates return 400 DATE_RANGE_IN_FUTURE." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tracked page identifier" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "prompts": [ { "id": "6ba7b82e-9dad-11d1-80b4-00c04fd430c8", "prompt": "What is the best workflow automation tool for finance teams?", "type": "ORGANIC", "intent": "INFORMATIONAL", "isActive": true, "languageCode": "en-US", "llmMonitorId": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "llmMonitor": { "id": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "name": "US English monitor" }, "amountOfResponses": 36, "averageVisibility": 49.5, "volume": 8800, "difficulty": 37, "createdAt": "2026-02-05T11:00:00.000Z", "updatedAt": "2026-03-29T18:20:00.000Z" }, { "id": "6ba7b82f-9dad-11d1-80b4-00c04fd430c8", "prompt": "Example Brand vs Fabrikam for invoicing", "type": "COMPETITOR_COMPARISON", "intent": "BRANDED", "isActive": true, "languageCode": "en-US", "llmMonitorId": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "llmMonitor": { "id": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "name": "US English monitor" }, "amountOfResponses": 12, "averageVisibility": 61, "volume": 2100, "difficulty": 52, "createdAt": "2026-02-05T11:00:00.000Z", "updatedAt": "2026-03-29T18:20:00.000Z" } ], "total": 2, "page": 1, "size": 10, "totalPages": 1 }, "properties": { "prompts": { "type": "array", "items": { "type": "object", "example": { "id": "6ba7b82e-9dad-11d1-80b4-00c04fd430c8", "prompt": "What is the best workflow automation tool for finance teams?", "type": "ORGANIC", "intent": "INFORMATIONAL", "isActive": true, "languageCode": "en-US", "llmMonitorId": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "llmMonitor": { "id": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "name": "US English monitor" }, "amountOfResponses": 36, "averageVisibility": 49.5, "volume": 8800, "difficulty": 37, "createdAt": "2026-02-05T11:00:00.000Z", "updatedAt": "2026-03-29T18:20:00.000Z" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Prompt identifier" }, "prompt": { "type": "string", "description": "The prompt text" }, "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ], "description": "Type of prompt" }, "intent": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ], "nullable": true, "description": "Intent of the prompt" }, "isActive": { "type": "boolean", "description": "Whether the prompt is active" }, "languageCode": { "type": "string", "description": "Language code for the prompt" }, "llmMonitorId": { "type": "string", "format": "uuid", "description": "Monitor that owns this prompt" }, "llmMonitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Monitor identifier" }, "name": { "type": "string", "description": "Monitor name" } }, "required": [ "id", "name" ], "additionalProperties": false }, "amountOfResponses": { "type": "number", "description": "Total number of responses for this prompt" }, "averageVisibility": { "type": "number", "nullable": true, "description": "Average visibility score across all responses" }, "volume": { "type": "number", "nullable": true, "description": "Weighted search volume across all keywords (Google + Bing + AI). Null if no keyword data available." }, "difficulty": { "type": "number", "nullable": true, "description": "Weighted average keyword difficulty across all keywords" }, "createdAt": { "type": "string", "format": "date-time", "description": "Prompt creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Prompt last update timestamp" } }, "required": [ "id", "prompt", "type", "isActive", "languageCode", "llmMonitorId", "llmMonitor", "amountOfResponses", "volume", "createdAt", "updatedAt" ], "additionalProperties": false }, "description": "Array of prompts" }, "total": { "type": "integer", "description": "Total items matching the request" }, "page": { "type": "integer", "description": "Page number (1-based)" }, "size": { "type": "integer", "description": "Page size" }, "totalPages": { "type": "integer", "description": "Total pages for this page size" } }, "required": [ "prompts", "total", "page", "size", "totalPages" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TRACKED_PAGE_NOT_FOUND", "message": "Tracked page not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TRACKED_PAGE_NOT_FOUND", "TRACKED_PAGE_ALREADY_EXISTS", "DATE_RANGE_IN_FUTURE", "INTERNAL_ERROR" ], "example": "TRACKED_PAGE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Tracked page not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TRACKED_PAGE_NOT_FOUND", "message": "Tracked page not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TRACKED_PAGE_NOT_FOUND", "TRACKED_PAGE_ALREADY_EXISTS", "DATE_RANGE_IN_FUTURE", "INTERNAL_ERROR" ], "example": "TRACKED_PAGE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Tracked page not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TRACKED_PAGE_NOT_FOUND", "message": "Tracked page not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TRACKED_PAGE_NOT_FOUND", "TRACKED_PAGE_ALREADY_EXISTS", "DATE_RANGE_IN_FUTURE", "INTERNAL_ERROR" ], "example": "TRACKED_PAGE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Tracked page not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/page-tracker/{id}": { "get": { "operationId": "getTrackedPage", "summary": "Get Tracked Page", "tags": [ "Page Tracker" ], "description": "Get a tracked page with citation stats for a date range. Date range uses inclusive UTC calendar days. When both startDate and endDate are omitted, the default range is today only (00:00:00.000Z through 23:59:59.999Z on the current UTC date). When only one bound is omitted, the missing bound defaults to today.", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "First inclusive UTC calendar day (YYYY-MM-DD). Defaults to today when omitted. Future dates return 400 DATE_RANGE_IN_FUTURE." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "Last inclusive UTC calendar day (YYYY-MM-DD). Defaults to today when omitted. Future dates return 400 DATE_RANGE_IN_FUTURE." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tracked page identifier" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "example": { "id": "6ba7b822-9dad-11d1-80b4-00c04fd430c8", "url": "https://example.com/pricing", "title": "Pricing", "domainName": "example.com", "createdAt": "2026-03-15T10:00:00.000Z", "promptCount": 12, "citationCount": 28, "lastCitedAt": "2026-03-28T14:30:00.000Z" }, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Tracked page identifier" }, "url": { "type": "string", "description": "Canonical page URL" }, "title": { "type": "string", "nullable": true, "description": "Page title" }, "domainName": { "type": "string", "description": "Page domain" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp (ISO 8601)" }, "promptCount": { "type": "number", "description": "Distinct prompts citing this page in the date range" }, "citationCount": { "type": "number", "description": "Citation occurrences (responses citing this page) in the date range" }, "lastCitedAt": { "type": "string", "format": "date-time", "description": "Most recent citation timestamp in the date range", "nullable": true } }, "required": [ "id", "url", "title", "domainName", "createdAt", "promptCount", "citationCount", "lastCitedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TRACKED_PAGE_NOT_FOUND", "message": "Tracked page not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TRACKED_PAGE_NOT_FOUND", "TRACKED_PAGE_ALREADY_EXISTS", "DATE_RANGE_IN_FUTURE", "INTERNAL_ERROR" ], "example": "TRACKED_PAGE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Tracked page not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TRACKED_PAGE_NOT_FOUND", "message": "Tracked page not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TRACKED_PAGE_NOT_FOUND", "TRACKED_PAGE_ALREADY_EXISTS", "DATE_RANGE_IN_FUTURE", "INTERNAL_ERROR" ], "example": "TRACKED_PAGE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Tracked page not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TRACKED_PAGE_NOT_FOUND", "message": "Tracked page not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TRACKED_PAGE_NOT_FOUND", "TRACKED_PAGE_ALREADY_EXISTS", "DATE_RANGE_IN_FUTURE", "INTERNAL_ERROR" ], "example": "TRACKED_PAGE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Tracked page not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deleteTrackedPage", "summary": "Delete Tracked Page", "tags": [ "Page Tracker" ], "description": "Stop tracking a page by tracked page id", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tracked page identifier" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "deletedCount": 1 }, "properties": { "deletedCount": { "type": "number", "description": "Number of tracked pages removed" } }, "required": [ "deletedCount" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TRACKED_PAGE_NOT_FOUND", "message": "Tracked page not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TRACKED_PAGE_NOT_FOUND", "TRACKED_PAGE_ALREADY_EXISTS", "DATE_RANGE_IN_FUTURE", "INTERNAL_ERROR" ], "example": "TRACKED_PAGE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Tracked page not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TRACKED_PAGE_NOT_FOUND", "message": "Tracked page not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TRACKED_PAGE_NOT_FOUND", "TRACKED_PAGE_ALREADY_EXISTS", "DATE_RANGE_IN_FUTURE", "INTERNAL_ERROR" ], "example": "TRACKED_PAGE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Tracked page not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/visibility-time-series": { "get": { "operationId": "getVisibilityTimeSeries", "summary": "Visibility Time Series", "tags": [ "Visibility" ], "description": "Get brand visibility time series data", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for visibility data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for visibility data (YYYY-MM-DD)" }, { "schema": { "type": "string", "enum": [ "day", "week", "month" ], "default": "day" }, "in": "query", "name": "range", "required": false, "description": "Time grouping for the data (day, week, or month)" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "models", "required": false, "description": "Filter by LLM models. Repeat for multiple: models=x&models=y" }, { "schema": { "type": "string" }, "in": "query", "name": "promptId", "required": false, "description": "Filter by specific prompt ID" }, { "schema": { "type": "string" }, "in": "query", "name": "llmMonitorId", "required": false, "description": "Filter by specific LLM monitor ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "example": [ { "date": "2026-03-14", "value": 41.25 }, { "date": "2026-03-15", "value": 43.8 } ], "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Bucket start date (YYYY-MM-DD)" }, "value": { "type": "number", "nullable": true, "description": "Visibility score for the bucket, or null if no responses in range" } }, "required": [ "date", "value" ], "additionalProperties": false } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred while computing visibility." }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "INTERNAL_ERROR" ], "example": "INTERNAL_ERROR" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An unexpected error occurred" } }, "required": [ "code", "message" ], "additionalProperties": false }, "example": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } }, "/prompt-visibility-time-series": { "get": { "operationId": "getPromptVisibilityTimeSeries", "summary": "Prompt Visibility Time Series", "tags": [ "Visibility" ], "description": "Get per-prompt visibility time series data (the chart lines for each prompt)", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for visibility data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for visibility data (YYYY-MM-DD)" }, { "schema": { "type": "string", "enum": [ "day", "week", "month" ], "default": "day" }, "in": "query", "name": "range", "required": false, "description": "Time grouping for the data (day, week, or month)" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "models", "required": false, "description": "Filter by LLM models. Repeat for multiple: models=x&models=y" }, { "schema": { "type": "string" }, "in": "query", "name": "llmMonitorId", "required": false, "description": "Filter by specific LLM monitor ID" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } } ] }, "in": "query", "name": "types", "required": false, "description": "Filter by prompt types. Repeat for multiple: types=x&types=y" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "tagIds", "required": false, "description": "Filter by prompt tag IDs. Repeat for multiple: tagIds=x&tagIds=y" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "topicIds", "required": false, "description": "Filter by prompt topic IDs. Repeat for multiple: topicIds=x&topicIds=y" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "in": "query", "name": "sortDirection", "required": false, "description": "Direction to rank prompts by average visibility" }, { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "limit", "required": false, "description": "Number of top-ranked prompts to return (omit for all prompts)" }, { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "offset", "required": false, "description": "Number of top-ranked prompts to skip before applying limit" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeSeries": { "type": "array", "description": "Per-prompt visibility lines, one point per (prompt, bucket)", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Bucket start date (YYYY-MM-DD)" }, "prompt": { "type": "object", "properties": { "id": { "type": "string", "description": "Prompt ID" }, "prompt": { "type": "string", "description": "Prompt text" }, "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ], "description": "Prompt type" } }, "required": [ "id", "prompt", "type" ], "additionalProperties": false }, "averageVisibility": { "type": "number", "description": "Average visibility score (0-100) for the prompt in this bucket" }, "totalResponses": { "type": "integer", "description": "Number of responses for the prompt in this bucket" }, "mentionCount": { "type": "integer", "description": "Number of responses mentioning the brand in this bucket" } }, "required": [ "date", "prompt", "averageVisibility", "totalResponses", "mentionCount" ], "additionalProperties": false } }, "prompts": { "type": "array", "description": "Per-prompt summary across the full range, ranked by average visibility", "items": { "type": "object", "properties": { "prompt": { "type": "object", "properties": { "id": { "type": "string", "description": "Prompt ID" }, "prompt": { "type": "string", "description": "Prompt text" }, "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ], "description": "Prompt type" }, "isActive": { "type": "boolean", "description": "Whether the prompt is active" } }, "required": [ "id", "prompt", "type", "isActive" ], "additionalProperties": false }, "averageVisibility": { "type": "number", "description": "Daily-averaged visibility score (0-100)" }, "daysWithMentions": { "type": "integer", "description": "Number of buckets with at least one brand mention" }, "totalDays": { "type": "integer", "description": "Number of buckets with responses" }, "totalResponses": { "type": "integer", "description": "Total responses for the prompt in the range" } }, "required": [ "prompt", "averageVisibility", "daysWithMentions", "totalDays", "totalResponses" ], "additionalProperties": false } }, "totalPrompts": { "type": "integer", "description": "Total number of prompts matching the filters (ignores limit/offset), for pagination" } }, "required": [ "timeSeries", "prompts", "totalPrompts" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred while computing visibility." }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "INTERNAL_ERROR" ], "example": "INTERNAL_ERROR" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An unexpected error occurred" } }, "required": [ "code", "message" ], "additionalProperties": false }, "example": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } }, "/sentiment-time-series": { "get": { "operationId": "getBrandSentimentTimeSeries", "summary": "Sentiment Time Series", "tags": [ "Analytics" ], "description": "Get brand sentiment time series data", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for sentiment data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for sentiment data (YYYY-MM-DD)" }, { "schema": { "type": "string", "enum": [ "day", "week", "month" ], "default": "day" }, "in": "query", "name": "range", "required": false, "description": "Time grouping for the data (day, week, or month)" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "models", "required": false, "description": "Filter by LLM models. Repeat for multiple" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } } ] }, "in": "query", "name": "promptTypes", "required": false, "description": "Filter by prompt type. Repeat for multiple" }, { "schema": { "type": "string" }, "in": "query", "name": "promptId", "required": false, "description": "Filter by specific prompt ID" }, { "schema": { "type": "string" }, "in": "query", "name": "llmMonitorId", "required": false, "description": "Filter by specific LLM monitor ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "example": [ { "date": "2026-03-14", "value": 0.62 }, { "date": "2026-03-15", "value": 0.58 } ], "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Bucket date (YYYY-MM-DD)" }, "value": { "type": "number", "nullable": true, "description": "Aggregated sentiment score for the bucket, or null if empty" } }, "required": [ "date", "value" ], "additionalProperties": false } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred while computing sentiment." }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "INTERNAL_ERROR" ], "example": "INTERNAL_ERROR" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An unexpected error occurred" } }, "required": [ "code", "message" ], "additionalProperties": false }, "example": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } }, "/citations": { "get": { "operationId": "getCitationAnalytics", "summary": "Citation Analytics", "tags": [ "Citations" ], "description": "Get citation analytics including top cited domains, URLs, and authority metrics", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for citation data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for citation data (YYYY-MM-DD)" }, { "schema": { "anyOf": [ { "type": "string", "description": "Single model" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "models", "required": false, "description": "Filter by LLM models. Repeat for multiple: models=x&models=y" }, { "schema": { "type": "string" }, "in": "query", "name": "promptId", "required": false, "description": "Filter by specific prompt ID" }, { "schema": { "type": "string" }, "in": "query", "name": "llmMonitorId", "required": false, "description": "Filter by specific LLM monitor ID" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } } ] }, "in": "query", "name": "promptTypes", "required": false, "description": "Filter by prompt type. Repeat for multiple: promptTypes=ORGANIC&promptTypes=BRAND_SPECIFIC" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of domain results to return" }, { "schema": { "anyOf": [ { "type": "string", "description": "Single domain" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "domains", "required": false, "description": "Filter by domains. Repeat for multiple: domains=x&domains=y" }, { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number for URL results (1-indexed)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 20 }, "in": "query", "name": "size", "required": false, "description": "Number of URL results per page" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "domains": [ { "domainName": "docs.example.com", "count": 48 }, { "domainName": "blog.example.com", "count": 31 } ], "urls": [ { "url": "https://docs.example.com/guide", "count": 22 }, { "url": "https://blog.example.com/post-a", "count": 18 } ], "totalEstimatedTraffic": 125000, "averageAuthorityScore": 42.5, "averagePageRank": 3.2, "summary": { "totalCitedDomains": 85, "totalCitedUrls": 210, "totalCitations": 1520 }, "pagination": { "total": 210, "page": 1, "size": 20, "totalPages": 11 } }, "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domainName": { "type": "string", "description": "Domain name that was cited" }, "count": { "type": "number", "description": "Number of times this domain was cited" } }, "required": [ "domainName", "count" ], "additionalProperties": false }, "description": "Top cited domains with their citation counts" }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL that was cited" }, "count": { "type": "number", "description": "Number of times this URL was cited" } }, "required": [ "url", "count" ], "additionalProperties": false }, "description": "Top cited URLs with their citation counts" }, "totalEstimatedTraffic": { "type": "number", "description": "Total estimated traffic from all cited URLs" }, "averageAuthorityScore": { "type": "number", "nullable": true, "description": "Average domain authority score of cited domains" }, "averagePageRank": { "type": "number", "nullable": true, "description": "Average page rank of cited URLs" }, "summary": { "type": "object", "properties": { "totalCitedDomains": { "type": "number", "description": "Total number of unique domains cited" }, "totalCitedUrls": { "type": "number", "description": "Total number of unique URLs cited" }, "totalCitations": { "type": "number", "description": "Total number of citations" } }, "required": [ "totalCitedDomains", "totalCitedUrls", "totalCitations" ], "additionalProperties": false }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of URL results" }, "page": { "type": "number", "description": "Current page number (1-indexed)" }, "size": { "type": "number", "description": "Number of results per page" }, "totalPages": { "type": "number", "description": "Total number of pages" } }, "required": [ "total", "page", "size", "totalPages" ], "additionalProperties": false } }, "required": [ "domains", "urls", "totalEstimatedTraffic", "summary", "pagination" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROJECT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROJECT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Project not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" } }, "example2": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/citations/self-frequency": { "get": { "operationId": "getSelfCitationFrequency", "summary": "Self-Citation Frequency", "tags": [ "Citations" ], "description": "Get self-citation frequency over time (citations pointing to your own domain)", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for citation data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for citation data (YYYY-MM-DD)" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "models", "required": false, "description": "Filter by LLM models. Repeat for multiple" }, { "schema": { "type": "string" }, "in": "query", "name": "promptId", "required": false, "description": "Filter by specific prompt ID" }, { "schema": { "type": "string" }, "in": "query", "name": "llmMonitorId", "required": false, "description": "Filter by specific LLM monitor ID" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } } ] }, "in": "query", "name": "promptTypes", "required": false, "description": "Filter by prompt type. Repeat for multiple" }, { "schema": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ], "default": "DAILY" }, "in": "query", "name": "range", "required": false, "description": "Time range grouping" }, { "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "default": "daily" }, "in": "query", "name": "granularity", "required": false, "description": "Time granularity for grouping data" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "in": "query", "name": "domainLimit", "required": false, "description": "Maximum number of domains to include (for domain over time endpoint)" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "domains", "required": false, "description": "Filter by domains. Repeat for multiple" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeSelf", "required": false, "description": "If true, always include the project's own brand domain (even with 0 citations)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "example": [ { "date": "2026-03-14T00:00:00.000Z", "value": 7 }, { "date": "2026-03-15T00:00:00.000Z", "value": 9 } ], "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time", "description": "Date for this data point" }, "value": { "type": "number", "nullable": true, "description": "Number of self-citations for this period" } }, "required": [ "date" ], "additionalProperties": false } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROJECT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROJECT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Project not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" } }, "example2": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/citations/domains-over-time": { "get": { "operationId": "getDomainCitationsOverTime", "summary": "Domain Citations Over Time", "tags": [ "Citations" ], "description": "Get domain citation frequency over time for top domains", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for citation data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for citation data (YYYY-MM-DD)" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "models", "required": false, "description": "Filter by LLM models. Repeat for multiple" }, { "schema": { "type": "string" }, "in": "query", "name": "promptId", "required": false, "description": "Filter by specific prompt ID" }, { "schema": { "type": "string" }, "in": "query", "name": "llmMonitorId", "required": false, "description": "Filter by specific LLM monitor ID" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } } ] }, "in": "query", "name": "promptTypes", "required": false, "description": "Filter by prompt type. Repeat for multiple" }, { "schema": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ], "default": "DAILY" }, "in": "query", "name": "range", "required": false, "description": "Time range grouping" }, { "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "default": "daily" }, "in": "query", "name": "granularity", "required": false, "description": "Time granularity for grouping data" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "in": "query", "name": "domainLimit", "required": false, "description": "Maximum number of domains to include (for domain over time endpoint)" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "domains", "required": false, "description": "Filter by domains. Repeat for multiple" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeSelf", "required": false, "description": "If true, always include the project's own brand domain (even with 0 citations)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "dates": [ "2026-03-14T00:00:00.000Z", "2026-03-15T00:00:00.000Z" ], "series": [ { "domain": "docs.example.com", "data": [ 12, 15 ], "total": 27, "percentage": 52, "averageRank": 2.1 }, { "domain": "competitor.example.net", "data": [ 8, 7 ], "total": 15, "percentage": 29, "averageRank": 3.4 } ], "totalCitations": 52 }, "properties": { "dates": { "type": "array", "items": { "type": "string", "format": "date-time" }, "description": "Array of dates for the time series" }, "series": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain name" }, "data": { "type": "array", "items": { "type": "number", "nullable": true }, "description": "Citation counts for each date" }, "total": { "type": "number", "description": "Total citation count for this domain" }, "percentage": { "type": "number", "description": "Percentage of total citations" }, "averageRank": { "type": "number", "nullable": true, "description": "Average citation rank/position for this domain" } }, "required": [ "domain", "data", "total", "percentage" ], "additionalProperties": false }, "description": "Time series data for each domain" }, "totalCitations": { "type": "number", "description": "Total citations across all domains" } }, "required": [ "dates", "series", "totalCitations" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROJECT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROJECT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Project not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" } }, "example2": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/citations/rank-analysis": { "get": { "operationId": "getCitationRankAnalysis", "summary": "Citation Rank Analysis", "tags": [ "Citations" ], "description": "Get citation rank analysis for your domain over time", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for citation data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for citation data (YYYY-MM-DD)" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "models", "required": false, "description": "Filter by LLM models. Repeat for multiple" }, { "schema": { "type": "string" }, "in": "query", "name": "promptId", "required": false, "description": "Filter by specific prompt ID" }, { "schema": { "type": "string" }, "in": "query", "name": "llmMonitorId", "required": false, "description": "Filter by specific LLM monitor ID" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } } ] }, "in": "query", "name": "promptTypes", "required": false, "description": "Filter by prompt type. Repeat for multiple" }, { "schema": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ], "default": "DAILY" }, "in": "query", "name": "range", "required": false, "description": "Time range grouping" }, { "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "default": "daily" }, "in": "query", "name": "granularity", "required": false, "description": "Time granularity for grouping data" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "in": "query", "name": "domainLimit", "required": false, "description": "Maximum number of domains to include (for domain over time endpoint)" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "domains", "required": false, "description": "Filter by domains. Repeat for multiple" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeSelf", "required": false, "description": "If true, always include the project's own brand domain (even with 0 citations)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "timeSeries": [ { "date": "2026-03-14T00:00:00.000Z", "totalCitations": 20, "averageRank": 2.4, "bestRank": 1, "worstRank": 5, "citationsWithRank": 18 }, { "date": "2026-03-15T00:00:00.000Z", "totalCitations": 22, "averageRank": 2.1, "bestRank": 1, "worstRank": 6, "citationsWithRank": 20 } ], "overallAverageRank": 2.25, "lastRank": 2.1 }, "properties": { "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time", "description": "Date for this data point" }, "totalCitations": { "type": "number", "nullable": true, "description": "Total citations for this period" }, "averageRank": { "type": "number", "nullable": true, "description": "Average citation rank/position" }, "bestRank": { "type": "number", "nullable": true, "description": "Best (lowest) rank achieved" }, "worstRank": { "type": "number", "nullable": true, "description": "Worst (highest) rank" }, "citationsWithRank": { "type": "number", "nullable": true, "description": "Citations with position data" } }, "required": [ "date" ], "additionalProperties": false } }, "overallAverageRank": { "type": "number", "nullable": true, "description": "Overall average rank for the entire period" }, "lastRank": { "type": "number", "nullable": true, "description": "The last rank value from the time series" } }, "required": [ "timeSeries" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROJECT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROJECT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Project not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" } }, "example2": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/citations/top-pages": { "get": { "operationId": "getTopCitedPages", "summary": "Top Cited Pages", "tags": [ "Citations" ], "description": "Get top cited pages with average rank", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for citation data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for citation data (YYYY-MM-DD)" }, { "schema": { "anyOf": [ { "type": "string", "description": "Single model" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "models", "required": false, "description": "Filter by LLM models. Repeat for multiple: models=x&models=y" }, { "schema": { "type": "string" }, "in": "query", "name": "promptId", "required": false, "description": "Filter by specific prompt ID" }, { "schema": { "type": "string" }, "in": "query", "name": "llmMonitorId", "required": false, "description": "Filter by specific LLM monitor ID" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } } ] }, "in": "query", "name": "promptTypes", "required": false, "description": "Filter by prompt type. Repeat for multiple: promptTypes=ORGANIC&promptTypes=BRAND_SPECIFIC" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of domain results to return" }, { "schema": { "anyOf": [ { "type": "string", "description": "Single domain" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "domains", "required": false, "description": "Filter by domains. Repeat for multiple: domains=x&domains=y" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "example": [ { "url": "https://docs.example.com/pricing", "count": 36, "averageRank": 2 }, { "url": "https://www.example.com/", "count": 29, "averageRank": 1.6 } ], "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL that was cited" }, "count": { "type": "number", "description": "Number of times this URL was cited" }, "averageRank": { "type": "number", "nullable": true, "description": "Average rank/position for this URL" } }, "required": [ "url", "count", "averageRank" ], "additionalProperties": false } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROJECT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROJECT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Project not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" } }, "example2": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/citations/llm-sources": { "get": { "operationId": "getLlmCitationSources", "summary": "LLM Sources", "tags": [ "Citations" ], "description": "Get top LLM sources with citation statistics", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for citation data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for citation data (YYYY-MM-DD)" }, { "schema": { "anyOf": [ { "type": "string", "description": "Single model" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "models", "required": false, "description": "Filter by LLM models. Repeat for multiple: models=x&models=y" }, { "schema": { "type": "string" }, "in": "query", "name": "promptId", "required": false, "description": "Filter by specific prompt ID" }, { "schema": { "type": "string" }, "in": "query", "name": "llmMonitorId", "required": false, "description": "Filter by specific LLM monitor ID" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } } ] }, "in": "query", "name": "promptTypes", "required": false, "description": "Filter by prompt type. Repeat for multiple: promptTypes=ORGANIC&promptTypes=BRAND_SPECIFIC" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of domain results to return" }, { "schema": { "anyOf": [ { "type": "string", "description": "Single domain" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "domains", "required": false, "description": "Filter by domains. Repeat for multiple: domains=x&domains=y" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "example": [ { "llm": "openai_gpt-4.1", "provider": "openai", "model": "gpt-4.1", "totalCitations": 420, "uniqueDomains": 55, "uniquePrompts": 38 }, { "llm": "anthropic_claude-sonnet-4-20250514", "provider": "anthropic", "model": "claude-sonnet-4-20250514", "totalCitations": 310, "uniqueDomains": 41, "uniquePrompts": 29 } ], "items": { "type": "object", "properties": { "llm": { "type": "string", "description": "LLM identifier (provider_model)" }, "provider": { "type": "string", "description": "LLM provider name" }, "model": { "type": "string", "description": "LLM model name" }, "totalCitations": { "type": "number", "description": "Total number of citations from this LLM" }, "uniqueDomains": { "type": "number", "description": "Number of unique domains cited by this LLM" }, "uniquePrompts": { "type": "number", "description": "Number of unique prompts that generated citations" } }, "required": [ "llm", "provider", "model", "totalCitations", "uniqueDomains", "uniquePrompts" ], "additionalProperties": false } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROJECT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROJECT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Project not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" } }, "example2": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/citations/domains-by-llm": { "get": { "operationId": "getDomainCitationsByLlm", "summary": "Domains by LLM", "tags": [ "Citations" ], "description": "Get domain citations grouped by LLM source", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for citation data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for citation data (YYYY-MM-DD)" }, { "schema": { "anyOf": [ { "type": "string", "description": "Single model" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "models", "required": false, "description": "Filter by LLM models. Repeat for multiple: models=x&models=y" }, { "schema": { "type": "string" }, "in": "query", "name": "promptId", "required": false, "description": "Filter by specific prompt ID" }, { "schema": { "type": "string" }, "in": "query", "name": "llmMonitorId", "required": false, "description": "Filter by specific LLM monitor ID" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } } ] }, "in": "query", "name": "promptTypes", "required": false, "description": "Filter by prompt type. Repeat for multiple: promptTypes=ORGANIC&promptTypes=BRAND_SPECIFIC" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of domain results to return" }, { "schema": { "anyOf": [ { "type": "string", "description": "Single domain" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "domains", "required": false, "description": "Filter by domains. Repeat for multiple: domains=x&domains=y" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "example": [ { "llm": "openai_gpt-4.1", "provider": "openai", "model": "gpt-4.1", "domains": [ { "domainName": "docs.example.com", "count": 24 }, { "domainName": "news.example.org", "count": 11 } ] } ], "items": { "type": "object", "properties": { "llm": { "type": "string", "description": "LLM identifier (provider_model)" }, "provider": { "type": "string", "description": "LLM provider name" }, "model": { "type": "string", "description": "LLM model name" }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domainName": { "type": "string", "description": "Domain name" }, "count": { "type": "number", "description": "Number of citations for this domain from this LLM" } }, "required": [ "domainName", "count" ], "additionalProperties": false }, "description": "Top domains cited by this LLM" } }, "required": [ "llm", "provider", "model", "domains" ], "additionalProperties": false } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROJECT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROJECT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Project not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" } }, "example2": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/prompts": { "get": { "operationId": "listPrompts", "summary": "List Prompts", "tags": [ "Prompts" ], "description": "Get paginated list of prompts with search and filtering options", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number (1-based)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "in": "query", "name": "size", "required": false, "description": "Page size" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "llmMonitorId", "required": false, "description": "Filter by monitor" }, { "schema": { "type": "string" }, "in": "query", "name": "query", "required": false, "description": "Search query for prompt text (full-text search)" }, { "schema": { "type": "boolean" }, "in": "query", "name": "isActive", "required": false, "description": "Filter by active/inactive status" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } }, "in": "query", "name": "types", "required": false, "description": "Filter by prompt types" }, { "schema": { "type": "string", "enum": [ "createdAt", "updatedAt", "isActive", "type", "intent" ], "default": "createdAt" }, "in": "query", "name": "sortBy", "required": false, "description": "Field to sort by" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "in": "query", "name": "sortOrder", "required": false, "description": "Sort order" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "prompts": [ { "id": "6ba7b82e-9dad-11d1-80b4-00c04fd430c8", "prompt": "What is the best workflow automation tool for finance teams?", "type": "ORGANIC", "intent": "INFORMATIONAL", "isActive": true, "languageCode": "en-US", "llmMonitorId": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "llmMonitor": { "id": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "name": "US English monitor" }, "amountOfResponses": 36, "averageVisibility": 49.5, "volume": 8800, "difficulty": 37, "createdAt": "2026-02-05T11:00:00.000Z", "updatedAt": "2026-03-29T18:20:00.000Z" }, { "id": "6ba7b82f-9dad-11d1-80b4-00c04fd430c8", "prompt": "Example Brand vs Fabrikam for invoicing", "type": "COMPETITOR_COMPARISON", "intent": "BRANDED", "isActive": true, "languageCode": "en-US", "llmMonitorId": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "llmMonitor": { "id": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "name": "US English monitor" }, "amountOfResponses": 12, "averageVisibility": 61, "volume": 2100, "difficulty": 52, "createdAt": "2026-02-05T11:00:00.000Z", "updatedAt": "2026-03-29T18:20:00.000Z" } ], "total": 2, "page": 1, "size": 10, "totalPages": 1 }, "properties": { "prompts": { "type": "array", "items": { "type": "object", "example": { "id": "6ba7b82e-9dad-11d1-80b4-00c04fd430c8", "prompt": "What is the best workflow automation tool for finance teams?", "type": "ORGANIC", "intent": "INFORMATIONAL", "isActive": true, "languageCode": "en-US", "llmMonitorId": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "llmMonitor": { "id": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "name": "US English monitor" }, "amountOfResponses": 36, "averageVisibility": 49.5, "volume": 8800, "difficulty": 37, "createdAt": "2026-02-05T11:00:00.000Z", "updatedAt": "2026-03-29T18:20:00.000Z" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Prompt identifier" }, "prompt": { "type": "string", "description": "The prompt text" }, "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ], "description": "Type of prompt" }, "intent": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ], "nullable": true, "description": "Intent of the prompt" }, "isActive": { "type": "boolean", "description": "Whether the prompt is active" }, "languageCode": { "type": "string", "description": "Language code for the prompt" }, "llmMonitorId": { "type": "string", "format": "uuid", "description": "Monitor that owns this prompt" }, "llmMonitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Monitor identifier" }, "name": { "type": "string", "description": "Monitor name" } }, "required": [ "id", "name" ], "additionalProperties": false }, "amountOfResponses": { "type": "number", "description": "Total number of responses for this prompt" }, "averageVisibility": { "type": "number", "nullable": true, "description": "Average visibility score across all responses" }, "volume": { "type": "number", "nullable": true, "description": "Weighted search volume across all keywords (Google + Bing + AI). Null if no keyword data available." }, "difficulty": { "type": "number", "nullable": true, "description": "Weighted average keyword difficulty across all keywords" }, "createdAt": { "type": "string", "format": "date-time", "description": "Prompt creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Prompt last update timestamp" } }, "required": [ "id", "prompt", "type", "isActive", "languageCode", "llmMonitorId", "llmMonitor", "amountOfResponses", "volume", "createdAt", "updatedAt" ], "additionalProperties": false }, "description": "Array of prompts" }, "total": { "type": "integer", "description": "Total items matching the request" }, "page": { "type": "integer", "description": "Page number (1-based)" }, "size": { "type": "integer", "description": "Page size" }, "totalPages": { "type": "integer", "description": "Total pages for this page size" } }, "required": [ "prompts", "total", "page", "size", "totalPages" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } }, "post": { "operationId": "createPrompt", "summary": "Create Prompt", "tags": [ "Prompts" ], "description": "Create a new prompt", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The prompt text" }, "llmMonitorId": { "type": "string", "format": "uuid", "description": "Monitor to attach prompt to" }, "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ], "description": "Type of prompt" }, "intent": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ], "nullable": true, "description": "Intent of the prompt" }, "languageCode": { "type": "string", "default": "en-US", "description": "Language code" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Optional keywords" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional tag names" }, "isActive": { "type": "boolean", "default": true, "description": "Whether prompt is active" } }, "required": [ "prompt", "llmMonitorId", "type" ], "additionalProperties": false } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "6ba7b830-9dad-11d1-80b4-00c04fd430c8", "prompt": "Track brand mentions in ChatGPT answers?", "type": "ORGANIC", "intent": null, "isActive": true, "llmMonitorId": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "languageCode": "en-US", "createdAt": "2026-03-30T10:00:00.000Z" }, "properties": { "id": { "type": "string", "format": "uuid" }, "prompt": { "type": "string" }, "type": { "type": "string" }, "intent": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" }, "llmMonitorId": { "type": "string", "format": "uuid" }, "languageCode": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "prompt", "type", "isActive", "llmMonitorId", "createdAt" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "402": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Payment Required", "message": "Cannot create prompt. Your organization has 50 of 50 active prompts. Please upgrade your plan to continue.", "current": 50, "limit": 50, "available": 0 }, "properties": { "error": { "type": "string", "description": "Fixed error label", "enum": [ "Payment Required" ] }, "message": { "type": "string", "description": "Explanation including usage and limit" }, "current": { "type": "integer", "description": "Current usage for this quota" }, "limit": { "type": "integer", "description": "Maximum allowed on the current plan" }, "available": { "type": "integer", "description": "Remaining quota (0 when blocked)" } }, "required": [ "error", "message", "current", "limit", "available" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/prompts/{id}": { "get": { "operationId": "getPrompt", "summary": "Get Prompt", "tags": [ "Prompts" ], "description": "Get a single prompt by ID", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Prompt ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "6ba7b82e-9dad-11d1-80b4-00c04fd430c8", "prompt": "What is the best workflow automation tool for finance teams?", "type": "ORGANIC", "intent": "INFORMATIONAL", "isActive": true, "languageCode": "en-US", "llmMonitorId": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "llmMonitor": { "id": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "name": "US English monitor" }, "amountOfResponses": 36, "averageVisibility": 49.5, "volume": 8800, "difficulty": 37, "createdAt": "2026-02-05T11:00:00.000Z", "updatedAt": "2026-03-29T18:20:00.000Z" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Prompt identifier" }, "prompt": { "type": "string", "description": "The prompt text" }, "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ], "description": "Type of prompt" }, "intent": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ], "nullable": true, "description": "Intent of the prompt" }, "isActive": { "type": "boolean", "description": "Whether the prompt is active" }, "languageCode": { "type": "string", "description": "Language code for the prompt" }, "llmMonitorId": { "type": "string", "format": "uuid", "description": "Monitor that owns this prompt" }, "llmMonitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Monitor identifier" }, "name": { "type": "string", "description": "Monitor name" } }, "required": [ "id", "name" ], "additionalProperties": false }, "amountOfResponses": { "type": "number", "description": "Total number of responses for this prompt" }, "averageVisibility": { "type": "number", "nullable": true, "description": "Average visibility score across all responses" }, "volume": { "type": "number", "nullable": true, "description": "Weighted search volume across all keywords (Google + Bing + AI). Null if no keyword data available." }, "difficulty": { "type": "number", "nullable": true, "description": "Weighted average keyword difficulty across all keywords" }, "createdAt": { "type": "string", "format": "date-time", "description": "Prompt creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Prompt last update timestamp" } }, "required": [ "id", "prompt", "type", "isActive", "languageCode", "llmMonitorId", "llmMonitor", "amountOfResponses", "volume", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } }, "put": { "operationId": "updatePrompt", "summary": "Update Prompt", "tags": [ "Prompts" ], "description": "Update a prompt's type and intent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ], "description": "Type of prompt" }, "intent": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ], "description": "Intent of the prompt" } }, "required": [ "type", "intent" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Prompt ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "6ba7b82e-9dad-11d1-80b4-00c04fd430c8", "prompt": "What is the best workflow automation tool for finance teams?", "type": "ORGANIC", "intent": "INFORMATIONAL", "updatedAt": "2026-03-30T10:15:00.000Z" }, "properties": { "id": { "type": "string", "format": "uuid" }, "prompt": { "type": "string" }, "type": { "type": "string" }, "intent": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "prompt", "type", "updatedAt" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } }, "delete": { "operationId": "deletePrompt", "summary": "Delete Prompt", "tags": [ "Prompts" ], "description": "Soft-delete a prompt by ID", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Prompt ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "Default Response" }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/prompts/bulk": { "post": { "operationId": "bulkCreatePrompts", "summary": "Bulk Create Prompts", "tags": [ "Prompts" ], "description": "Create multiple prompts in a single request (max 100)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "llmMonitorId": { "type": "string", "format": "uuid", "description": "Monitor to attach prompts to" }, "prompts": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The prompt text" }, "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, "intent": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ], "nullable": true }, "languageCode": { "type": "string", "default": "en-US" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Optional keywords" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional tag names" }, "isActive": { "type": "boolean", "description": "Whether prompt is active" } }, "required": [ "prompt", "type" ], "additionalProperties": false }, "description": "Array of prompts to create (max 100)" } }, "required": [ "llmMonitorId", "prompts" ], "additionalProperties": false } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "created": 2, "prompts": [ { "id": "6ba7b831-9dad-11d1-80b4-00c04fd430c8", "prompt": "Headless CMS for ecommerce?" }, { "id": "6ba7b832-9dad-11d1-80b4-00c04fd430c8", "prompt": "AI analytics vendors for SaaS?" } ] }, "properties": { "created": { "type": "number", "description": "Number of prompts created" }, "prompts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "prompt": { "type": "string" } }, "required": [ "id", "prompt" ] } } }, "required": [ "created", "prompts" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "402": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Payment Required", "message": "Cannot create prompt. Your organization has 50 of 50 active prompts. Please upgrade your plan to continue.", "current": 50, "limit": 50, "available": 0 }, "properties": { "error": { "type": "string", "description": "Fixed error label", "enum": [ "Payment Required" ] }, "message": { "type": "string", "description": "Explanation including usage and limit" }, "current": { "type": "integer", "description": "Current usage for this quota" }, "limit": { "type": "integer", "description": "Maximum allowed on the current plan" }, "available": { "type": "integer", "description": "Remaining quota (0 when blocked)" } }, "required": [ "error", "message", "current", "limit", "available" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } }, "delete": { "operationId": "bulkDeletePrompts", "summary": "Bulk Delete Prompts", "tags": [ "Prompts" ], "description": "Soft-delete multiple prompts by IDs", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "description": "Array of prompt IDs (max 200)" } }, "required": [ "ids" ], "additionalProperties": false } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "deleted": 5 }, "properties": { "deleted": { "type": "number", "description": "Number of prompts deleted" } }, "required": [ "deleted" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/prompts/bulk/activate": { "patch": { "operationId": "activatePrompts", "summary": "Activate Prompts", "tags": [ "Prompts" ], "description": "Activate multiple prompts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "description": "Array of prompt IDs (max 200)" } }, "required": [ "ids" ], "additionalProperties": false } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "activated": 8 }, "properties": { "activated": { "type": "number", "description": "Number of prompts activated" } }, "required": [ "activated" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/prompts/bulk/deactivate": { "patch": { "operationId": "deactivatePrompts", "summary": "Deactivate Prompts", "tags": [ "Prompts" ], "description": "Deactivate multiple prompts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "description": "Array of prompt IDs (max 200)" } }, "required": [ "ids" ], "additionalProperties": false } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "deactivated": 3 }, "properties": { "deactivated": { "type": "number", "description": "Number of prompts deactivated" } }, "required": [ "deactivated" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/prompts/{id}/tags": { "post": { "operationId": "attachTagsToPrompt", "summary": "Attach Tags to Prompt", "tags": [ "Prompts", "Tags" ], "description": "Attach tags to a prompt (creates tags if they don't exist)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Array of tag names to attach" } }, "required": [ "tags" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Prompt ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "attached": 2, "tags": [ { "id": "6ba7b820-9dad-11d1-80b4-00c04fd430c8", "name": "Q2 campaign" }, { "id": "6ba7b833-9dad-11d1-80b4-00c04fd430c8", "name": "Enterprise" } ] }, "properties": { "attached": { "type": "number", "description": "Number of tags attached to the prompt" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Tag identifier" }, "name": { "type": "string", "description": "Tag label" } }, "required": [ "id", "name" ], "additionalProperties": false }, "description": "Array of all tags now attached to the prompt" } }, "required": [ "attached", "tags" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/prompts/bulk/tags": { "post": { "operationId": "bulkAttachTags", "summary": "Bulk Attach Tags", "tags": [ "Prompts", "Tags" ], "description": "Attach tags to multiple prompts (creates tags if they don't exist)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "promptIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Array of prompt IDs" }, "tags": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Array of tag names to attach" } }, "required": [ "promptIds", "tags" ], "additionalProperties": false } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "attached": 24 }, "properties": { "attached": { "type": "number", "description": "Number of tag-prompt relationships created" } }, "required": [ "attached" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/prompts/{id}/topics": { "post": { "operationId": "attachTopicsToPrompt", "summary": "Attach Topics to Prompt", "tags": [ "Prompts", "Topics" ], "description": "Attach topics to a prompt (creates topics if they don't exist)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topics": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Array of topic names to attach" } }, "required": [ "topics" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Prompt ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "attached": 2 }, "properties": { "attached": { "type": "number", "description": "Number of topic-prompt relationships created" } }, "required": [ "attached" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TOPIC_NOT_FOUND", "message": "Topic not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TOPIC_NOT_FOUND", "TOPIC_FORBIDDEN", "TOPIC_ALREADY_EXISTS", "TOPIC_INVALID_NAME", "TOPIC_INVALID_PROMPT", "TOPIC_NO_VALID_TOPICS_SUPPLIED", "TOPIC_IN_USE", "INTERNAL_ERROR" ], "example": "TOPIC_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/prompts/bulk/topics": { "post": { "operationId": "bulkAttachTopics", "summary": "Bulk Attach Topics", "tags": [ "Prompts", "Topics" ], "description": "Attach topics to multiple prompts (creates topics if they don't exist)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "promptIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Array of prompt IDs" }, "topics": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Array of topic names to attach" } }, "required": [ "promptIds", "topics" ], "additionalProperties": false } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "attached": 24 }, "properties": { "attached": { "type": "number", "description": "Number of topic-prompt relationships created" } }, "required": [ "attached" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TOPIC_NOT_FOUND", "message": "Topic not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TOPIC_NOT_FOUND", "TOPIC_FORBIDDEN", "TOPIC_ALREADY_EXISTS", "TOPIC_INVALID_NAME", "TOPIC_INVALID_PROMPT", "TOPIC_NO_VALID_TOPICS_SUPPLIED", "TOPIC_IN_USE", "INTERNAL_ERROR" ], "example": "TOPIC_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROMPT_NOT_FOUND", "PROMPT_KEYWORDS_REQUIRED", "PROMPT_CLASSIFICATION_FAILED", "PROMPT_INVALID_MOVE_LANGUAGE", "MONITOR_NOT_FOUND", "PROJECT_NOT_FOUND", "PERSONA_NOT_FOUND", "INTERNAL_ERROR" ], "example": "PROMPT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Prompt not found or access denied" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example2": { "value": { "code": "PROMPT_KEYWORDS_REQUIRED", "message": "Keywords are required for keywords generation type" } }, "example3": { "value": { "code": "PROMPT_CLASSIFICATION_FAILED", "message": "All prompt classifications failed" } }, "example4": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/query-fanouts": { "get": { "operationId": "getQueryFanouts", "summary": "List Query Fanouts", "tags": [ "Query Fanouts" ], "description": "Get paginated list of prompts with extracted ChatGPT query fanout keywords", "parameters": [ { "schema": { "type": "number", "default": 1, "minimum": 1 }, "in": "query", "name": "page", "required": false }, { "schema": { "type": "number", "default": 25, "minimum": 1, "maximum": 100 }, "in": "query", "name": "size", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "query", "required": false, "description": "Text search on prompt" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } } ] }, "in": "query", "name": "promptTypes", "required": false, "description": "Prompt type filter; repeat the parameter for multiple values" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ] }, { "type": "array", "items": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ] } } ] }, "in": "query", "name": "intentTypes", "required": false, "description": "Intent type filter; repeat the parameter for multiple values" }, { "schema": { "type": "boolean" }, "in": "query", "name": "hasChatgptFanouts", "required": false, "description": "Filter to prompts with ChatGPT-extracted keywords" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "array", "items": { "type": "string", "format": "uuid" } } ] }, "in": "query", "name": "promptId", "required": false, "description": "Filter by prompt ID(s). Repeat for multiple: promptId=id1&promptId=id2" }, { "schema": { "type": "string", "enum": [ "createdAt", "updatedAt", "type", "intent" ] }, "in": "query", "name": "sortBy", "required": false, "description": "Sort field (combinedVolume/combinedDifficulty not supported - computed post-query)" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortOrder", "required": false } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "items": [ { "id": "6ba7b828-9dad-11d1-80b4-00c04fd430c8", "prompt": "Affordable project management tools for agencies?", "type": "ORGANIC", "intent": "COMMERCIAL", "combinedVolume": 14800, "combinedDifficulty": 41, "keywords": [ { "id": "6ba7b829-9dad-11d1-80b4-00c04fd430c8", "text": "agency project management software", "extractedFromChatgpt": true, "googleSearchVolume": 1900, "bingSearchVolume": 420, "aiSearchVolume": 210, "googleKeywordDifficulty": 38 } ] }, { "id": "6ba7b82a-9dad-11d1-80b4-00c04fd430c8", "prompt": "Example Brand vs Contoso for invoicing", "type": "COMPETITOR_COMPARISON", "intent": "BRANDED", "combinedVolume": 3200, "combinedDifficulty": 55, "keywords": [ { "id": "6ba7b82b-9dad-11d1-80b4-00c04fd430c8", "text": "example brand invoicing", "extractedFromChatgpt": false, "googleSearchVolume": null, "bingSearchVolume": null, "aiSearchVolume": null, "googleKeywordDifficulty": null } ] } ], "total": 95, "page": 1, "size": 25, "totalPages": 4 }, "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Prompt identifier" }, "prompt": { "type": "string" }, "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ], "nullable": true }, "intent": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ], "nullable": true }, "combinedVolume": { "type": "number" }, "combinedDifficulty": { "type": "number" }, "keywords": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Keyword identifier" }, "text": { "type": "string" }, "extractedFromChatgpt": { "type": "boolean" }, "googleSearchVolume": { "type": "number", "nullable": true }, "bingSearchVolume": { "type": "number", "nullable": true }, "aiSearchVolume": { "type": "number", "nullable": true }, "googleKeywordDifficulty": { "type": "number", "nullable": true } }, "required": [ "id", "text", "extractedFromChatgpt" ], "additionalProperties": false } } }, "required": [ "id", "prompt", "type", "intent", "combinedVolume", "combinedDifficulty", "keywords" ], "additionalProperties": false }, "description": "Page of prompts" }, "page": { "type": "integer", "description": "Page number (1-based)" }, "size": { "type": "integer", "description": "Page size" }, "total": { "type": "integer", "description": "Total items matching the request" }, "totalPages": { "type": "integer", "description": "Total pages for this page size" } }, "required": [ "items", "total", "page", "size", "totalPages" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found" }, "properties": { "code": { "type": "string", "description": "Domain error code", "enum": [ "PROMPT_NOT_FOUND", "INTERNAL_ERROR" ] }, "message": { "type": "string", "description": "Human-readable explanation" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/analytics/visitors/total": { "get": { "operationId": "getTotalVisits", "summary": "Total Visits", "tags": [ "Analytics" ], "description": "Get total visitor counts over time", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for analytics data (YYYY-MM-DD). Max range 60 days." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for analytics data (YYYY-MM-DD). Max range 60 days." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, { "type": "array", "items": { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, "maxItems": 8 } ] }, "in": "query", "name": "referrerDomains", "required": false, "description": "Filter by AI referrer domains (repeat param for multiple). Allowed: chatgpt.com, gemini.google.com, perplexity.ai, copilot.microsoft.com, copilot.com, claude.ai, grok.com, chat.mistral.ai" }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false, "description": "IANA timezone for date bucketing (e.g., 'America/Los_Angeles')" }, { "schema": { "type": "string" }, "in": "query", "name": "path", "required": false, "description": "Filter by specific page path" }, { "schema": { "type": "string", "enum": [ "exact", "partial" ] }, "in": "query", "name": "pathMatch", "required": false, "description": "Path matching mode: 'exact' for exact match, 'partial' for prefix match (default: 'partial')" }, { "schema": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AR", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BM", "BN", "BO", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CD", "CF", "CG", "CH", "CI", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ES", "ET", "FI", "FJ", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GT", "GU", "GW", "GY", "HK", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KN", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MG", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NG", "NI", "NL", "NO", "NP", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PR", "PS", "PT", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SC", "SD", "SE", "SG", "SI", "SK", "SL", "SN", "SO", "SR", "SS", "SV", "SX", "SZ", "TC", "TD", "TG", "TH", "TJ", "TM", "TN", "TR", "TT", "TW", "TZ", "UA", "UG", "US", "UY", "UZ", "VC", "VE", "VG", "VI", "VN", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "in": "query", "name": "location", "required": false, "description": "Filter by geographic location (ISO 3166-1 alpha-2 country code, e.g. US, GB, DE)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "example": [ { "date": "2026-03-14", "total_visits": 1180 }, { "date": "2026-03-15", "total_visits": 1245 } ], "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Date for the data point" }, "total_visits": { "type": "number", "description": "Total visits for the date" } }, "required": [ "date", "total_visits" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/analytics/visitors/trend": { "get": { "operationId": "getVisitorTrends", "summary": "Visitor Trends", "tags": [ "Analytics" ], "description": "Get visitor trends grouped by referrer", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for analytics data (YYYY-MM-DD). Max range 60 days." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for analytics data (YYYY-MM-DD). Max range 60 days." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, { "type": "array", "items": { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, "maxItems": 8 } ] }, "in": "query", "name": "referrerDomains", "required": false, "description": "Filter by AI referrer domains (repeat param for multiple). Allowed: chatgpt.com, gemini.google.com, perplexity.ai, copilot.microsoft.com, copilot.com, claude.ai, grok.com, chat.mistral.ai" }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false, "description": "IANA timezone for date bucketing (e.g., 'America/Los_Angeles')" }, { "schema": { "type": "string" }, "in": "query", "name": "path", "required": false, "description": "Filter by specific page path" }, { "schema": { "type": "string", "enum": [ "exact", "partial" ] }, "in": "query", "name": "pathMatch", "required": false, "description": "Path matching mode: 'exact' for exact match, 'partial' for prefix match (default: 'partial')" }, { "schema": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AR", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BM", "BN", "BO", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CD", "CF", "CG", "CH", "CI", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ES", "ET", "FI", "FJ", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GT", "GU", "GW", "GY", "HK", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KN", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MG", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NG", "NI", "NL", "NO", "NP", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PR", "PS", "PT", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SC", "SD", "SE", "SG", "SI", "SK", "SL", "SN", "SO", "SR", "SS", "SV", "SX", "SZ", "TC", "TD", "TG", "TH", "TJ", "TM", "TN", "TR", "TT", "TW", "TZ", "UA", "UG", "US", "UY", "UZ", "VC", "VE", "VG", "VI", "VN", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "in": "query", "name": "location", "required": false, "description": "Filter by geographic location (ISO 3166-1 alpha-2 country code, e.g. US, GB, DE)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "dates": [ "2026-03-14", "2026-03-15" ], "series": [ { "name": "chatgpt.com", "data": [ 620, 655 ] }, { "name": "perplexity.ai", "data": [ 310, 328 ] } ] }, "properties": { "dates": { "type": "array", "items": { "type": "string", "description": "Date values" }, "description": "Array of dates for the time series" }, "series": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ], "description": "Referrer domain" }, "data": { "type": "array", "items": { "type": "number" }, "description": "Visit counts for each date" } }, "required": [ "name", "data" ], "additionalProperties": false }, "description": "Time series data for each referrer" } }, "required": [ "dates", "series" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/analytics/visitors/referrer-stats": { "get": { "operationId": "getReferrerStats", "summary": "Referrer Stats", "tags": [ "Analytics" ], "description": "Get referrer comparison stats with period-over-period changes", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date (YYYY-MM-DD). Max range 60 days." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date (YYYY-MM-DD). Max range 60 days." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, { "type": "array", "items": { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, "minItems": 1, "maxItems": 8 } ] }, "in": "query", "name": "referrerDomains", "required": false, "description": "Referrer domains to compare (repeat param for multiple). Defaults to all known AI referrers: chatgpt.com, gemini.google.com, perplexity.ai, copilot.microsoft.com, copilot.com, claude.ai, grok.com, chat.mistral.ai" }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "path", "required": false }, { "schema": { "type": "string", "enum": [ "exact", "partial" ] }, "in": "query", "name": "pathMatch", "required": false }, { "schema": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AR", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BM", "BN", "BO", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CD", "CF", "CG", "CH", "CI", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ES", "ET", "FI", "FJ", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GT", "GU", "GW", "GY", "HK", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KN", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MG", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NG", "NI", "NL", "NO", "NP", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PR", "PS", "PT", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SC", "SD", "SE", "SG", "SI", "SK", "SL", "SN", "SO", "SR", "SS", "SV", "SX", "SZ", "TC", "TD", "TG", "TH", "TJ", "TM", "TN", "TR", "TT", "TW", "TZ", "UA", "UG", "US", "UY", "UZ", "VC", "VE", "VG", "VI", "VN", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "in": "query", "name": "location", "required": false, "description": "Filter by geographic location (ISO 3166-1 alpha-2 country code)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "referrer": "chatgpt.com", "visits": 5400, "hits": 9100, "visitsPrevious": 5000, "hitsPrevious": 8600, "visitsChangePercentage": 8, "hitsChangePercentage": 5.8 }, { "referrer": "claude.ai", "visits": 2100, "hits": 3400, "visitsPrevious": 1900, "hitsPrevious": 3100, "visitsChangePercentage": 10.5, "hitsChangePercentage": 9.7 } ] }, "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "referrer": { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ], "description": "Referrer domain" }, "visits": { "type": "number" }, "hits": { "type": "number" }, "visitsPrevious": { "type": "number" }, "hitsPrevious": { "type": "number" }, "visitsChangePercentage": { "type": "number" }, "hitsChangePercentage": { "type": "number" } }, "required": [ "referrer", "visits", "hits", "visitsPrevious", "hitsPrevious", "visitsChangePercentage", "hitsChangePercentage" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/analytics/visitors/top-pages": { "get": { "operationId": "getTopPages", "summary": "Top Pages", "tags": [ "Analytics" ], "description": "Get top pages by visitor count", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for analytics data (YYYY-MM-DD). Max range 60 days." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for analytics data (YYYY-MM-DD). Max range 60 days." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, { "type": "array", "items": { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, "maxItems": 8 } ] }, "in": "query", "name": "referrerDomains", "required": false, "description": "Filter by AI referrer domains (repeat param for multiple). Allowed: chatgpt.com, gemini.google.com, perplexity.ai, copilot.microsoft.com, copilot.com, claude.ai, grok.com, chat.mistral.ai" }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false, "description": "IANA timezone for date bucketing (e.g., 'America/Los_Angeles')" }, { "schema": { "type": "string" }, "in": "query", "name": "path", "required": false, "description": "Filter by specific page path" }, { "schema": { "type": "string", "enum": [ "exact", "partial" ] }, "in": "query", "name": "pathMatch", "required": false, "description": "Path matching mode: 'exact' for exact match, 'partial' for prefix match (default: 'partial')" }, { "schema": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AR", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BM", "BN", "BO", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CD", "CF", "CG", "CH", "CI", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ES", "ET", "FI", "FJ", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GT", "GU", "GW", "GY", "HK", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KN", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MG", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NG", "NI", "NL", "NO", "NP", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PR", "PS", "PT", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SC", "SD", "SE", "SG", "SI", "SK", "SL", "SN", "SO", "SR", "SS", "SV", "SX", "SZ", "TC", "TD", "TG", "TH", "TJ", "TM", "TN", "TR", "TT", "TW", "TZ", "UA", "UG", "US", "UY", "UZ", "VC", "VE", "VG", "VI", "VN", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "in": "query", "name": "location", "required": false, "description": "Filter by geographic location (ISO 3166-1 alpha-2 country code, e.g. US, GB, DE)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "name": "/pricing", "value": 1840 }, { "name": "/blog/geo-guide", "value": 920 } ] }, "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "number" } }, "required": [ "name", "value" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/analytics/visitors/top-sources": { "get": { "operationId": "getTopSources", "summary": "Top Sources", "tags": [ "Analytics" ], "description": "Get top referrer sources by visitor count", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for analytics data (YYYY-MM-DD). Max range 60 days." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for analytics data (YYYY-MM-DD). Max range 60 days." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, { "type": "array", "items": { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, "maxItems": 8 } ] }, "in": "query", "name": "referrerDomains", "required": false, "description": "Filter by AI referrer domains (repeat param for multiple). Allowed: chatgpt.com, gemini.google.com, perplexity.ai, copilot.microsoft.com, copilot.com, claude.ai, grok.com, chat.mistral.ai" }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false, "description": "IANA timezone for date bucketing (e.g., 'America/Los_Angeles')" }, { "schema": { "type": "string" }, "in": "query", "name": "path", "required": false, "description": "Filter by specific page path" }, { "schema": { "type": "string", "enum": [ "exact", "partial" ] }, "in": "query", "name": "pathMatch", "required": false, "description": "Path matching mode: 'exact' for exact match, 'partial' for prefix match (default: 'partial')" }, { "schema": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AR", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BM", "BN", "BO", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CD", "CF", "CG", "CH", "CI", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ES", "ET", "FI", "FJ", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GT", "GU", "GW", "GY", "HK", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KN", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MG", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NG", "NI", "NL", "NO", "NP", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PR", "PS", "PT", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SC", "SD", "SE", "SG", "SI", "SK", "SL", "SN", "SO", "SR", "SS", "SV", "SX", "SZ", "TC", "TD", "TG", "TH", "TJ", "TM", "TN", "TR", "TT", "TW", "TZ", "UA", "UG", "US", "UY", "UZ", "VC", "VE", "VG", "VI", "VN", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "in": "query", "name": "location", "required": false, "description": "Filter by geographic location (ISO 3166-1 alpha-2 country code, e.g. US, GB, DE)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "name": "chatgpt.com", "value": 4400 }, { "name": "gemini.google.com", "value": 2100 } ] }, "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ], "description": "Referrer domain" }, "value": { "type": "number" } }, "required": [ "name", "value" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/analytics/visitors/top-locations": { "get": { "operationId": "getTopLocations", "summary": "Top Locations", "tags": [ "Analytics" ], "description": "Get top geographic locations by visitor count", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for analytics data (YYYY-MM-DD). Max range 60 days." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for analytics data (YYYY-MM-DD). Max range 60 days." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, { "type": "array", "items": { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, "maxItems": 8 } ] }, "in": "query", "name": "referrerDomains", "required": false, "description": "Filter by AI referrer domains (repeat param for multiple). Allowed: chatgpt.com, gemini.google.com, perplexity.ai, copilot.microsoft.com, copilot.com, claude.ai, grok.com, chat.mistral.ai" }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false, "description": "IANA timezone for date bucketing (e.g., 'America/Los_Angeles')" }, { "schema": { "type": "string" }, "in": "query", "name": "path", "required": false, "description": "Filter by specific page path" }, { "schema": { "type": "string", "enum": [ "exact", "partial" ] }, "in": "query", "name": "pathMatch", "required": false, "description": "Path matching mode: 'exact' for exact match, 'partial' for prefix match (default: 'partial')" }, { "schema": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AR", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BM", "BN", "BO", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CD", "CF", "CG", "CH", "CI", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ES", "ET", "FI", "FJ", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GT", "GU", "GW", "GY", "HK", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KN", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MG", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NG", "NI", "NL", "NO", "NP", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PR", "PS", "PT", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SC", "SD", "SE", "SG", "SI", "SK", "SL", "SN", "SO", "SR", "SS", "SV", "SX", "SZ", "TC", "TD", "TG", "TH", "TJ", "TM", "TN", "TR", "TT", "TW", "TZ", "UA", "UG", "US", "UY", "UZ", "VC", "VE", "VG", "VI", "VN", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "in": "query", "name": "location", "required": false, "description": "Filter by geographic location (ISO 3166-1 alpha-2 country code, e.g. US, GB, DE)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "name": "/pricing", "value": 1840 }, { "name": "/blog/geo-guide", "value": 920 } ] }, "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "number" } }, "required": [ "name", "value" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/analytics/visitors/top-devices": { "get": { "operationId": "getTopDevices", "summary": "Top Devices", "tags": [ "Analytics" ], "description": "Get top devices by visitor count", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for analytics data (YYYY-MM-DD). Max range 60 days." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for analytics data (YYYY-MM-DD). Max range 60 days." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, { "type": "array", "items": { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, "maxItems": 8 } ] }, "in": "query", "name": "referrerDomains", "required": false, "description": "Filter by AI referrer domains (repeat param for multiple). Allowed: chatgpt.com, gemini.google.com, perplexity.ai, copilot.microsoft.com, copilot.com, claude.ai, grok.com, chat.mistral.ai" }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false, "description": "IANA timezone for date bucketing (e.g., 'America/Los_Angeles')" }, { "schema": { "type": "string" }, "in": "query", "name": "path", "required": false, "description": "Filter by specific page path" }, { "schema": { "type": "string", "enum": [ "exact", "partial" ] }, "in": "query", "name": "pathMatch", "required": false, "description": "Path matching mode: 'exact' for exact match, 'partial' for prefix match (default: 'partial')" }, { "schema": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AR", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BM", "BN", "BO", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CD", "CF", "CG", "CH", "CI", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ES", "ET", "FI", "FJ", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GT", "GU", "GW", "GY", "HK", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KN", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MG", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NG", "NI", "NL", "NO", "NP", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PR", "PS", "PT", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SC", "SD", "SE", "SG", "SI", "SK", "SL", "SN", "SO", "SR", "SS", "SV", "SX", "SZ", "TC", "TD", "TG", "TH", "TJ", "TM", "TN", "TR", "TT", "TW", "TZ", "UA", "UG", "US", "UY", "UZ", "VC", "VE", "VG", "VI", "VN", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "in": "query", "name": "location", "required": false, "description": "Filter by geographic location (ISO 3166-1 alpha-2 country code, e.g. US, GB, DE)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "name": "/pricing", "value": 1840 }, { "name": "/blog/geo-guide", "value": 920 } ] }, "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "number" } }, "required": [ "name", "value" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/analytics/visitors/top-browsers": { "get": { "operationId": "getTopBrowsers", "summary": "Top Browsers", "tags": [ "Analytics" ], "description": "Get top browsers by visitor count", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for analytics data (YYYY-MM-DD). Max range 60 days." }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for analytics data (YYYY-MM-DD). Max range 60 days." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, { "type": "array", "items": { "type": "string", "enum": [ "chatgpt.com", "gemini.google.com", "perplexity.ai", "copilot.microsoft.com", "copilot.com", "claude.ai", "grok.com", "chat.mistral.ai" ] }, "maxItems": 8 } ] }, "in": "query", "name": "referrerDomains", "required": false, "description": "Filter by AI referrer domains (repeat param for multiple). Allowed: chatgpt.com, gemini.google.com, perplexity.ai, copilot.microsoft.com, copilot.com, claude.ai, grok.com, chat.mistral.ai" }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false, "description": "IANA timezone for date bucketing (e.g., 'America/Los_Angeles')" }, { "schema": { "type": "string" }, "in": "query", "name": "path", "required": false, "description": "Filter by specific page path" }, { "schema": { "type": "string", "enum": [ "exact", "partial" ] }, "in": "query", "name": "pathMatch", "required": false, "description": "Path matching mode: 'exact' for exact match, 'partial' for prefix match (default: 'partial')" }, { "schema": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AR", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BM", "BN", "BO", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CD", "CF", "CG", "CH", "CI", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ES", "ET", "FI", "FJ", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GT", "GU", "GW", "GY", "HK", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KN", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MG", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NG", "NI", "NL", "NO", "NP", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PR", "PS", "PT", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SC", "SD", "SE", "SG", "SI", "SK", "SL", "SN", "SO", "SR", "SS", "SV", "SX", "SZ", "TC", "TD", "TG", "TH", "TJ", "TM", "TN", "TR", "TT", "TW", "TZ", "UA", "UG", "US", "UY", "UZ", "VC", "VE", "VG", "VI", "VN", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] }, "in": "query", "name": "location", "required": false, "description": "Filter by geographic location (ISO 3166-1 alpha-2 country code, e.g. US, GB, DE)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "name": "/pricing", "value": 1840 }, { "name": "/blog/geo-guide", "value": 920 } ] }, "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "number" } }, "required": [ "name", "value" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/analytics/crawlers/trend": { "get": { "operationId": "getCrawlerActivityTrends", "summary": "Crawler Activity Trends", "tags": [ "Analytics" ], "description": "Get crawler activity trends over time. If the `crawlers` query parameter is omitted, the response includes all known AI crawler types that have data in the selected range (the server queries the full set of allowed crawler keys).", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for analytics data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for analytics data (YYYY-MM-DD)" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "openai-gptbot", "openai-searchbot", "openai-chatgpt-user", "openai-adsbot", "anthropic-claudebot", "anthropic-claude-user", "anthropic-claude-search-bot", "anthropic-claude-web", "anthropic-ai", "perplexity-bot", "perplexity-user", "cohere-ai", "mistral-ai-user", "mistral-ai-index", "deepseek-bot", "x-ai-grok-bot", "x-ai-grok-search", "x-ai-grok-deep-search", "google-extended", "google-mobile-agent", "google-desktop-agent", "meta-web-indexer", "meta-external-agent", "meta-external-fetcher", "meta-facebook-bot" ] }, { "type": "array", "items": { "type": "string", "enum": [ "openai-gptbot", "openai-searchbot", "openai-chatgpt-user", "openai-adsbot", "anthropic-claudebot", "anthropic-claude-user", "anthropic-claude-search-bot", "anthropic-claude-web", "anthropic-ai", "perplexity-bot", "perplexity-user", "cohere-ai", "mistral-ai-user", "mistral-ai-index", "deepseek-bot", "x-ai-grok-bot", "x-ai-grok-search", "x-ai-grok-deep-search", "google-extended", "google-mobile-agent", "google-desktop-agent", "meta-web-indexer", "meta-external-agent", "meta-external-fetcher", "meta-facebook-bot" ] } } ] }, "in": "query", "name": "crawlers", "required": false, "description": "Filter by crawler(s). Repeat for multiple: crawlers=openai-gptbot&crawlers=perplexity-bot. Allowed: openai-gptbot, openai-searchbot, openai-chatgpt-user, openai-adsbot, anthropic-claudebot, anthropic-claude-user, anthropic-claude-search-bot, anthropic-claude-web, anthropic-ai, perplexity-bot, perplexity-user, cohere-ai, mistral-ai-user, mistral-ai-index, deepseek-bot, x-ai-grok-bot, x-ai-grok-search, x-ai-grok-deep-search, google-extended, google-mobile-agent, google-desktop-agent, meta-web-indexer, meta-external-agent, meta-external-fetcher, meta-facebook-bot. If omitted, **crawler activity trend** uses every known key above; other operations that support this field may apply no per-crawler filter in the data store." }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false, "description": "IANA timezone for date bucketing (e.g., 'America/Los_Angeles')" }, { "schema": { "type": "string" }, "in": "query", "name": "path", "required": false, "description": "Filter by specific page path" }, { "schema": { "type": "string", "enum": [ "exact", "partial" ] }, "in": "query", "name": "pathMatch", "required": false, "description": "Path matching mode: 'exact' for exact match, 'partial' for prefix match (default: 'partial')" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "dates": [ "2026-03-14", "2026-03-15" ], "series": [ { "name": "OpenAI GPTBot", "data": [ 2100, 2240 ] }, { "name": "Perplexity Bot", "data": [ 980, 1012 ] } ] }, "properties": { "dates": { "type": "array", "items": { "type": "string", "description": "Date values" }, "description": "Array of dates for the time series" }, "series": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Crawler display name" }, "data": { "type": "array", "items": { "type": "number" }, "description": "Hit counts for each date" } }, "required": [ "name", "data" ], "additionalProperties": false }, "description": "Time series data for each crawler" } }, "required": [ "dates", "series" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/analytics/crawlers/top-pages": { "get": { "operationId": "getTopCrawlerPages", "summary": "Top Crawler Pages", "tags": [ "Analytics" ], "description": "Get top pages requested by crawlers", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for analytics data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for analytics data (YYYY-MM-DD)" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "openai-gptbot", "openai-searchbot", "openai-chatgpt-user", "openai-adsbot", "anthropic-claudebot", "anthropic-claude-user", "anthropic-claude-search-bot", "anthropic-claude-web", "anthropic-ai", "perplexity-bot", "perplexity-user", "cohere-ai", "mistral-ai-user", "mistral-ai-index", "deepseek-bot", "x-ai-grok-bot", "x-ai-grok-search", "x-ai-grok-deep-search", "google-extended", "google-mobile-agent", "google-desktop-agent", "meta-web-indexer", "meta-external-agent", "meta-external-fetcher", "meta-facebook-bot" ] }, { "type": "array", "items": { "type": "string", "enum": [ "openai-gptbot", "openai-searchbot", "openai-chatgpt-user", "openai-adsbot", "anthropic-claudebot", "anthropic-claude-user", "anthropic-claude-search-bot", "anthropic-claude-web", "anthropic-ai", "perplexity-bot", "perplexity-user", "cohere-ai", "mistral-ai-user", "mistral-ai-index", "deepseek-bot", "x-ai-grok-bot", "x-ai-grok-search", "x-ai-grok-deep-search", "google-extended", "google-mobile-agent", "google-desktop-agent", "meta-web-indexer", "meta-external-agent", "meta-external-fetcher", "meta-facebook-bot" ] } } ] }, "in": "query", "name": "crawlers", "required": false, "description": "Filter by crawler(s). Repeat for multiple: crawlers=openai-gptbot&crawlers=perplexity-bot. Allowed: openai-gptbot, openai-searchbot, openai-chatgpt-user, openai-adsbot, anthropic-claudebot, anthropic-claude-user, anthropic-claude-search-bot, anthropic-claude-web, anthropic-ai, perplexity-bot, perplexity-user, cohere-ai, mistral-ai-user, mistral-ai-index, deepseek-bot, x-ai-grok-bot, x-ai-grok-search, x-ai-grok-deep-search, google-extended, google-mobile-agent, google-desktop-agent, meta-web-indexer, meta-external-agent, meta-external-fetcher, meta-facebook-bot. If omitted, **crawler activity trend** uses every known key above; other operations that support this field may apply no per-crawler filter in the data store." }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false, "description": "IANA timezone for date bucketing (e.g., 'America/Los_Angeles')" }, { "schema": { "type": "string" }, "in": "query", "name": "path", "required": false, "description": "Filter by specific page path" }, { "schema": { "type": "string", "enum": [ "exact", "partial" ] }, "in": "query", "name": "pathMatch", "required": false, "description": "Path matching mode: 'exact' for exact match, 'partial' for prefix match (default: 'partial')" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "example": [ { "request_path": "/pricing", "requests": 184, "unique_crawlers": 4, "crawlers": [ "openai-gptbot", "perplexity-bot", "anthropic-ai", "google-extended" ] }, { "request_path": "/blog/geo-checklist", "requests": 96, "unique_crawlers": 3, "crawlers": [ "openai-gptbot", "perplexity-bot", "anthropic-claudebot" ] } ], "type": "array", "items": { "type": "object", "properties": { "request_path": { "type": "string", "description": "Path requested by crawlers, like '/blog/some-post'" }, "requests": { "type": "number", "description": "Number of requests to this path by crawlers." }, "unique_crawlers": { "type": "number", "description": "Number of unique crawlers that requested this path." }, "crawlers": { "type": "array", "items": { "type": "string" }, "description": "List of crawlers that requested this path." } }, "required": [ "request_path", "requests", "unique_crawlers", "crawlers" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/analytics/crawlers/events": { "get": { "operationId": "getCrawlerEvents", "summary": "Crawler activity events", "tags": [ "Analytics" ], "description": "List individual AI crawler HTTP requests (event log) for the project, with pagination and filters. Same data as the in-product crawler activity explorer.", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for analytics data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for analytics data (YYYY-MM-DD)" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "openai-gptbot", "openai-searchbot", "openai-chatgpt-user", "openai-adsbot", "anthropic-claudebot", "anthropic-claude-user", "anthropic-claude-search-bot", "anthropic-claude-web", "anthropic-ai", "perplexity-bot", "perplexity-user", "cohere-ai", "mistral-ai-user", "mistral-ai-index", "deepseek-bot", "x-ai-grok-bot", "x-ai-grok-search", "x-ai-grok-deep-search", "google-extended", "google-mobile-agent", "google-desktop-agent", "meta-web-indexer", "meta-external-agent", "meta-external-fetcher", "meta-facebook-bot" ] }, { "type": "array", "items": { "type": "string", "enum": [ "openai-gptbot", "openai-searchbot", "openai-chatgpt-user", "openai-adsbot", "anthropic-claudebot", "anthropic-claude-user", "anthropic-claude-search-bot", "anthropic-claude-web", "anthropic-ai", "perplexity-bot", "perplexity-user", "cohere-ai", "mistral-ai-user", "mistral-ai-index", "deepseek-bot", "x-ai-grok-bot", "x-ai-grok-search", "x-ai-grok-deep-search", "google-extended", "google-mobile-agent", "google-desktop-agent", "meta-web-indexer", "meta-external-agent", "meta-external-fetcher", "meta-facebook-bot" ] } } ] }, "in": "query", "name": "crawlers", "required": false, "description": "Filter by crawler(s). Repeat for multiple: crawlers=openai-gptbot&crawlers=perplexity-bot. Allowed: openai-gptbot, openai-searchbot, openai-chatgpt-user, openai-adsbot, anthropic-claudebot, anthropic-claude-user, anthropic-claude-search-bot, anthropic-claude-web, anthropic-ai, perplexity-bot, perplexity-user, cohere-ai, mistral-ai-user, mistral-ai-index, deepseek-bot, x-ai-grok-bot, x-ai-grok-search, x-ai-grok-deep-search, google-extended, google-mobile-agent, google-desktop-agent, meta-web-indexer, meta-external-agent, meta-external-fetcher, meta-facebook-bot. If omitted, **crawler activity trend** uses every known key above; other operations that support this field may apply no per-crawler filter in the data store." }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false, "description": "IANA timezone for consistency with other crawler analytics endpoints; does not alter raw event timestamps in this response." }, { "schema": { "type": "string" }, "in": "query", "name": "path", "required": false, "description": "Filter by specific page path" }, { "schema": { "type": "string", "enum": [ "exact", "partial" ] }, "in": "query", "name": "pathMatch", "required": false, "description": "Path matching mode: 'exact' for exact match, 'partial' for prefix match (default: 'partial')" }, { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number (1-based)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "size", "required": false, "description": "Page size (max 200)" }, { "schema": { "anyOf": [ { "type": "integer" }, { "type": "array", "items": { "type": "integer" } } ] }, "in": "query", "name": "statusCodes", "required": false, "description": "Filter by HTTP status code(s). Repeat the param for multiple values." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "When the crawler request was recorded" }, "statusCode": { "type": "integer", "description": "HTTP response status code" }, "requestMethod": { "type": "string", "description": "HTTP method (e.g. GET)" }, "requestPath": { "type": "string", "description": "Requested path" }, "hostname": { "type": "string", "description": "Request hostname" }, "userAgent": { "type": "string", "description": "User-Agent header value" }, "crawler": { "type": "string", "description": "Identified crawler key" }, "referrer": { "type": "string", "nullable": true, "description": "Referer header if present" }, "contentType": { "type": "string", "description": "Response Content-Type" }, "queryString": { "type": "string", "nullable": true, "description": "Query string if present" } }, "required": [ "timestamp", "statusCode", "requestMethod", "requestPath", "hostname", "userAgent", "crawler", "referrer", "contentType", "queryString" ], "additionalProperties": false }, "description": "Paginated crawler request events, newest first" }, "total": { "type": "integer", "description": "Total events matching filters (all pages)" }, "page": { "type": "integer", "description": "Current page (1-based)" }, "size": { "type": "integer", "description": "Page size" }, "totalPages": { "type": "integer", "description": "Total number of pages" } }, "required": [ "data", "total", "page", "size", "totalPages" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "CRAWLER_ANALYTICS_PROJECT_NOT_FOUND", "CRAWLER_ANALYTICS_EVENTS_FETCH_FAILED", "INTERNAL_ERROR" ], "example": "CRAWLER_ANALYTICS_PROJECT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Project not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "CRAWLER_ANALYTICS_PROJECT_NOT_FOUND", "CRAWLER_ANALYTICS_EVENTS_FETCH_FAILED", "INTERNAL_ERROR" ], "example": "CRAWLER_ANALYTICS_PROJECT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Project not found" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/brands": { "get": { "operationId": "listBrands", "summary": "List Brands", "tags": [ "Brands" ], "description": "Get all brands for the project.\n\n\n\nFavicons are available from a separate public endpoint (not part of API v2).
See Brand icons.", "parameters": [ { "schema": { "type": "string", "enum": [ "SELF", "DIRECT_COMPETITOR", "OTHER", "IGNORED" ] }, "in": "query", "name": "relation", "required": false, "description": "Filter by brand relation" }, { "schema": { "type": "string" }, "in": "query", "name": "query", "required": false, "description": "Search by brand name or domain" }, { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number (1-based)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "size", "required": false, "description": "Page size" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "brands": [ { "id": "6ba7b81d-9dad-11d1-80b4-00c04fd430c8", "name": "Example Brand", "domain": "example.com", "relation": "SELF" }, { "id": "6ba7b81e-9dad-11d1-80b4-00c04fd430c8", "name": "Fabrikam Co", "domain": "fabrikam.example", "relation": "DIRECT_COMPETITOR" } ], "total": 2, "page": 1, "size": 50, "totalPages": 1 }, "properties": { "brands": { "type": "array", "items": { "type": "object", "example": { "id": "6ba7b81c-9dad-11d1-80b4-00c04fd430c8", "name": "Contoso Insights", "domain": "contoso.example", "relation": "DIRECT_COMPETITOR" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Brand identifier" }, "name": { "type": "string", "description": "Brand name" }, "domain": { "type": "string", "nullable": true, "description": "Brand hostname when known (e.g. example.com)." }, "relation": { "type": "string", "enum": [ "SELF", "DIRECT_COMPETITOR", "OTHER", "IGNORED" ], "nullable": true, "description": "Brand relation to project" } }, "required": [ "id", "name" ], "additionalProperties": false }, "description": "Array of brands" }, "total": { "type": "integer", "description": "Total brands matching filters" }, "page": { "type": "integer", "description": "Page number (1-based)" }, "size": { "type": "integer", "description": "Page size" }, "totalPages": { "type": "integer", "description": "Total pages for this page size" } }, "required": [ "brands", "total" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "BRAND_NOT_FOUND", "message": "Brand not found" }, "properties": { "code": { "type": "string", "description": "Domain error code", "enum": [ "BRAND_NOT_FOUND", "BRAND_ALREADY_EXISTS", "BRAND_INVALID_NAME", "INTERNAL_ERROR" ], "example": "BRAND_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Brand not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "BRAND_NOT_FOUND", "message": "Brand not found" } }, "example2": { "value": { "code": "BRAND_ALREADY_EXISTS", "message": "Brand is already connected to the project" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } }, "post": { "operationId": "createBrand", "summary": "Create Brand", "tags": [ "Brands" ], "description": "Create or connect a brand to the project.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Brand name" }, "url": { "type": "string", "description": "Brand website URL" }, "relation": { "type": "string", "enum": [ "SELF", "DIRECT_COMPETITOR", "OTHER", "IGNORED" ], "description": "Brand relation to project" } }, "required": [ "name", "url", "relation" ], "additionalProperties": false } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "6ba7b81c-9dad-11d1-80b4-00c04fd430c8", "name": "Contoso Insights", "domain": "contoso.example", "relation": "DIRECT_COMPETITOR" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Brand identifier" }, "name": { "type": "string", "description": "Brand name" }, "domain": { "type": "string", "nullable": true, "description": "Brand hostname when known (e.g. example.com)." }, "relation": { "type": "string", "enum": [ "SELF", "DIRECT_COMPETITOR", "OTHER", "IGNORED" ], "nullable": true, "description": "Brand relation to project" } }, "required": [ "id", "name" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "BRAND_NOT_FOUND", "message": "Brand not found" }, "properties": { "code": { "type": "string", "description": "Domain error code", "enum": [ "BRAND_NOT_FOUND", "BRAND_ALREADY_EXISTS", "BRAND_INVALID_NAME", "INTERNAL_ERROR" ], "example": "BRAND_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Brand not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "BRAND_NOT_FOUND", "message": "Brand not found" } }, "example2": { "value": { "code": "BRAND_ALREADY_EXISTS", "message": "Brand is already connected to the project" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "BRAND_NOT_FOUND", "message": "Brand not found" }, "properties": { "code": { "type": "string", "description": "Domain error code", "enum": [ "BRAND_NOT_FOUND", "BRAND_ALREADY_EXISTS", "BRAND_INVALID_NAME", "INTERNAL_ERROR" ], "example": "BRAND_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Brand not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "BRAND_NOT_FOUND", "message": "Brand not found" } }, "example2": { "value": { "code": "BRAND_ALREADY_EXISTS", "message": "Brand is already connected to the project" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/brands/{id}": { "put": { "operationId": "updateBrand", "summary": "Update Brand", "tags": [ "Brands" ], "description": "Update brand relationship.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "relation": { "type": "string", "enum": [ "SELF", "DIRECT_COMPETITOR", "OTHER", "IGNORED" ], "nullable": true, "description": "Brand relation to project (null to remove)" } }, "required": [ "relation" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Brand ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "6ba7b81c-9dad-11d1-80b4-00c04fd430c8", "name": "Contoso Insights", "domain": "contoso.example", "relation": "DIRECT_COMPETITOR" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Brand identifier" }, "name": { "type": "string", "description": "Brand name" }, "domain": { "type": "string", "nullable": true, "description": "Brand hostname when known (e.g. example.com)." }, "relation": { "type": "string", "enum": [ "SELF", "DIRECT_COMPETITOR", "OTHER", "IGNORED" ], "nullable": true, "description": "Brand relation to project" } }, "required": [ "id", "name" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "BRAND_NOT_FOUND", "message": "Brand not found" }, "properties": { "code": { "type": "string", "description": "Domain error code", "enum": [ "BRAND_NOT_FOUND", "BRAND_ALREADY_EXISTS", "BRAND_INVALID_NAME", "INTERNAL_ERROR" ], "example": "BRAND_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Brand not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "BRAND_NOT_FOUND", "message": "Brand not found" } }, "example2": { "value": { "code": "BRAND_ALREADY_EXISTS", "message": "Brand is already connected to the project" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "BRAND_NOT_FOUND", "message": "Brand not found" }, "properties": { "code": { "type": "string", "description": "Domain error code", "enum": [ "BRAND_NOT_FOUND", "BRAND_ALREADY_EXISTS", "BRAND_INVALID_NAME", "INTERNAL_ERROR" ], "example": "BRAND_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Brand not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "BRAND_NOT_FOUND", "message": "Brand not found" } }, "example2": { "value": { "code": "BRAND_ALREADY_EXISTS", "message": "Brand is already connected to the project" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "BRAND_NOT_FOUND", "message": "Brand not found" }, "properties": { "code": { "type": "string", "description": "Domain error code", "enum": [ "BRAND_NOT_FOUND", "BRAND_ALREADY_EXISTS", "BRAND_INVALID_NAME", "INTERNAL_ERROR" ], "example": "BRAND_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Brand not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "BRAND_NOT_FOUND", "message": "Brand not found" } }, "example2": { "value": { "code": "BRAND_ALREADY_EXISTS", "message": "Brand is already connected to the project" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/analytics/brands/visibility-over-time": { "get": { "operationId": "getBrandVisibilityOverTime", "summary": "Brand Visibility Over Time", "tags": [ "Analytics" ], "description": "Get brand visibility over time.", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date (YYYY-MM-DD)" }, { "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "default": "daily" }, "in": "query", "name": "range", "required": false }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "models", "required": false, "description": "Filter by LLM models. Repeat for multiple" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "promptId", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "llmMonitorId", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } } ] }, "in": "query", "name": "promptTypes", "required": false, "description": "Filter by prompt type. Repeat for multiple" }, { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "skip", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludeSelf", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "DIRECT_COMPETITOR", "SELF", "IGNORED", "OTHER" ] }, { "type": "array", "items": { "type": "string", "enum": [ "DIRECT_COMPETITOR", "SELF", "IGNORED", "OTHER" ] } } ] }, "in": "query", "name": "relations", "required": false, "description": "Filter by brand relation. Repeat for multiple" }, { "schema": { "type": "string" }, "in": "query", "name": "query", "required": false } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "example": [ { "date": "2026-03-14", "brand": { "id": "6ba7b81d-9dad-11d1-80b4-00c04fd430c8", "name": "Example Brand", "domain": "example.com", "relation": "SELF" }, "averageVisibility": 58.2, "mentionCount": 42, "totalResponses": 55, "visibilityPercentage": 76.4 }, { "date": "2026-03-15", "brand": { "id": "6ba7b81d-9dad-11d1-80b4-00c04fd430c8", "name": "Example Brand", "domain": "example.com", "relation": "SELF" }, "averageVisibility": 61, "mentionCount": 45, "totalResponses": 58, "visibilityPercentage": 77.6 } ], "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Date (YYYY-MM-DD)" }, "brand": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string", "nullable": true }, "relation": { "type": "string", "nullable": true, "enum": [ "DIRECT_COMPETITOR", "SELF", "IGNORED", "OTHER" ] } }, "required": [ "id", "name" ], "additionalProperties": false }, "averageVisibility": { "type": "number" }, "mentionCount": { "type": "number" }, "totalResponses": { "type": "number" }, "visibilityPercentage": { "type": "number" } }, "required": [ "date", "brand", "averageVisibility", "mentionCount", "totalResponses", "visibilityPercentage" ], "additionalProperties": false } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "BRAND_NOT_FOUND", "message": "Brand not found" }, "properties": { "code": { "type": "string", "description": "Domain error code", "enum": [ "BRAND_NOT_FOUND", "BRAND_ALREADY_EXISTS", "BRAND_INVALID_NAME", "INTERNAL_ERROR" ], "example": "BRAND_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Brand not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "BRAND_NOT_FOUND", "message": "Brand not found" } }, "example2": { "value": { "code": "BRAND_ALREADY_EXISTS", "message": "Brand is already connected to the project" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/responses": { "get": { "operationId": "listResponses", "summary": "List Responses", "tags": [ "Responses" ], "description": "Get paginated list of responses with filtering options", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number (1-based)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "in": "query", "name": "size", "required": false, "description": "Page size" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "llmMonitorId", "required": false, "description": "Filter by monitor" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "promptId", "required": false, "description": "Prompt identifier" }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "models", "required": false, "description": "Filter by specific models" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "POSITIVE", "NEGATIVE", "NEUTRAL" ] } }, "in": "query", "name": "sentiment", "required": false, "description": "Filter by sentiment" }, { "schema": { "type": "boolean" }, "in": "query", "name": "mentionedOurBrand", "required": false, "description": "Filter by whether the brand was mentioned" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false, "description": "Filter responses created after this date" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "until", "required": false, "description": "Filter responses created before this date" }, { "schema": { "type": "string", "enum": [ "createdAt", "visibilityScore", "sentimentScore" ], "default": "createdAt" }, "in": "query", "name": "sortBy", "required": false, "description": "Field to sort by" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "in": "query", "name": "sortOrder", "required": false, "description": "Sort order" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "responses": [ { "id": "550e8400-e29b-41d4-a716-446655440003", "content": "Illustrative snippet of model output…", "model": "claude-sonnet-4-20250514", "provider": "anthropic", "visibilityScore": 65, "sentimentScore": null, "sentiment": "NEUTRAL", "toneOfVoice": null, "mentionedOurBrand": false, "competitorMentions": [], "citationCount": 0, "prompt": { "id": "6ba7b816-9dad-11d1-80b4-00c04fd430c8", "prompt": "How do I export a weekly visibility report?", "type": "BRAND_SPECIFIC", "intent": "INFORMATIONAL", "llmMonitor": { "id": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "name": "US English monitor" } }, "createdAt": "2026-03-28T10:00:00.000Z" } ], "total": 128, "page": 1, "size": 10, "totalPages": 13 }, "properties": { "responses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "LLM response identifier" }, "content": { "type": "string", "description": "The LLM response content" }, "model": { "type": "string", "description": "Model used for this response" }, "provider": { "type": "string", "description": "LLM provider" }, "visibilityScore": { "type": "number", "nullable": true, "description": "Visibility score for this response" }, "sentimentScore": { "type": "number", "nullable": true, "description": "Sentiment score for this response" }, "sentiment": { "type": "string", "enum": [ "POSITIVE", "NEGATIVE", "NEUTRAL" ], "nullable": true, "description": "Sentiment classification" }, "toneOfVoice": { "type": "string", "nullable": true, "description": "Detected tone of voice" }, "mentionedOurBrand": { "type": "boolean", "description": "Whether the project's brand was mentioned" }, "competitorMentions": { "type": "array", "items": { "type": "string" }, "description": "List of competitor brands mentioned" }, "citationCount": { "type": "number", "description": "Total number of citations in response" }, "brandMentions": { "type": "array", "items": { "type": "object", "properties": { "brandName": { "type": "string", "description": "Canonical brand name" }, "brandDomain": { "type": "string", "nullable": true, "description": "Primary brand domain" }, "relation": { "type": "string", "enum": [ "SELF", "DIRECT_COMPETITOR", "OTHER", "IGNORED" ], "description": "Brand relation to the project" }, "visibilityScore": { "type": "number", "description": "Visibility score for this brand mention (0-100)" }, "position": { "type": "number", "nullable": true, "description": "Position in the response (1st, 2nd, etc.)" }, "sentiment": { "type": "string", "enum": [ "POSITIVE", "NEGATIVE", "NEUTRAL" ], "nullable": true, "description": "Sentiment toward this brand in the response" }, "toneOfVoice": { "type": "string", "nullable": true, "description": "Detected tone of voice for this brand" } }, "required": [ "brandName", "relation", "visibilityScore" ], "additionalProperties": false }, "description": "Brands detected in this response with per-brand metrics" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Citation URL" }, "domain": { "type": "string", "description": "Citation domain" }, "rank": { "type": "number", "nullable": true, "description": "Page rank of the cited URL (single response only)" }, "title": { "type": "string", "nullable": true, "description": "Citation title" }, "sourceType": { "type": "string", "enum": [ "NEWS", "BLOG", "CORPORATE", "ACADEMIC", "GOVERNMENT", "WIKI", "INSTAGRAM", "TIKTOK", "X", "REDDIT", "YOUTUBE", "FACEBOOK", "LINKEDIN", "GITHUB", "STACKOVERFLOW", "MEDIUM", "SUBSTACK", "HACKERNEWS", "QUORA", "OTHER" ], "nullable": true, "description": "Source type classification of the cited URL" }, "contentType": { "type": "string", "enum": [ "NEWS_ARTICLE", "OPINION", "LISTICLE", "HOW_TO", "REVIEW", "COMPARISON", "CASE_STUDY", "INTERVIEW", "VIDEO", "PODCAST", "INFOGRAPHIC", "RESEARCH_PAPER", "REPORT", "DOCUMENTATION", "WIKI", "PRODUCT_PAGE", "LANDING_PAGE", "FORUM_POST", "SOCIAL_POST", "COMMENT", "QA", "PRESS_RELEASE", "FAQ", "GLOSSARY", "OTHER" ], "nullable": true, "description": "Content type classification of the cited URL" } }, "required": [ "url", "domain" ], "additionalProperties": false }, "description": "Citations in this response" }, "prompt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Prompt this response belongs to" }, "prompt": { "type": "string", "description": "Prompt text" }, "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ], "description": "Prompt classification" }, "intent": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ], "nullable": true, "description": "Search intent label when set" }, "llmMonitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Monitor identifier" }, "name": { "type": "string", "description": "Monitor display name" } }, "required": [ "id", "name" ], "description": "Monitor that owns the prompt" } }, "required": [ "id", "prompt", "type", "llmMonitor" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Response creation timestamp" } }, "required": [ "id", "content", "model", "provider", "mentionedOurBrand", "competitorMentions", "citationCount", "brandMentions", "citations", "prompt", "createdAt" ], "additionalProperties": false }, "description": "Array of responses" }, "total": { "type": "integer", "description": "Total items matching the request" }, "page": { "type": "integer", "description": "Page number (1-based)" }, "size": { "type": "integer", "description": "Page size" }, "totalPages": { "type": "integer", "description": "Total pages for this page size" } }, "required": [ "responses", "total", "page", "size", "totalPages" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "RESPONSE_NOT_FOUND", "PROMPT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "RESPONSE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Response not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" } }, "example2": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "RESPONSE_NOT_FOUND", "PROMPT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "RESPONSE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Response not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" } }, "example2": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/responses/{id}": { "get": { "operationId": "getResponse", "summary": "Get Response", "tags": [ "Responses" ], "description": "Get a single response by ID with full citations", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Response ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "550e8400-e29b-41d4-a716-446655440002", "content": "Northwind Analytics provides enterprise reporting dashboards. For pricing, compare plans on their website — example only, not factual.", "model": "gpt-4.1", "provider": "openai", "visibilityScore": 72.5, "sentimentScore": 0.33, "sentiment": "POSITIVE", "toneOfVoice": "professional", "mentionedOurBrand": true, "competitorMentions": [ "Contoso Insights" ], "citationCount": 2, "prompt": { "id": "6ba7b814-9dad-11d1-80b4-00c04fd430c8", "prompt": "Best analytics tools for mid-market teams?", "type": "ORGANIC", "intent": "COMMERCIAL", "llmMonitor": { "id": "6ba7b815-9dad-11d1-80b4-00c04fd430c8", "name": "US English monitor" } }, "brandMentions": [ { "brandName": "Northwind Analytics", "brandDomain": "northwind.example.com", "relation": "SELF", "visibilityScore": 85, "position": 1, "sentiment": "POSITIVE", "toneOfVoice": "professional" } ], "citations": [ { "url": "https://docs.example.com/pricing", "domain": "docs.example.com", "rank": 1, "title": "Pricing overview", "sourceType": "CORPORATE", "contentType": "PRODUCT_PAGE" }, { "url": "https://blog.example.com/compare", "domain": "blog.example.com", "rank": 2, "title": "Tool comparison (illustrative)", "sourceType": "BLOG", "contentType": "COMPARISON" } ], "createdAt": "2026-03-29T14:22:00.000Z" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "LLM response identifier" }, "content": { "type": "string", "description": "The LLM response content" }, "model": { "type": "string", "description": "Model used for this response" }, "provider": { "type": "string", "description": "LLM provider" }, "visibilityScore": { "type": "number", "nullable": true, "description": "Visibility score for this response" }, "sentimentScore": { "type": "number", "nullable": true, "description": "Sentiment score for this response" }, "sentiment": { "type": "string", "enum": [ "POSITIVE", "NEGATIVE", "NEUTRAL" ], "nullable": true, "description": "Sentiment classification" }, "toneOfVoice": { "type": "string", "nullable": true, "description": "Detected tone of voice" }, "mentionedOurBrand": { "type": "boolean", "description": "Whether the project's brand was mentioned" }, "competitorMentions": { "type": "array", "items": { "type": "string" }, "description": "List of competitor brands mentioned" }, "citationCount": { "type": "number", "description": "Total number of citations in response" }, "brandMentions": { "type": "array", "items": { "type": "object", "properties": { "brandName": { "type": "string", "description": "Canonical brand name" }, "brandDomain": { "type": "string", "nullable": true, "description": "Primary brand domain" }, "relation": { "type": "string", "enum": [ "SELF", "DIRECT_COMPETITOR", "OTHER", "IGNORED" ], "description": "Brand relation to the project" }, "visibilityScore": { "type": "number", "description": "Visibility score for this brand mention (0-100)" }, "position": { "type": "number", "nullable": true, "description": "Position in the response (1st, 2nd, etc.)" }, "sentiment": { "type": "string", "enum": [ "POSITIVE", "NEGATIVE", "NEUTRAL" ], "nullable": true, "description": "Sentiment toward this brand in the response" }, "toneOfVoice": { "type": "string", "nullable": true, "description": "Detected tone of voice for this brand" } }, "required": [ "brandName", "relation", "visibilityScore" ], "additionalProperties": false }, "description": "Brands detected in this response with per-brand metrics" }, "prompt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Prompt this response belongs to" }, "prompt": { "type": "string", "description": "Prompt text" }, "type": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ], "description": "Prompt classification" }, "intent": { "type": "string", "enum": [ "BRANDED", "INFORMATIONAL", "NAVIGATIONAL", "COMMERCIAL", "TRANSACTIONAL" ], "nullable": true, "description": "Search intent label when set" }, "llmMonitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Monitor identifier" }, "name": { "type": "string", "description": "Monitor display name" } }, "required": [ "id", "name" ], "description": "Monitor that owns the prompt" } }, "required": [ "id", "prompt", "type", "llmMonitor" ], "additionalProperties": false }, "citations": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Citation URL" }, "domain": { "type": "string", "description": "Citation domain" }, "rank": { "type": "number", "nullable": true, "description": "Page rank of the cited URL (single response only)" }, "title": { "type": "string", "nullable": true, "description": "Citation title" }, "sourceType": { "type": "string", "enum": [ "NEWS", "BLOG", "CORPORATE", "ACADEMIC", "GOVERNMENT", "WIKI", "INSTAGRAM", "TIKTOK", "X", "REDDIT", "YOUTUBE", "FACEBOOK", "LINKEDIN", "GITHUB", "STACKOVERFLOW", "MEDIUM", "SUBSTACK", "HACKERNEWS", "QUORA", "OTHER" ], "nullable": true, "description": "Source type classification of the cited URL" }, "contentType": { "type": "string", "enum": [ "NEWS_ARTICLE", "OPINION", "LISTICLE", "HOW_TO", "REVIEW", "COMPARISON", "CASE_STUDY", "INTERVIEW", "VIDEO", "PODCAST", "INFOGRAPHIC", "RESEARCH_PAPER", "REPORT", "DOCUMENTATION", "WIKI", "PRODUCT_PAGE", "LANDING_PAGE", "FORUM_POST", "SOCIAL_POST", "COMMENT", "QA", "PRESS_RELEASE", "FAQ", "GLOSSARY", "OTHER" ], "nullable": true, "description": "Content type classification of the cited URL" } }, "required": [ "url", "domain" ], "additionalProperties": false }, "description": "Full list of citations in the response" }, "createdAt": { "type": "string", "format": "date-time", "description": "Response creation timestamp" } }, "required": [ "id", "content", "model", "provider", "mentionedOurBrand", "competitorMentions", "citationCount", "brandMentions", "prompt", "citations", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "RESPONSE_NOT_FOUND", "PROMPT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "RESPONSE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Response not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" } }, "example2": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "RESPONSE_NOT_FOUND", "PROMPT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "RESPONSE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Response not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" } }, "example2": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/responses/summary": { "get": { "operationId": "getResponsesSummary", "summary": "Response Summary", "tags": [ "Responses" ], "description": "Get response summary including total responses and brand mentions", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for data (YYYY-MM-DD)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "totalResponses": 240, "totalBrandMentions": 108, "brandMentionRate": 0.45 }, "properties": { "totalResponses": { "type": "number", "description": "Total number of LLM responses" }, "totalBrandMentions": { "type": "number", "description": "Total responses mentioning your brand" }, "brandMentionRate": { "type": "number", "description": "Percentage of responses mentioning your brand" } }, "required": [ "totalResponses", "totalBrandMentions", "brandMentionRate" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "RESPONSE_NOT_FOUND", "PROMPT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "RESPONSE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Response not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" } }, "example2": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/responses/mentions-time-series": { "get": { "operationId": "getMentionsTimeSeries", "summary": "Mentions Time Series", "tags": [ "Responses" ], "description": "Get brand and competitor mentions over time", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for data (YYYY-MM-DD)" }, { "schema": { "type": "string", "enum": [ "day", "week", "month" ], "default": "day" }, "in": "query", "name": "range", "required": false, "description": "Time grouping for the data (day, week, or month)" }, { "schema": { "type": "string" }, "in": "query", "name": "llmMonitorId", "required": false, "description": "Filter by specific LLM monitor ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "example": [ { "date": "2026-03-14T00:00:00.000Z", "brandMentions": 12, "competitorMentions": 34 }, { "date": "2026-03-15T00:00:00.000Z", "brandMentions": 15, "competitorMentions": 29 } ], "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time", "description": "Date of the data point" }, "brandMentions": { "type": "number", "nullable": true, "description": "Number of brand mentions" }, "competitorMentions": { "type": "number", "nullable": true, "description": "Number of competitor mentions" } }, "required": [ "date" ], "additionalProperties": false } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "RESPONSE_NOT_FOUND", "PROMPT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "RESPONSE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Response not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" } }, "example2": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/responses/competitors": { "get": { "operationId": "getTopCompetitors", "summary": "Top Competitors", "tags": [ "Responses" ], "description": "Get top competitor mentions from LLM responses", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for data (YYYY-MM-DD)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "example": [ { "competitor": "Contoso Insights", "count": 42, "percentage": 38.5 }, { "competitor": "Fabrikam Labs", "count": 28, "percentage": 25.7 } ], "items": { "type": "object", "properties": { "competitor": { "type": "string", "description": "Competitor name" }, "count": { "type": "number", "description": "Number of mentions" }, "percentage": { "type": "number", "description": "Percentage of total competitor mentions" } }, "required": [ "competitor", "count", "percentage" ], "additionalProperties": false } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "RESPONSE_NOT_FOUND", "PROMPT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "RESPONSE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Response not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" } }, "example2": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/responses/sentiment-distribution": { "get": { "operationId": "getSentimentDistribution", "summary": "Sentiment Distribution", "tags": [ "Responses" ], "description": "Get sentiment distribution of LLM responses", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for data (YYYY-MM-DD)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "example": [ { "sentiment": "POSITIVE", "count": 55, "percentage": 0.38 }, { "sentiment": "NEUTRAL", "count": 62, "percentage": 0.43 }, { "sentiment": "NEGATIVE", "count": 28, "percentage": 0.19 } ], "items": { "type": "object", "properties": { "sentiment": { "type": "string", "description": "Sentiment category (POSITIVE, NEGATIVE, NEUTRAL)" }, "count": { "type": "number", "description": "Number of responses with this sentiment" }, "percentage": { "type": "number", "description": "Percentage of total responses" } }, "required": [ "sentiment", "count", "percentage" ], "additionalProperties": false } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "RESPONSE_NOT_FOUND", "PROMPT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "RESPONSE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Response not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" } }, "example2": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/responses/sentiment-time-series": { "get": { "operationId": "getSentimentTimeSeries", "summary": "Sentiment Over Time", "tags": [ "Responses" ], "description": "Get sentiment changes over time for brand mentions", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for data (YYYY-MM-DD)" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "example": [ { "date": "2026-03-14", "positive": 18, "negative": 4, "neutral": 30, "unknown": 2 }, { "date": "2026-03-15", "positive": 21, "negative": 3, "neutral": 28, "unknown": 1 } ], "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Date of the data point" }, "positive": { "type": "number", "description": "Number of positive responses" }, "negative": { "type": "number", "description": "Number of negative responses" }, "neutral": { "type": "number", "description": "Number of neutral responses" }, "unknown": { "type": "number", "description": "Number of responses with unknown sentiment" } }, "required": [ "date", "positive", "negative", "neutral", "unknown" ], "additionalProperties": false } } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "RESPONSE_NOT_FOUND", "PROMPT_NOT_FOUND", "INTERNAL_ERROR" ], "example": "RESPONSE_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Response not found" } }, "required": [ "code", "message" ], "additionalProperties": false }, "examples": { "example1": { "value": { "code": "RESPONSE_NOT_FOUND", "message": "Response not found" } }, "example2": { "value": { "code": "PROMPT_NOT_FOUND", "message": "Prompt not found or access denied" } }, "example3": { "value": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } } } } } } } }, "/tags": { "get": { "operationId": "listTags", "summary": "List Tags", "tags": [ "Tags" ], "description": "Get all tags for the project with prompt counts", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "query", "required": false, "description": "Search query for tag name" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "tags": [ { "id": "6ba7b820-9dad-11d1-80b4-00c04fd430c8", "name": "Q2 campaign", "promptCount": 14 }, { "id": "6ba7b821-9dad-11d1-80b4-00c04fd430c8", "name": "Brand queries", "promptCount": 32 } ] }, "properties": { "tags": { "type": "array", "items": { "type": "object", "example": { "id": "6ba7b820-9dad-11d1-80b4-00c04fd430c8", "name": "Q2 campaign", "promptCount": 14 }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Tag unique identifier" }, "name": { "type": "string", "description": "Tag name" }, "promptCount": { "type": "number", "description": "Number of prompts using this tag" } }, "required": [ "id", "name", "promptCount" ], "additionalProperties": false }, "description": "Array of tags" } }, "required": [ "tags" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TAG_NOT_FOUND", "message": "Tag not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TAG_NOT_FOUND", "TAG_FORBIDDEN", "TAG_ALREADY_EXISTS", "TAG_INVALID_NAME", "TAG_INVALID_PROMPT", "TAG_INVALID_BRAND", "TAG_MISSING_BRAND_ID", "TAG_NO_VALID_TAGS_SUPPLIED", "INTERNAL_ERROR" ], "example": "TAG_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } }, "post": { "operationId": "createTags", "summary": "Create Tags", "tags": [ "Tags" ], "description": "Create one or more tags for the project", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Array of tag names to create" } }, "required": [ "names" ], "additionalProperties": false } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "tags": [ { "id": "6ba7b820-9dad-11d1-80b4-00c04fd430c8", "name": "Q2 campaign", "promptCount": 14 }, { "id": "6ba7b821-9dad-11d1-80b4-00c04fd430c8", "name": "Brand queries", "promptCount": 32 } ] }, "properties": { "tags": { "type": "array", "items": { "type": "object", "example": { "id": "6ba7b820-9dad-11d1-80b4-00c04fd430c8", "name": "Q2 campaign", "promptCount": 14 }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Tag unique identifier" }, "name": { "type": "string", "description": "Tag name" }, "promptCount": { "type": "number", "description": "Number of prompts using this tag" } }, "required": [ "id", "name", "promptCount" ], "additionalProperties": false }, "description": "Array of tags" } }, "required": [ "tags" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TAG_NOT_FOUND", "message": "Tag not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TAG_NOT_FOUND", "TAG_FORBIDDEN", "TAG_ALREADY_EXISTS", "TAG_INVALID_NAME", "TAG_INVALID_PROMPT", "TAG_INVALID_BRAND", "TAG_MISSING_BRAND_ID", "TAG_NO_VALID_TAGS_SUPPLIED", "INTERNAL_ERROR" ], "example": "TAG_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TAG_NOT_FOUND", "message": "Tag not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TAG_NOT_FOUND", "TAG_FORBIDDEN", "TAG_ALREADY_EXISTS", "TAG_INVALID_NAME", "TAG_INVALID_PROMPT", "TAG_INVALID_BRAND", "TAG_MISSING_BRAND_ID", "TAG_NO_VALID_TAGS_SUPPLIED", "INTERNAL_ERROR" ], "example": "TAG_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/tags/{id}": { "patch": { "operationId": "renameTag", "summary": "Rename Tag", "tags": [ "Tags" ], "description": "Rename an existing tag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "New name for the tag" } }, "required": [ "name" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tag ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "6ba7b820-9dad-11d1-80b4-00c04fd430c8", "name": "Q2 campaign", "promptCount": 14 }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Tag unique identifier" }, "name": { "type": "string", "description": "Tag name" }, "promptCount": { "type": "number", "description": "Number of prompts using this tag" } }, "required": [ "id", "name", "promptCount" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TAG_NOT_FOUND", "message": "Tag not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TAG_NOT_FOUND", "TAG_FORBIDDEN", "TAG_ALREADY_EXISTS", "TAG_INVALID_NAME", "TAG_INVALID_PROMPT", "TAG_INVALID_BRAND", "TAG_MISSING_BRAND_ID", "TAG_NO_VALID_TAGS_SUPPLIED", "INTERNAL_ERROR" ], "example": "TAG_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TAG_NOT_FOUND", "message": "Tag not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TAG_NOT_FOUND", "TAG_FORBIDDEN", "TAG_ALREADY_EXISTS", "TAG_INVALID_NAME", "TAG_INVALID_PROMPT", "TAG_INVALID_BRAND", "TAG_MISSING_BRAND_ID", "TAG_NO_VALID_TAGS_SUPPLIED", "INTERNAL_ERROR" ], "example": "TAG_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TAG_NOT_FOUND", "message": "Tag not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TAG_NOT_FOUND", "TAG_FORBIDDEN", "TAG_ALREADY_EXISTS", "TAG_INVALID_NAME", "TAG_INVALID_PROMPT", "TAG_INVALID_BRAND", "TAG_MISSING_BRAND_ID", "TAG_NO_VALID_TAGS_SUPPLIED", "INTERNAL_ERROR" ], "example": "TAG_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deleteTag", "summary": "Delete Tag", "tags": [ "Tags" ], "description": "Delete a tag and remove it from all prompts", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tag ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "Tag removed; empty body." }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TAG_NOT_FOUND", "message": "Tag not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TAG_NOT_FOUND", "TAG_FORBIDDEN", "TAG_ALREADY_EXISTS", "TAG_INVALID_NAME", "TAG_INVALID_PROMPT", "TAG_INVALID_BRAND", "TAG_MISSING_BRAND_ID", "TAG_NO_VALID_TAGS_SUPPLIED", "INTERNAL_ERROR" ], "example": "TAG_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TAG_NOT_FOUND", "message": "Tag not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TAG_NOT_FOUND", "TAG_FORBIDDEN", "TAG_ALREADY_EXISTS", "TAG_INVALID_NAME", "TAG_INVALID_PROMPT", "TAG_INVALID_BRAND", "TAG_MISSING_BRAND_ID", "TAG_NO_VALID_TAGS_SUPPLIED", "INTERNAL_ERROR" ], "example": "TAG_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/topics": { "get": { "operationId": "listTopics", "summary": "List Topics", "tags": [ "Topics" ], "description": "Get all topics for the project with prompt counts", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "topics": [ { "id": "6ba7b820-9dad-11d1-80b4-00c04fd430c8", "name": "seo tips", "promptCount": 7 }, { "id": "6ba7b821-9dad-11d1-80b4-00c04fd430c8", "name": "brand queries", "promptCount": 12 } ] }, "properties": { "topics": { "type": "array", "items": { "type": "object", "example": { "id": "6ba7b820-9dad-11d1-80b4-00c04fd430c8", "name": "seo tips", "promptCount": 7 }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Topic unique identifier" }, "name": { "type": "string", "description": "Topic name" }, "promptCount": { "type": "number", "description": "Number of prompts using this topic" } }, "required": [ "id", "name", "promptCount" ], "additionalProperties": false }, "description": "Array of topics" } }, "required": [ "topics" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TOPIC_NOT_FOUND", "message": "Topic not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TOPIC_NOT_FOUND", "TOPIC_FORBIDDEN", "TOPIC_ALREADY_EXISTS", "TOPIC_INVALID_NAME", "TOPIC_INVALID_PROMPT", "TOPIC_NO_VALID_TOPICS_SUPPLIED", "TOPIC_IN_USE", "INTERNAL_ERROR" ], "example": "TOPIC_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } }, "post": { "operationId": "createTopics", "summary": "Create Topics", "tags": [ "Topics" ], "description": "Create one or more topics for the project", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Array of topic names to create" } }, "required": [ "names" ], "additionalProperties": false } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "topics": [ { "id": "6ba7b820-9dad-11d1-80b4-00c04fd430c8", "name": "seo tips", "promptCount": 7 }, { "id": "6ba7b821-9dad-11d1-80b4-00c04fd430c8", "name": "brand queries", "promptCount": 12 } ] }, "properties": { "topics": { "type": "array", "items": { "type": "object", "example": { "id": "6ba7b820-9dad-11d1-80b4-00c04fd430c8", "name": "seo tips", "promptCount": 7 }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Topic unique identifier" }, "name": { "type": "string", "description": "Topic name" }, "promptCount": { "type": "number", "description": "Number of prompts using this topic" } }, "required": [ "id", "name", "promptCount" ], "additionalProperties": false }, "description": "Array of topics" } }, "required": [ "topics" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TOPIC_NOT_FOUND", "message": "Topic not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TOPIC_NOT_FOUND", "TOPIC_FORBIDDEN", "TOPIC_ALREADY_EXISTS", "TOPIC_INVALID_NAME", "TOPIC_INVALID_PROMPT", "TOPIC_NO_VALID_TOPICS_SUPPLIED", "TOPIC_IN_USE", "INTERNAL_ERROR" ], "example": "TOPIC_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TOPIC_NOT_FOUND", "message": "Topic not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TOPIC_NOT_FOUND", "TOPIC_FORBIDDEN", "TOPIC_ALREADY_EXISTS", "TOPIC_INVALID_NAME", "TOPIC_INVALID_PROMPT", "TOPIC_NO_VALID_TOPICS_SUPPLIED", "TOPIC_IN_USE", "INTERNAL_ERROR" ], "example": "TOPIC_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/topics/{id}": { "patch": { "operationId": "renameTopic", "summary": "Rename Topic", "tags": [ "Topics" ], "description": "Rename an existing topic", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "New name for the topic" } }, "required": [ "name" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Topic ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "6ba7b820-9dad-11d1-80b4-00c04fd430c8", "name": "seo tips" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Topic unique identifier" }, "name": { "type": "string", "description": "Topic name" } }, "required": [ "id", "name" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TOPIC_NOT_FOUND", "message": "Topic not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TOPIC_NOT_FOUND", "TOPIC_FORBIDDEN", "TOPIC_ALREADY_EXISTS", "TOPIC_INVALID_NAME", "TOPIC_INVALID_PROMPT", "TOPIC_NO_VALID_TOPICS_SUPPLIED", "TOPIC_IN_USE", "INTERNAL_ERROR" ], "example": "TOPIC_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TOPIC_NOT_FOUND", "message": "Topic not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TOPIC_NOT_FOUND", "TOPIC_FORBIDDEN", "TOPIC_ALREADY_EXISTS", "TOPIC_INVALID_NAME", "TOPIC_INVALID_PROMPT", "TOPIC_NO_VALID_TOPICS_SUPPLIED", "TOPIC_IN_USE", "INTERNAL_ERROR" ], "example": "TOPIC_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TOPIC_NOT_FOUND", "message": "Topic not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TOPIC_NOT_FOUND", "TOPIC_FORBIDDEN", "TOPIC_ALREADY_EXISTS", "TOPIC_INVALID_NAME", "TOPIC_INVALID_PROMPT", "TOPIC_NO_VALID_TOPICS_SUPPLIED", "TOPIC_IN_USE", "INTERNAL_ERROR" ], "example": "TOPIC_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deleteTopic", "summary": "Delete Topic", "tags": [ "Topics" ], "description": "Delete a topic and remove it from all prompts", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Topic ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "Topic removed; empty body." }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TOPIC_NOT_FOUND", "message": "Topic not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TOPIC_NOT_FOUND", "TOPIC_FORBIDDEN", "TOPIC_ALREADY_EXISTS", "TOPIC_INVALID_NAME", "TOPIC_INVALID_PROMPT", "TOPIC_NO_VALID_TOPICS_SUPPLIED", "TOPIC_IN_USE", "INTERNAL_ERROR" ], "example": "TOPIC_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "TOPIC_NOT_FOUND", "message": "Topic not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "TOPIC_NOT_FOUND", "TOPIC_FORBIDDEN", "TOPIC_ALREADY_EXISTS", "TOPIC_INVALID_NAME", "TOPIC_INVALID_PROMPT", "TOPIC_NO_VALID_TOPICS_SUPPLIED", "TOPIC_IN_USE", "INTERNAL_ERROR" ], "example": "TOPIC_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/actions": { "get": { "operationId": "listActionItems", "summary": "List action items", "tags": [ "Actions" ], "description": "Returns paginated action items for the project. Defaults to non-dismissed actions (page 1, size 50). Pass status=dismissed with an optional startDate to fetch dismissed actions.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "suggested", "dismissed", "todo", "in_progress", "done" ] }, { "type": "array", "items": { "type": "string", "enum": [ "suggested", "dismissed", "todo", "in_progress", "done" ] } } ] }, "in": "query", "name": "status", "required": false, "description": "Filter by status. Repeat for multiple: status=suggested&status=todo. Pass status=dismissed to fetch dismissed actions." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "WEBSITE_PERFORMANCE", "WEBSITE_HEALTH", "CONTENT_GAP", "SENTIMENT", "REDDIT_SOCIAL", "SETUP", "UNTRACKED_PAGE", "UNTAPPED_PAGE", "OFFSITE_MENTION" ] }, { "type": "array", "items": { "type": "string", "enum": [ "WEBSITE_PERFORMANCE", "WEBSITE_HEALTH", "CONTENT_GAP", "SENTIMENT", "REDDIT_SOCIAL", "SETUP", "UNTRACKED_PAGE", "UNTAPPED_PAGE", "OFFSITE_MENTION" ] } } ] }, "in": "query", "name": "type", "required": false, "description": "Filter by action type. Repeat for multiple: type=SETUP&type=CONTENT_GAP" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, { "type": "array", "items": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] } } ] }, "in": "query", "name": "severity", "required": false, "description": "Filter by severity. Repeat for multiple: severity=critical&severity=high" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "size", "required": false, "description": "Page size (default 50, max 200)" }, { "schema": { "type": "integer", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number (1-based, default 1)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Return dismissed actions dismissed on or after this date (YYYY-MM-DD, UTC). Only applied when status=dismissed. Defaults to the last 14 days when omitted." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "actions": [ { "id": "6ba7b820-9dad-11d1-80b4-00c04fd430c8", "projectId": "6ba7b821-9dad-11d1-80b4-00c04fd430c8", "type": "SETUP", "status": "todo", "severity": "high", "title": "Connect your sitemap", "description": "Add a sitemap so we can crawl your site.", "reasoning": "", "geoImpact": null, "data": { "type": "SETUP", "setupType": "SITEMAP", "status": "NOT_CONFIGURED" }, "completedAt": null, "dismissedAt": null, "createdAt": "2026-06-01T12:00:00.000Z", "updatedAt": "2026-06-01T12:00:00.000Z" } ], "total": 1, "page": 1, "size": 50, "totalPages": 1 }, "properties": { "actions": { "type": "array", "items": { "type": "object", "example": { "id": "6ba7b820-9dad-11d1-80b4-00c04fd430c8", "projectId": "6ba7b821-9dad-11d1-80b4-00c04fd430c8", "type": "SETUP", "status": "todo", "severity": "high", "title": "Connect your sitemap", "description": "Add a sitemap so we can crawl your site.", "reasoning": "", "geoImpact": null, "data": { "type": "SETUP", "setupType": "SITEMAP", "status": "NOT_CONFIGURED" }, "completedAt": null, "dismissedAt": null, "createdAt": "2026-06-01T12:00:00.000Z", "updatedAt": "2026-06-01T12:00:00.000Z" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Action item identifier" }, "projectId": { "type": "string", "format": "uuid", "description": "Project identifier" }, "type": { "type": "string", "enum": [ "WEBSITE_PERFORMANCE", "WEBSITE_HEALTH", "CONTENT_GAP", "SENTIMENT", "REDDIT_SOCIAL", "SETUP", "UNTRACKED_PAGE", "UNTAPPED_PAGE", "OFFSITE_MENTION" ], "description": "Action type" }, "status": { "type": "string", "enum": [ "suggested", "dismissed", "todo", "in_progress", "done" ], "description": "Action item status" }, "severity": { "type": "string", "nullable": true, "enum": [ "critical", "high", "medium", "low" ], "description": "Priority severity" }, "title": { "type": "string", "nullable": true, "description": "Card headline" }, "description": { "type": "string", "nullable": true, "description": "Card body" }, "reasoning": { "type": "string", "nullable": true, "description": "Evidence trail for the suggestion" }, "geoImpact": { "type": "string", "nullable": true, "description": "GEO visibility impact summary" }, "data": { "type": "object", "additionalProperties": true, "description": "Type-specific payload (discriminated union on `type`). Drill-down keys: CONTENT_GAP → use `data.promptId` with GET /content-gap/prompts/{promptId}/latest; WEBSITE_HEALTH → GET /site-health (optional issueTypes filter)." }, "completedAt": { "type": "string", "format": "date-time", "description": "Timestamp (ISO 8601)", "nullable": true }, "dismissedAt": { "type": "string", "format": "date-time", "description": "Timestamp (ISO 8601)", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp (ISO 8601)" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp (ISO 8601)" } }, "required": [ "id", "projectId", "type", "status", "data", "createdAt", "updatedAt" ], "additionalProperties": false }, "description": "Action items for the project matching the requested filters" }, "total": { "type": "integer", "description": "Total actions matching the filters" }, "page": { "type": "integer", "description": "Page number (1-based)" }, "size": { "type": "integer", "description": "Page size" }, "totalPages": { "type": "integer", "description": "Total pages for this page size" } }, "required": [ "actions", "total", "page", "size", "totalPages" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "UNIFIED_ACTION_NOT_FOUND", "message": "Action not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "UNIFIED_ACTION_NOT_FOUND", "INTERNAL_ERROR" ], "example": "UNIFIED_ACTION_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/actions/{id}": { "patch": { "operationId": "updateActionItemStatus", "summary": "Update action item status", "tags": [ "Actions" ], "description": "Updates an action item status (accept, dismiss, complete, etc.).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "suggested", "dismissed", "todo", "in_progress", "done" ], "description": "New status" } }, "required": [ "status" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Action item ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "6ba7b820-9dad-11d1-80b4-00c04fd430c8", "projectId": "6ba7b821-9dad-11d1-80b4-00c04fd430c8", "type": "SETUP", "status": "todo", "severity": "high", "title": "Connect your sitemap", "description": "Add a sitemap so we can crawl your site.", "reasoning": "", "geoImpact": null, "data": { "type": "SETUP", "setupType": "SITEMAP", "status": "NOT_CONFIGURED" }, "completedAt": null, "dismissedAt": null, "createdAt": "2026-06-01T12:00:00.000Z", "updatedAt": "2026-06-01T12:00:00.000Z" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Action item identifier" }, "projectId": { "type": "string", "format": "uuid", "description": "Project identifier" }, "type": { "type": "string", "enum": [ "WEBSITE_PERFORMANCE", "WEBSITE_HEALTH", "CONTENT_GAP", "SENTIMENT", "REDDIT_SOCIAL", "SETUP", "UNTRACKED_PAGE", "UNTAPPED_PAGE", "OFFSITE_MENTION" ], "description": "Action type" }, "status": { "type": "string", "enum": [ "suggested", "dismissed", "todo", "in_progress", "done" ], "description": "Action item status" }, "severity": { "type": "string", "nullable": true, "enum": [ "critical", "high", "medium", "low" ], "description": "Priority severity" }, "title": { "type": "string", "nullable": true, "description": "Card headline" }, "description": { "type": "string", "nullable": true, "description": "Card body" }, "reasoning": { "type": "string", "nullable": true, "description": "Evidence trail for the suggestion" }, "geoImpact": { "type": "string", "nullable": true, "description": "GEO visibility impact summary" }, "data": { "type": "object", "additionalProperties": true, "description": "Type-specific payload (discriminated union on `type`). Drill-down keys: CONTENT_GAP → use `data.promptId` with GET /content-gap/prompts/{promptId}/latest; WEBSITE_HEALTH → GET /site-health (optional issueTypes filter)." }, "completedAt": { "type": "string", "format": "date-time", "description": "Timestamp (ISO 8601)", "nullable": true }, "dismissedAt": { "type": "string", "format": "date-time", "description": "Timestamp (ISO 8601)", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp (ISO 8601)" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp (ISO 8601)" } }, "required": [ "id", "projectId", "type", "status", "data", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "UNIFIED_ACTION_NOT_FOUND", "message": "Action not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "UNIFIED_ACTION_NOT_FOUND", "INTERNAL_ERROR" ], "example": "UNIFIED_ACTION_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "UNIFIED_ACTION_NOT_FOUND", "message": "Action not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "UNIFIED_ACTION_NOT_FOUND", "INTERNAL_ERROR" ], "example": "UNIFIED_ACTION_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/personas": { "get": { "operationId": "listPersonas", "summary": "List Personas", "tags": [ "Personas" ], "description": "Get all personas for the project", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "personas": [ { "id": "6ba7b822-9dad-11d1-80b4-00c04fd430c8", "name": "Alex — procurement lead", "description": "Evaluates vendors for mid-market SaaS.", "ageRange": "35-44", "educationLevel": "College degree", "createdAt": "2026-02-10T12:00:00.000Z", "updatedAt": "2026-03-20T08:30:00.000Z" } ] }, "properties": { "personas": { "type": "array", "items": { "type": "object", "example": { "id": "6ba7b822-9dad-11d1-80b4-00c04fd430c8", "name": "Alex — procurement lead", "description": "Evaluates vendors for mid-market SaaS; cares about ROI and implementation time.", "ageRange": "35-44", "educationLevel": "College degree", "createdAt": "2026-02-10T12:00:00.000Z", "updatedAt": "2026-03-20T08:30:00.000Z" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Persona unique identifier" }, "name": { "type": "string", "description": "Persona name" }, "description": { "type": "string", "description": "Persona description" }, "ageRange": { "type": "string", "nullable": true, "description": "Target age range" }, "educationLevel": { "type": "string", "nullable": true, "description": "Education level" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "description", "createdAt", "updatedAt" ], "additionalProperties": false }, "description": "Array of personas" } }, "required": [ "personas" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PERSONA_NOT_FOUND", "message": "Persona not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PERSONA_NOT_FOUND", "PERSONA_FORBIDDEN", "PERSONA_ALREADY_EXISTS", "PERSONA_LAST_IN_PROJECT", "INTERNAL_ERROR" ], "example": "PERSONA_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } }, "post": { "operationId": "createPersona", "summary": "Create Persona", "tags": [ "Personas" ], "description": "Create a new persona for the project", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Persona name" }, "description": { "type": "string", "minLength": 1, "description": "Persona description" }, "ageRange": { "type": "string", "description": "Target age range" }, "educationLevel": { "type": "string", "description": "Education level" } }, "required": [ "name", "description" ], "additionalProperties": false } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "6ba7b822-9dad-11d1-80b4-00c04fd430c8", "name": "Alex — procurement lead", "description": "Evaluates vendors for mid-market SaaS; cares about ROI and implementation time.", "ageRange": "35-44", "educationLevel": "College degree", "createdAt": "2026-02-10T12:00:00.000Z", "updatedAt": "2026-03-20T08:30:00.000Z" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Persona unique identifier" }, "name": { "type": "string", "description": "Persona name" }, "description": { "type": "string", "description": "Persona description" }, "ageRange": { "type": "string", "nullable": true, "description": "Target age range" }, "educationLevel": { "type": "string", "nullable": true, "description": "Education level" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "description", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PERSONA_NOT_FOUND", "message": "Persona not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PERSONA_NOT_FOUND", "PERSONA_FORBIDDEN", "PERSONA_ALREADY_EXISTS", "PERSONA_LAST_IN_PROJECT", "INTERNAL_ERROR" ], "example": "PERSONA_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PERSONA_NOT_FOUND", "message": "Persona not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PERSONA_NOT_FOUND", "PERSONA_FORBIDDEN", "PERSONA_ALREADY_EXISTS", "PERSONA_LAST_IN_PROJECT", "INTERNAL_ERROR" ], "example": "PERSONA_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/personas/{id}": { "get": { "operationId": "getPersona", "summary": "Get Persona", "tags": [ "Personas" ], "description": "Get a specific persona by ID", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Persona ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "6ba7b822-9dad-11d1-80b4-00c04fd430c8", "name": "Alex — procurement lead", "description": "Evaluates vendors for mid-market SaaS; cares about ROI and implementation time.", "ageRange": "35-44", "educationLevel": "College degree", "createdAt": "2026-02-10T12:00:00.000Z", "updatedAt": "2026-03-20T08:30:00.000Z" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Persona unique identifier" }, "name": { "type": "string", "description": "Persona name" }, "description": { "type": "string", "description": "Persona description" }, "ageRange": { "type": "string", "nullable": true, "description": "Target age range" }, "educationLevel": { "type": "string", "nullable": true, "description": "Education level" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "description", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PERSONA_NOT_FOUND", "message": "Persona not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PERSONA_NOT_FOUND", "PERSONA_FORBIDDEN", "PERSONA_ALREADY_EXISTS", "PERSONA_LAST_IN_PROJECT", "INTERNAL_ERROR" ], "example": "PERSONA_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PERSONA_NOT_FOUND", "message": "Persona not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PERSONA_NOT_FOUND", "PERSONA_FORBIDDEN", "PERSONA_ALREADY_EXISTS", "PERSONA_LAST_IN_PROJECT", "INTERNAL_ERROR" ], "example": "PERSONA_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } }, "put": { "operationId": "updatePersona", "summary": "Update Persona", "tags": [ "Personas" ], "description": "Update an existing persona", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Persona name" }, "description": { "type": "string", "minLength": 1, "description": "Persona description" }, "ageRange": { "type": "string", "description": "Target age range" }, "educationLevel": { "type": "string", "description": "Education level" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Persona ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "6ba7b822-9dad-11d1-80b4-00c04fd430c8", "name": "Alex — procurement lead", "description": "Evaluates vendors for mid-market SaaS; cares about ROI and implementation time.", "ageRange": "35-44", "educationLevel": "College degree", "createdAt": "2026-02-10T12:00:00.000Z", "updatedAt": "2026-03-20T08:30:00.000Z" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Persona unique identifier" }, "name": { "type": "string", "description": "Persona name" }, "description": { "type": "string", "description": "Persona description" }, "ageRange": { "type": "string", "nullable": true, "description": "Target age range" }, "educationLevel": { "type": "string", "nullable": true, "description": "Education level" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "description", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PERSONA_NOT_FOUND", "message": "Persona not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PERSONA_NOT_FOUND", "PERSONA_FORBIDDEN", "PERSONA_ALREADY_EXISTS", "PERSONA_LAST_IN_PROJECT", "INTERNAL_ERROR" ], "example": "PERSONA_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PERSONA_NOT_FOUND", "message": "Persona not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PERSONA_NOT_FOUND", "PERSONA_FORBIDDEN", "PERSONA_ALREADY_EXISTS", "PERSONA_LAST_IN_PROJECT", "INTERNAL_ERROR" ], "example": "PERSONA_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PERSONA_NOT_FOUND", "message": "Persona not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PERSONA_NOT_FOUND", "PERSONA_FORBIDDEN", "PERSONA_ALREADY_EXISTS", "PERSONA_LAST_IN_PROJECT", "INTERNAL_ERROR" ], "example": "PERSONA_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deletePersona", "summary": "Delete Persona", "tags": [ "Personas" ], "description": "Delete a persona", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Persona ID" } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "Persona removed; empty body." }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PERSONA_NOT_FOUND", "message": "Persona not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PERSONA_NOT_FOUND", "PERSONA_FORBIDDEN", "PERSONA_ALREADY_EXISTS", "PERSONA_LAST_IN_PROJECT", "INTERNAL_ERROR" ], "example": "PERSONA_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PERSONA_NOT_FOUND", "message": "Persona not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PERSONA_NOT_FOUND", "PERSONA_FORBIDDEN", "PERSONA_ALREADY_EXISTS", "PERSONA_LAST_IN_PROJECT", "INTERNAL_ERROR" ], "example": "PERSONA_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/projects": { "get": { "operationId": "listProjects", "summary": "List Projects", "tags": [ "Projects" ], "description": "Get all projects for the organization (requires org-level API key, X-Project-Id header NOT required)", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "projects": [ { "id": "6ba7b81a-9dad-11d1-80b4-00c04fd430c8", "name": "Example Project", "slug": "example-project", "website": "https://www.example.com", "createdAt": "2026-01-10T09:00:00.000Z" }, { "id": "6ba7b81b-9dad-11d1-80b4-00c04fd430c8", "name": "Sandbox", "slug": "sandbox", "website": null, "createdAt": "2026-03-01T14:20:00.000Z" } ] }, "properties": { "projects": { "type": "array", "items": { "type": "object", "example": { "id": "6ba7b81a-9dad-11d1-80b4-00c04fd430c8", "name": "Example Project", "slug": "example-project", "website": "https://www.example.com", "createdAt": "2026-03-30T10:15:00.000Z" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Project unique identifier" }, "name": { "type": "string", "description": "Project name" }, "slug": { "type": "string", "description": "Project URL slug" }, "website": { "type": "string", "nullable": true, "description": "Project website URL" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "name", "slug", "createdAt" ], "additionalProperties": false }, "description": "Array of projects" } }, "required": [ "projects" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROJECT_NOT_FOUND", "PROJECT_FORBIDDEN", "PROJECT_DELETED", "PROJECT_LAST_IN_ORG", "PROJECT_ORG_FORBIDDEN", "PROJECT_ENRICHMENT_FAILED", "PROJECT_RETRIEVE_FAILED", "PROJECT_FETCH_FAILED", "PROJECT_ORG_ACCESS_CHECK_FAILED", "PROJECT_RETRIEVE_BY_ORG_FAILED", "PROJECT_SLUG_GENERATION_FAILED", "INTERNAL_ERROR" ], "example": "PROJECT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROJECT_NOT_FOUND", "PROJECT_FORBIDDEN", "PROJECT_DELETED", "PROJECT_LAST_IN_ORG", "PROJECT_ORG_FORBIDDEN", "PROJECT_ENRICHMENT_FAILED", "PROJECT_RETRIEVE_FAILED", "PROJECT_FETCH_FAILED", "PROJECT_ORG_ACCESS_CHECK_FAILED", "PROJECT_RETRIEVE_BY_ORG_FAILED", "PROJECT_SLUG_GENERATION_FAILED", "INTERNAL_ERROR" ], "example": "PROJECT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } }, "post": { "operationId": "createProject", "summary": "Create Project", "tags": [ "Projects" ], "description": "Create a new project (requires org-level API key, X-Project-Id header NOT required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Project name" }, "website": { "type": "string", "description": "Project website URL" }, "countryCode": { "type": "string", "description": "Country code (e.g., US)" }, "languageCode": { "type": "string", "description": "Language code (e.g., en)" } }, "required": [ "name", "website" ], "additionalProperties": false } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "id": "6ba7b81a-9dad-11d1-80b4-00c04fd430c8", "name": "Example Project", "slug": "example-project", "website": "https://www.example.com", "createdAt": "2026-03-30T10:15:00.000Z" }, "properties": { "id": { "type": "string", "format": "uuid", "description": "Project unique identifier" }, "name": { "type": "string", "description": "Project name" }, "slug": { "type": "string", "description": "Project URL slug" }, "website": { "type": "string", "nullable": true, "description": "Project website URL" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "name", "slug", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROJECT_NOT_FOUND", "PROJECT_FORBIDDEN", "PROJECT_DELETED", "PROJECT_LAST_IN_ORG", "PROJECT_ORG_FORBIDDEN", "PROJECT_ENRICHMENT_FAILED", "PROJECT_RETRIEVE_FAILED", "PROJECT_FETCH_FAILED", "PROJECT_ORG_ACCESS_CHECK_FAILED", "PROJECT_RETRIEVE_BY_ORG_FAILED", "PROJECT_SLUG_GENERATION_FAILED", "INTERNAL_ERROR" ], "example": "PROJECT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "402": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Payment Required", "message": "Cannot create prompt. Your organization has 50 of 50 active prompts. Please upgrade your plan to continue.", "current": 50, "limit": 50, "available": 0 }, "properties": { "error": { "type": "string", "description": "Fixed error label", "enum": [ "Payment Required" ] }, "message": { "type": "string", "description": "Explanation including usage and limit" }, "current": { "type": "integer", "description": "Current usage for this quota" }, "limit": { "type": "integer", "description": "Maximum allowed on the current plan" }, "available": { "type": "integer", "description": "Remaining quota (0 when blocked)" } }, "required": [ "error", "message", "current", "limit", "available" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROJECT_NOT_FOUND", "PROJECT_FORBIDDEN", "PROJECT_DELETED", "PROJECT_LAST_IN_ORG", "PROJECT_ORG_FORBIDDEN", "PROJECT_ENRICHMENT_FAILED", "PROJECT_RETRIEVE_FAILED", "PROJECT_FETCH_FAILED", "PROJECT_ORG_ACCESS_CHECK_FAILED", "PROJECT_RETRIEVE_BY_ORG_FAILED", "PROJECT_SLUG_GENERATION_FAILED", "INTERNAL_ERROR" ], "example": "PROJECT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "PROJECT_NOT_FOUND", "message": "Project not found" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "PROJECT_NOT_FOUND", "PROJECT_FORBIDDEN", "PROJECT_DELETED", "PROJECT_LAST_IN_ORG", "PROJECT_ORG_FORBIDDEN", "PROJECT_ENRICHMENT_FAILED", "PROJECT_RETRIEVE_FAILED", "PROJECT_FETCH_FAILED", "PROJECT_ORG_ACCESS_CHECK_FAILED", "PROJECT_RETRIEVE_BY_ORG_FAILED", "PROJECT_SLUG_GENERATION_FAILED", "INTERNAL_ERROR" ], "example": "PROJECT_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/competitor-heatmap": { "get": { "operationId": "getCompetitorVisibilityHeatmap", "summary": "Competitor Visibility Heatmap", "tags": [ "Visibility" ], "description": "Get competitor visibility heatmap data showing visibility percentages across different models and competitors. Returns a structured matrix ready for heatmap visualization. Use YYYY-MM-DD for startDate and endDate (full calendar days in UTC). Visibility percentages are rounded to 2 decimal places in the API response; the dashboard displays 1 decimal place.", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for heatmap data (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "End date for heatmap data (YYYY-MM-DD)" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "models", "required": false, "description": "Filter by LLM models. Repeat for multiple: models=x&models=y" }, { "schema": { "type": "string" }, "in": "query", "name": "promptId", "required": false, "description": "Filter by specific prompt ID" }, { "schema": { "type": "string" }, "in": "query", "name": "llmMonitorId", "required": false, "description": "Filter by specific LLM monitor ID" }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludeSelf", "required": false, "description": "Exclude self brand from results (default: false)" }, { "schema": { "type": "boolean" }, "in": "query", "name": "hideIgnoredBrands", "required": false, "description": "Hide ignored brands from results (default: true)" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "DIRECT_COMPETITOR", "SELF", "OTHER", "IGNORED" ] }, { "type": "array", "items": { "type": "string", "enum": [ "DIRECT_COMPETITOR", "SELF", "OTHER", "IGNORED" ] } } ] }, "in": "query", "name": "relations", "required": false, "description": "Filter to brand relations. Repeat for multiple: relations=DIRECT_COMPETITOR&relations=SELF" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Max number of top brands to include in the heatmap (default: 20)" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] }, { "type": "array", "items": { "type": "string", "enum": [ "ORGANIC", "BRAND_SPECIFIC", "COMPETITOR_COMPARISON" ] } } ] }, "in": "query", "name": "promptTypes", "required": false, "description": "Filter by prompt type. Repeat for multiple: promptTypes=ORGANIC&promptTypes=BRAND_SPECIFIC" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "array", "items": { "type": "string", "format": "uuid" } } ] }, "in": "query", "name": "tagIds", "required": false, "description": "Filter by prompt tag IDs. Repeat for multiple: tagIds=uuid1&tagIds=uuid2" }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "array", "items": { "type": "string", "format": "uuid" } } ] }, "in": "query", "name": "topicIds", "required": false, "description": "Filter by prompt topic IDs. Repeat for multiple: topicIds=uuid1&topicIds=uuid2" } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "Dashboard-equivalent (30-day window)", "source": "curl -X GET 'https://server.example.com/api/v2/competitor-heatmap?startDate=2026-04-20&endDate=2026-05-19&limit=20&hideIgnoredBrands=true' \\\n -H 'X-API-Key: YOUR_API_KEY' \\\n -H 'X-Project-Id: YOUR_PROJECT_ID'" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "models": [ "openai/gpt-4.1", "anthropic/claude-sonnet-4-20250514" ], "competitors": [ { "name": "Example Brand", "domain": "example.com", "relation": "SELF" }, { "name": "Contoso Insights", "domain": "contoso.example", "relation": "DIRECT_COMPETITOR" } ], "matrix": { "Contoso Insights": { "openai/gpt-4.1": 38.5, "anthropic/claude-sonnet-4-20250514": 41.2 }, "Example Brand": { "openai/gpt-4.1": 62, "anthropic/claude-sonnet-4-20250514": 58.75 } }, "minVisibility": 38.5, "maxVisibility": 62 }, "properties": { "models": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of model identifiers" }, "competitors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Brand or competitor label" }, "domain": { "type": "string", "nullable": true, "description": "Primary domain when known" }, "relation": { "type": "string", "nullable": true, "enum": [ "DIRECT_COMPETITOR", "SELF", "OTHER", "IGNORED" ], "description": "Configured relationship to your brand" } }, "required": [ "name" ] }, "description": "Ordered list of competitor information" }, "matrix": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "number", "nullable": true } }, "description": "Matrix of visibility percentages: matrix[competitor][model] = percentage" }, "minVisibility": { "type": "number", "description": "Minimum visibility value in the matrix" }, "maxVisibility": { "type": "number", "description": "Maximum visibility value in the matrix" } }, "required": [ "models", "competitors", "matrix", "minVisibility", "maxVisibility" ] } } } }, "204": { "description": "Default Response" }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/sitemap/progress": { "get": { "operationId": "getSitemapProgress", "summary": "Sitemap Crawl Progress", "tags": [ "Sitemap" ], "description": "Get sitemap crawl progress with counts and percentage", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "totalUrls": 500, "crawledUrls": 412, "notCrawledUrls": 88, "successfulCrawls": 380, "progressPercentage": 82.4, "crawlHealthScore": 76, "lastUpdated": "2026-03-30T08:00:00.000Z", "httpStatusBreakdown": { "success": { "count": 350, "percentage": 70 }, "redirect": { "count": 30, "percentage": 6 }, "clientError": { "count": 22, "percentage": 4.4 }, "serverError": { "count": 10, "percentage": 2 }, "notCrawled": { "count": 88, "percentage": 17.6 } }, "crawlAttempts": { "averageAttempts": 1.15, "maxAttempts": 4 } }, "properties": { "totalUrls": { "type": "number" }, "crawledUrls": { "type": "number" }, "notCrawledUrls": { "type": "number" }, "successfulCrawls": { "type": "number" }, "progressPercentage": { "type": "number", "description": "Percentage of URLs crawled (crawledUrls/totalUrls * 100)" }, "crawlHealthScore": { "type": "number", "description": "Percentage of all sitemap URLs successfully crawled (2xx + redirects) out of totalUrls (0-100)" }, "lastUpdated": { "type": "string", "format": "date-time" }, "httpStatusBreakdown": { "type": "object", "properties": { "success": { "type": "object", "properties": { "count": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "count", "percentage" ], "additionalProperties": false }, "redirect": { "type": "object", "properties": { "count": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "count", "percentage" ], "additionalProperties": false }, "clientError": { "type": "object", "properties": { "count": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "count", "percentage" ], "additionalProperties": false }, "serverError": { "type": "object", "properties": { "count": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "count", "percentage" ], "additionalProperties": false }, "notCrawled": { "type": "object", "properties": { "count": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "count", "percentage" ], "additionalProperties": false } }, "required": [ "success", "redirect", "clientError", "serverError", "notCrawled" ], "additionalProperties": false }, "crawlAttempts": { "type": "object", "properties": { "averageAttempts": { "type": "number" }, "maxAttempts": { "type": "number" } }, "required": [ "averageAttempts", "maxAttempts" ], "additionalProperties": false } }, "required": [ "totalUrls", "crawledUrls", "notCrawledUrls", "successfulCrawls", "progressPercentage", "crawlHealthScore", "lastUpdated", "httpStatusBreakdown", "crawlAttempts" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "INTERNAL_ERROR" ] }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/sitemap/urls": { "get": { "operationId": "listSitemapUrls", "summary": "List Sitemap URLs", "tags": [ "Sitemap" ], "description": "Paginated list of sitemap URLs for the project. Optionally use filter to narrow to errored (failed/blocked), redirected, or in-progress URLs.", "parameters": [ { "schema": { "type": "string", "enum": [ "errored", "redirected", "inProgress" ] }, "in": "query", "name": "filter", "required": false, "description": "Optional. Narrow results: errored (failed/blocked), redirected (3xx with target), inProgress (queued for crawl). Omit to return all crawl-scope URLs." }, { "schema": { "type": "integer", "default": 1, "minimum": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number (1-based)" }, { "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 }, "in": "query", "name": "size", "required": false, "description": "Page size" }, { "schema": { "type": "string", "enum": [ "canonical", "lastContentCrawlHttpStatus", "contentCrawlAttempts", "lastContentCrawledAt", "updatedAt", "createdAt" ], "default": "lastContentCrawledAt" }, "in": "query", "name": "sortBy", "required": false, "description": "Field to sort by" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "in": "query", "name": "sortOrder", "required": false, "description": "Sort direction" }, { "schema": { "anyOf": [ { "type": "integer" }, { "type": "array", "items": { "type": "integer" } } ] }, "in": "query", "name": "httpStatuses", "required": false, "description": "When filter=errored, restrict to specific HTTP status codes. Repeat the param for multiple values." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "url": "https://example.com/inventory/123", "rawUrl": "https://example.com/inventory/123/", "status": "ERROR", "httpStatus": 403, "crawlAttempts": 3, "lastCrawledAt": "2026-05-18T12:00:00.000Z", "redirectsTo": null, "createdAt": "2026-04-01T08:00:00.000Z", "updatedAt": "2026-05-18T12:00:00.000Z" } ], "total": 142, "page": 1, "size": 50, "totalPages": 3 }, "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Sitemap URL identifier" }, "url": { "type": "string", "description": "Canonical URL" }, "rawUrl": { "type": "string", "description": "Original URL as discovered" }, "status": { "type": "string", "enum": [ "DISCOVERED", "CRAWLED", "ERROR", "EXCLUDED", "REPROCESSING" ], "description": "Crawl lifecycle status" }, "httpStatus": { "type": "integer", "nullable": true, "description": "HTTP status from the last content crawl attempt" }, "crawlAttempts": { "type": "integer", "description": "Number of content crawl attempts" }, "lastCrawledAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When this URL was last content-crawled" }, "redirectsTo": { "type": "string", "nullable": true, "description": "Canonical target when the URL redirects (3xx)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "rawUrl", "status", "httpStatus", "crawlAttempts", "lastCrawledAt", "redirectsTo", "createdAt", "updatedAt" ], "additionalProperties": false } }, "total": { "type": "integer", "description": "Total items matching the request" }, "page": { "type": "integer", "description": "Page number (1-based)" }, "size": { "type": "integer", "description": "Page size" }, "totalPages": { "type": "integer", "description": "Total pages for this page size" } }, "required": [ "items", "total", "page", "size", "totalPages" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "INTERNAL_ERROR" ] }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } }, "/site-health": { "get": { "operationId": "getSiteHealth", "summary": "Site Health Pages", "tags": [ "Site Health" ], "description": "Pages with SEO issues (missing title/description, H1 problems, thin content). Omit issueTypes to return all issue types.", "parameters": [ { "schema": { "type": "integer", "default": 1, "minimum": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number (1-based)" }, { "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "in": "query", "name": "size", "required": false, "description": "Page size" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "missingTitle", "missingDescription", "noH1", "multipleH1", "thinContent" ] }, { "type": "array", "items": { "type": "string", "enum": [ "missingTitle", "missingDescription", "noH1", "multipleH1", "thinContent" ] } } ] }, "in": "query", "name": "issueTypes", "required": false, "description": "Filter by SEO issue type. Repeat for multiple: issueTypes=missingTitle&issueTypes=noH1. Omit for all." } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "pages": [ { "url": "https://example.com/no-title", "issue": "missingTitle", "crawledAt": "2026-05-18T12:00:00.000Z" } ], "total": 8, "page": 1, "size": 20, "totalPages": 1 }, "properties": { "pages": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Canonical page URL" }, "issue": { "type": "string", "enum": [ "missingTitle", "missingDescription", "noH1", "multipleH1", "thinContent" ], "description": "Detected SEO issue" }, "crawledAt": { "type": "string", "description": "Crawl timestamp (ISO) from the page document" } }, "required": [ "url" ], "additionalProperties": false }, "description": "Pages matching the requested issue types" }, "total": { "type": "integer", "description": "Total pages matching the requested issue types" }, "page": { "type": "integer", "description": "Page number (1-based)" }, "size": { "type": "integer", "description": "Page size" }, "totalPages": { "type": "integer", "description": "Total pages for this page size" } }, "required": [ "pages", "total", "page", "size", "totalPages" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Bad Request", "message": "Date range cannot exceed 60 days for this endpoint." }, "properties": { "error": { "type": "string", "description": "Error label" }, "message": { "type": "string", "description": "Reason the request was rejected" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Unauthorized", "message": "Missing or invalid X-API-Key header." }, "properties": { "error": { "type": "string", "description": "Error category (often aligned with HTTP semantics)" }, "code": { "type": "string", "description": "Optional machine-readable code" }, "message": { "type": "string", "description": "Human-readable explanation" }, "details": { "type": "object", "description": "Optional structured detail (e.g. validation)", "additionalProperties": true } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "SITE_HEALTH_WEBSITE_NOT_CONFIGURED", "message": "Project website is not configured" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "SITE_HEALTH_WEBSITE_NOT_CONFIGURED", "SITE_HEALTH_QUERY_FAILED", "INTERNAL_ERROR" ], "example": "SITE_HEALTH_WEBSITE_NOT_CONFIGURED" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "example": { "code": "SITE_HEALTH_WEBSITE_NOT_CONFIGURED", "message": "Project website is not configured" }, "properties": { "code": { "type": "string", "description": "Error code indicating the type of error", "enum": [ "SITE_HEALTH_WEBSITE_NOT_CONFIGURED", "SITE_HEALTH_QUERY_FAILED", "INTERNAL_ERROR" ], "example": "SITE_HEALTH_WEBSITE_NOT_CONFIGURED" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "message" ], "additionalProperties": false } } } } } } } }, "servers": [ { "url": "https://server.promptwatch.com/api/v2", "description": "Promptwatch API v2" } ], "tags": [ { "name": "Authentication", "description": "API key validation and authentication" }, { "name": "Content", "description": "AI content generation and optimization. Create content asynchronously and poll for results." }, { "name": "Content Gap", "description": "Content gap analysis and recommendations" }, { "name": "Models", "description": "Available LLM models" }, { "name": "Monitors", "description": "Monitor management and CRUD operations" }, { "name": "Page Tracker", "description": "Track URLs and inspect citation stats, responses, and prompts" }, { "name": "Prompts", "description": "Prompt management and operations" }, { "name": "Query Fanouts", "description": "ChatGPT query fanout keywords" }, { "name": "Responses", "description": "LLM response data and analytics" }, { "name": "Tags", "description": "Tag management for prompts" }, { "name": "Topics", "description": "Topic management for prompts" }, { "name": "Actions", "description": "Action items (GEO suggestions and tasks)" }, { "name": "Personas", "description": "Persona configuration for monitors" }, { "name": "Brands", "description": "Brand management for competitive analysis" }, { "name": "Visibility", "description": "Brand visibility time series and competitor heatmaps" }, { "name": "Citations", "description": "Citation analytics from AI responses" }, { "name": "Analytics", "description": "Visitor analytics, AI crawler logs, sentiment, and brand visibility trends" }, { "name": "Projects", "description": "Project management (organization-level keys only)" }, { "name": "Sitemap", "description": "Sitemap crawl progress and discovered URLs" }, { "name": "Site Health", "description": "Crawled pages with SEO issues (titles, meta descriptions, H1, thin content)" } ] }