{ "openapi": "3.0.3", "info": { "title": "Wellows Public API", "description": "## Overview\n\nThe Wellows Public API allows you to programmatically access your SEO analytics and AI-powered insights.\n\n## Authentication\n\nAll API requests require an API key passed in the `X-API-Key` header:\n\n```\nX-API-Key: your_api_key_here\n```\n\n### API Key Types\n\n- **USER-level keys**: Access all projects owned by your account. Requires `X-Project-ID` header for project-specific endpoints.\n- **PROJECT-level keys**: Scoped to a single project. No `X-Project-ID` header needed.\n\n## Response Format\n\nAll responses follow a standard format:\n\n```json\n{\n \"success\": true,\n \"message\": \"Success message\",\n \"code\": 200,\n \"data\": { ... },\n \"errors\": {},\n \"meta_data\": {}\n}\n```", "version": "1.0.0", "contact": { "name": "Wellows Digital Force", "url": "https://wellows.com" } }, "servers": [ { "url": "https://integrations.wellows.com/api/v1/", "description": "API for Wellows.com" } ], "tags": [ { "name": "Authentication", "description": "Validate API keys" }, { "name": "Projects", "description": "List and access project information" }, { "name": "Analytics", "description": "Retrieve SEO and AI analytics data" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/validate": { "get": { "tags": ["Authentication"], "summary": "Validate API key", "description": "Validate an API key and return its details.\n\nUse this endpoint to verify that an API key is valid.", "operationId": "validateApiKey", "parameters": [ { "name": "X-Project-ID", "in": "header", "description": "Project ID (optional - used to validate access to a specific project)", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "API key is valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResponse" }, "example": { "success": true, "message": "API key is valid", "code": 200, "data": { "valid": true, "key_level": "USER", "user_id": 123, "project_id": null, "expiry": "2025-12-31T23:59:59Z" }, "errors": {}, "meta_data": {} } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "message": "Invalid API key", "code": 401, "data": {}, "errors": { "error": "unauthorized", "detail": "API key is invalid or has expired" }, "meta_data": {} } } } } } } }, "/projects": { "get": { "tags": ["Projects"], "summary": "List accessible projects", "description": "List projects accessible by this API key.\n\n- **USER-level keys**: Returns all projects owned by the user\n- **PROJECT-level keys**: Returns only the associated project", "operationId": "listProjects", "responses": { "200": { "description": "Projects retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectsResponse" }, "example": { "success": true, "message": "Projects retrieved successfully", "code": 200, "data": { "projects": [ { "id": 1, "name": "my-project", "display_name": "My Project", "domain": "example.com", "region": "US", "language": "en", "status": "active", "created_at": "2024-01-15T10:30:00Z" } ], "total": 1 }, "errors": {}, "meta_data": {} } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "message": "Failed to retrieve projects", "code": 500, "data": {}, "errors": {}, "meta_data": {} } } } } } } }, "/overview": { "get": { "tags": ["Analytics"], "summary": "Get site summary overview", "description": "Get site summary overview analytics.\n\nReturns LLM presence statistics including:\n- Current day stats\n- Brands by topics\n- Brands by providers\n- Citation score\n- Sentiment analysis\n- Visibility score\n\n**Note**: For USER-level keys, the `X-Project-ID` header is required.", "operationId": "getOverview", "parameters": [ { "name": "X-Project-ID", "in": "header", "description": "Project ID (required for USER-level keys, optional for PROJECT-level keys)", "required": false, "schema": { "type": "integer" } }, { "name": "start_date", "in": "query", "description": "Start date for date range filter (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "end_date", "in": "query", "description": "End date for date range filter (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-31" } }, { "name": "region", "in": "query", "description": "Filter by region code", "required": false, "schema": { "type": "string", "example": "US" } }, { "name": "provider", "in": "query", "description": "Filter by LLM provider", "required": false, "schema": { "type": "string", "example": "openai" } } ], "responses": { "200": { "description": "Overview data retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverviewResponse" }, "example": { "success": true, "message": "Overview data retrieved successfully for 30 dates", "code": 200, "data": { "current_day_stats": { "visibility_score": 75.5, "citation_score": 82.3, "sentiment_score": 0.85 }, "brands_by_topics": { "topic1": ["brand1", "brand2"], "topic2": ["brand3"] }, "brands_by_providers": { "openai": ["brand1"], "anthropic": ["brand2"] }, "visibility_score": { "current": 75.5, "previous": 70.2, "trend": "up" }, "sentiment_analysis": { "positive": 0.7, "neutral": 0.2, "negative": 0.1 } }, "errors": {}, "meta_data": {} } } } }, "400": { "description": "Bad Request - X-Project-ID required for USER-level keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "message": "X-Project-ID header is required for USER-level API keys", "code": 400, "data": {}, "errors": { "error": "missing_project_id" }, "meta_data": {} } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - No access to the specified project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "message": "You do not have access to this project", "code": 403, "data": {}, "errors": { "error": "forbidden" }, "meta_data": {} } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "message": "Failed to retrieve overview data", "code": 500, "data": {}, "errors": {}, "meta_data": {} } } } } } } }, "/monitoring": { "get": { "tags": ["Analytics"], "summary": "Get site summary monitoring", "description": "Get site summary monitoring analytics with historical trends.\n\nReturns:\n- Brands by topics\n- Visibility score with history\n- Historical comparison with trends\n\n**Note**: For USER-level keys, the `X-Project-ID` header is required.", "operationId": "getMonitoring", "parameters": [ { "name": "X-Project-ID", "in": "header", "description": "Project ID (required for USER-level keys, optional for PROJECT-level keys)", "required": false, "schema": { "type": "integer" } }, { "name": "start_date", "in": "query", "description": "Start date for date range filter (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "end_date", "in": "query", "description": "End date for date range filter (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-31" } }, { "name": "region", "in": "query", "description": "Filter by region code", "required": false, "schema": { "type": "string", "example": "US" } }, { "name": "provider", "in": "query", "description": "Filter by LLM provider", "required": false, "schema": { "type": "string", "example": "openai" } } ], "responses": { "200": { "description": "Monitoring data retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringResponse" }, "example": { "success": true, "message": "Monitoring data retrieved successfully for 30 dates", "code": 200, "data": { "brands_by_topics": { "topic1": ["brand1", "brand2"], "topic2": ["brand3"] }, "visibility_score": { "current": 75.5, "history": [ {"date": "2024-01-01", "score": 70.2}, {"date": "2024-01-15", "score": 72.8}, {"date": "2024-01-30", "score": 75.5} ] }, "historical_comparison": { "current_period": { "start": "2024-01-01", "end": "2024-01-31", "visibility_score": 75.5 }, "previous_period": { "start": "2023-12-01", "end": "2023-12-31", "visibility_score": 70.2 }, "trend": "up", "change_percentage": 7.5 } }, "errors": {}, "meta_data": {} } } } }, "400": { "description": "Bad Request - X-Project-ID required for USER-level keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - No access to the specified project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "message": "Failed to retrieve monitoring data", "code": 500, "data": {}, "errors": {}, "meta_data": {} } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your API key from the API Keys page" } }, "schemas": { "StandardResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Request successful" }, "code": { "type": "integer", "example": 200 }, "data": { "type": "object" }, "errors": { "type": "object" }, "meta_data": { "type": "object" } }, "required": ["success", "message", "code", "data"] }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error description" }, "code": { "type": "integer", "example": 400 }, "data": { "type": "object" }, "errors": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } }, "meta_data": { "type": "object" } } }, "ValidationResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "API key is valid" }, "code": { "type": "integer", "example": 200 }, "data": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Always true if request succeeds", "example": true }, "key_level": { "type": "string", "enum": ["USER", "PROJECT"], "description": "API key scope level", "example": "USER" }, "user_id": { "type": "integer", "description": "ID of the key owner", "example": 123 }, "project_id": { "type": "integer", "nullable": true, "description": "Associated project ID (for PROJECT keys)", "example": 456 }, "expiry": { "type": "string", "format": "date-time", "nullable": true, "description": "Key expiration date (null if no expiry)", "example": "2025-12-31T23:59:59Z" } } }, "errors": { "type": "object" }, "meta_data": { "type": "object" } } }, "ProjectsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Projects retrieved successfully" }, "code": { "type": "integer", "example": 200 }, "data": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "total": { "type": "integer", "description": "Total number of projects", "example": 5 } } }, "errors": { "type": "object" }, "meta_data": { "type": "object" } } }, "Project": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique project identifier", "example": 1 }, "name": { "type": "string", "description": "Project slug/name", "example": "my-project" }, "display_name": { "type": "string", "nullable": true, "description": "Human-readable project name", "example": "My Project" }, "domain": { "type": "string", "description": "Website domain", "example": "example.com" }, "region": { "type": "string", "nullable": true, "description": "Project region code", "example": "US" }, "language": { "type": "string", "nullable": true, "description": "Project language code", "example": "en" }, "status": { "type": "string", "description": "Project status", "example": "active" }, "created_at": { "type": "string", "format": "date-time", "description": "Project creation timestamp", "example": "2024-01-15T10:30:00Z" } } }, "OverviewResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Overview data retrieved successfully for 30 dates" }, "code": { "type": "integer", "example": 200 }, "data": { "type": "object", "description": "Overview analytics data", "properties": { "current_day_stats": { "type": "object", "description": "Statistics for the current day", "properties": { "visibility_score": { "type": "number", "example": 75.5 }, "citation_score": { "type": "number", "example": 82.3 }, "sentiment_score": { "type": "number", "example": 0.85 } } }, "brands_by_topics": { "type": "object", "description": "Brands mentioned organized by topic", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "brands_by_providers": { "type": "object", "description": "Brands mentioned organized by LLM provider", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "visibility_score": { "type": "object", "description": "Visibility score with trend", "properties": { "current": { "type": "number", "example": 75.5 }, "previous": { "type": "number", "example": 70.2 }, "trend": { "type": "string", "enum": ["up", "down", "stable"], "example": "up" } } }, "sentiment_analysis": { "type": "object", "description": "Sentiment breakdown", "properties": { "positive": { "type": "number", "example": 0.7 }, "neutral": { "type": "number", "example": 0.2 }, "negative": { "type": "number", "example": 0.1 } } } } }, "errors": { "type": "object" }, "meta_data": { "type": "object" } } }, "MonitoringResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Monitoring data retrieved successfully for 30 dates" }, "code": { "type": "integer", "example": 200 }, "data": { "type": "object", "description": "Monitoring analytics data with historical trends", "properties": { "brands_by_topics": { "type": "object", "description": "Brands mentioned organized by topic", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "visibility_score": { "type": "object", "description": "Visibility score with historical data", "properties": { "current": { "type": "number", "example": 75.5 }, "history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "example": "2024-01-01" }, "score": { "type": "number", "example": 70.2 } } } } } }, "historical_comparison": { "type": "object", "description": "Comparison between current and previous periods", "properties": { "current_period": { "type": "object", "properties": { "start": { "type": "string", "format": "date", "example": "2024-01-01" }, "end": { "type": "string", "format": "date", "example": "2024-01-31" }, "visibility_score": { "type": "number", "example": 75.5 } } }, "previous_period": { "type": "object", "properties": { "start": { "type": "string", "format": "date", "example": "2023-12-01" }, "end": { "type": "string", "format": "date", "example": "2023-12-31" }, "visibility_score": { "type": "number", "example": 70.2 } } }, "trend": { "type": "string", "enum": ["up", "down", "stable"], "example": "up" }, "change_percentage": { "type": "number", "example": 7.5 } } } } }, "errors": { "type": "object" }, "meta_data": { "type": "object" } } } } } }