{ "openapi": "3.1.0", "info": { "title": "cloro", "description": "API for monitoring AI responses across different providers and regions", "license": { "name": "MIT" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.cloro.dev", "description": "Production server" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/monitor/chatgpt": { "post": { "summary": "Monitor ChatGPT Responses", "description": "Extract structured data from ChatGPT — answer text, cited sources, shopping cards, brand entities, and ads — for any prompt across supported regions", "operationId": "monitorChatgpt", "requestBody": { "description": "Request parameters for monitoring ChatGPT responses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatGPTMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "successful ChatGPT monitoring response", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 4 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatGPTMonitorResponse" } } } }, "400": { "description": "Bad Request - Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - Insufficient permissions or credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - Route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - Resource conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 4 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - Request was canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanceledError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "Bad Gateway - External service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/gemini": { "post": { "summary": "Monitor Gemini Responses", "description": "Extract structured data from Google Gemini — generated answer text and cited sources for any prompt, with Markdown and HTML export formats", "operationId": "monitorGemini", "requestBody": { "description": "Request parameters for monitoring Gemini responses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "successful Gemini monitoring response", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 4 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiMonitorResponse" } } } }, "400": { "description": "Bad Request - Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - Insufficient permissions or credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - Route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - Resource conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 4 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - Request was canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanceledError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "Bad Gateway - External service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/grok": { "post": { "summary": "Monitor Grok Responses", "description": "Extract structured data from Grok — answer text and cited sources, including X/Twitter references — for any prompt across supported regions", "operationId": "monitorGrok", "requestBody": { "description": "Request parameters for monitoring Grok responses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrokMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "successful Grok monitoring response", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 4 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 3 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrokMonitorResponse" } } } }, "400": { "description": "Bad Request - Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - Insufficient permissions or credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - Route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - Resource conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 4 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - Request was canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanceledError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "Bad Gateway - External service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/google": { "post": { "summary": "Monitor Google Search Results", "description": "Extract structured data from Google Search including organic results, People Also Ask, related searches, and optional AI Overview", "operationId": "monitorGoogle", "requestBody": { "description": "Request parameters for monitoring Google search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "successful Google monitoring response", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 997 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 3 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleMonitorResponse" } } } }, "400": { "description": "Bad Request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - Insufficient credits or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - Route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - Resource conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 4 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - Request was canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanceledError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "Bad Gateway - External service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/google/news": { "post": { "summary": "Monitor Google News Results", "description": "Extract structured news articles from Google News including titles, links, snippets, sources, dates, and thumbnails", "operationId": "monitorGoogleNews", "requestBody": { "description": "Request parameters for monitoring Google News results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleNewsMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "successful Google News monitoring response", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 997 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 3 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleNewsMonitorResponse" } } } }, "400": { "description": "Bad Request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - Insufficient credits or access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - Route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - Resource conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 4 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - Request was canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanceledError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "Bad Gateway - External service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/copilot": { "post": { "summary": "Monitor Copilot Responses", "description": "Extract structured data from Microsoft Copilot about your brand, products, or any topic across various regions", "operationId": "monitorCopilot", "requestBody": { "description": "Request parameters for monitoring Copilot responses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopilotMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "successful Copilot monitoring response", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 4 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 5 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopilotMonitorResponse" } } } }, "400": { "description": "Bad Request - Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - Insufficient permissions or credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - Route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - Resource conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 4 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - Request was canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanceledError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "Bad Gateway - External service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/perplexity": { "post": { "summary": "Monitor Perplexity Responses", "description": "Extract structured data from Perplexity AI about your brand, products, or any topic across various regions", "operationId": "monitorPerplexity", "requestBody": { "description": "Request parameters for monitoring Perplexity responses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerplexityMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "successful Perplexity monitoring response", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 4 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 5 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerplexityMonitorResponse" } } } }, "400": { "description": "Bad Request - Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - Insufficient permissions or credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - Route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - Resource conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 4 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - Request was canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanceledError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "Bad Gateway - External service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/aimode": { "post": { "summary": "Monitor AI Mode Responses", "description": "Extract structured data from AI Mode about your brand, products, or any topic across various regions", "operationId": "monitorAiMode", "requestBody": { "description": "Request parameters for monitoring AI Mode responses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiModeMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "successful AI Mode monitoring response", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 4 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 5 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiModeMonitorResponse" } } } }, "400": { "description": "Bad Request - Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - Insufficient permissions or credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - Route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - Resource conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-Concurrent-Limit": { "description": "Maximum number of concurrent requests allowed", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "Current number of concurrent requests", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Number of remaining concurrent slots available", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Number of credits remaining in user account", "schema": { "type": "integer", "example": 4 } }, "X-Credits-Charged": { "description": "Number of credits charged for this request", "schema": { "type": "integer", "example": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - Request was canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanceledError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "Bad Gateway - External service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/countries": { "get": { "summary": "List of countries", "description": "Returns a list of all supported ISO 3166-1 alpha-2 country codes. Can be filtered by model to get countries available for specific AI providers.", "operationId": "getCountries", "parameters": [ { "name": "model", "in": "query", "description": "Filter countries available for a specific model", "schema": { "type": "string", "enum": [ "aimode", "chatgpt", "copilot", "gemini", "google", "grok", "perplexity" ] }, "example": "chatgpt" } ], "responses": { "200": { "description": "List of supported country codes", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" }, "example": [ "AF", "AX", "AL", "DZ", "AS" ] } } } }, "400": { "description": "Bad Request - Invalid model parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "404": { "description": "Not Found - Route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } }, "/v1/async/task": { "post": { "summary": "Create async task", "description": "Submit an asynchronous task for background processing. Returns a task ID that you can use to poll for results or receive via webhook.", "operationId": "createAsyncTask", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchTaskRequest" }, "example": { "taskType": "CHATGPT", "priority": 5, "idempotencyKey": "your-custom-identifier-123", "webhook": { "url": "https://your-app.com/webhook-handler" }, "payload": { "prompt": "What is the weather in New York?", "country": "US" } } } } }, "responses": { "200": { "description": "Task created successfully. Returns task ID and initial status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncTaskCreateResponse" } } } }, "401": { "description": "Unauthorized - Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "409": { "description": "Conflict - Task with this idempotencyKey already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "422": { "description": "Validation Error - Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Queue Limit Exceeded - Organization has reached maximum queued tasks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueLimitError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } }, "/v1/async/task/batch": { "post": { "summary": "Create batch async tasks", "description": "Submit up to 500 async tasks in one request. Each task is validated independently, so one invalid task does not block the rest. Returns per-task results.", "operationId": "createBatchAsyncTasks", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 500, "description": "Array of task objects to create.", "items": { "$ref": "#/components/schemas/BatchTaskRequest" } }, "example": [ { "taskType": "CHATGPT", "priority": 5, "idempotencyKey": "batch-chatgpt-001", "webhook": { "url": "https://your-app.com/webhook-handler" }, "payload": { "prompt": "What do you know about Acme Corp?", "country": "US" } }, { "taskType": "PERPLEXITY", "priority": 3, "idempotencyKey": "batch-perplexity-001", "payload": { "prompt": "Latest news about Acme Corp", "country": "US" } } ] } } }, "responses": { "200": { "description": "Batch processed. Check the summary and individual results for per-task success or failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchTaskResponse" } } } }, "401": { "description": "Unauthorized - Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "422": { "description": "Validation Error - Request body is not a valid array or is empty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Queue Limit Exceeded - The entire batch is rejected because it would exceed your organization's queue capacity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueLimitError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } }, "/v1/async/task/{taskId}": { "get": { "summary": "Get async task status", "description": "Poll the status and result of an asynchronous task by ID. Returns the task state and, once complete, the full structured result payload.", "operationId": "getTaskStatus", "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "The ID of the task to fetch.", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response with the task status and result if completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskStatusResponse" } } } }, "401": { "description": "Unauthorized - Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "404": { "description": "Not Found - Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } }, "/v1/async/status": { "get": { "summary": "Get async queue status", "description": "Get organization-wide async queue metrics including queued and processing task counts, and concurrency usage.", "operationId": "getAsyncStatus", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response with queue metrics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncStatusResponse" } } } }, "401": { "description": "Unauthorized - Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } }, "/v1/states": { "get": { "summary": "List of states", "description": "Returns a list of US states supported for state-level geo-targeting. Only US is currently supported — other country values return an empty array.", "operationId": "getStates", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "ISO 3166-1 alpha-2 country code. Only \"US\" returns results.", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$" }, "example": "US" } ], "responses": { "200": { "description": "List of supported states", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "USPS two-letter state code", "example": "CA" }, "name": { "type": "string", "description": "Full state name", "example": "California" } }, "required": [ "code", "name" ] }, "example": [ { "code": "AL", "name": "Alabama" }, { "code": "AK", "name": "Alaska" }, { "code": "AZ", "name": "Arizona" }, { "code": "CA", "name": "California" }, { "code": "DC", "name": "District of Columbia" }, { "code": "NY", "name": "New York" }, { "code": "TX", "name": "Texas" } ] } } } }, "400": { "description": "Bad Request — missing or invalid country parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } } }, "components": { "schemas": { "AsyncTaskSummary": { "type": "object", "required": [ "id", "taskType", "status", "priority", "createdAt" ], "description": "Common task summary fields shared across async task responses.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique task identifier.", "example": "b27a21e1-7c39-4aa2-a347-23e828c426f9" }, "taskType": { "type": "string", "enum": [ "AIMODE", "GOOGLE", "GOOGLE_NEWS", "GEMINI", "CHATGPT", "COPILOT", "PERPLEXITY", "GROK" ], "description": "The AI provider for this task.", "example": "CHATGPT" }, "status": { "type": "string", "enum": [ "QUEUED", "PROCESSING", "COMPLETED", "FAILED" ], "description": "Current task status.", "example": "QUEUED" }, "priority": { "type": "integer", "description": "Task priority level (1-10). Higher numbers are processed first. Defaults to 1.", "minimum": 1, "maximum": 10, "example": 1 }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the task was created.", "example": "2026-04-09T15:00:00.000Z" }, "idempotencyKey": { "type": [ "string", "null" ], "description": "The idempotency key if one was provided.", "example": "batch-chatgpt-001" } } }, "AsyncTaskCredits": { "type": "object", "required": [ "creditsToCharge", "creditsCharged" ], "description": "Credit information for an async task.", "properties": { "creditsToCharge": { "type": "number", "description": "Credits reserved for this task.", "example": 10 }, "creditsCharged": { "type": [ "number", "null" ], "description": "Credits actually charged. Null until the task completes.", "example": null } } }, "AsyncTaskCreateResponse": { "type": "object", "required": [ "success", "task", "credits" ], "properties": { "success": { "type": "boolean", "example": true }, "task": { "$ref": "#/components/schemas/AsyncTaskSummary" }, "credits": { "$ref": "#/components/schemas/AsyncTaskCredits" } } }, "TaskStatusResponse": { "type": "object", "required": [ "task", "credits" ], "properties": { "task": { "$ref": "#/components/schemas/AsyncTaskSummary" }, "credits": { "$ref": "#/components/schemas/AsyncTaskCredits" }, "response": { "type": "object", "description": "The full response object, present only when the task is COMPLETED or FAILED." } } }, "AsyncStatusResponse": { "type": "object", "required": [ "queuedTasks", "processingTasks", "priorityBreakdown" ], "properties": { "queuedTasks": { "type": "integer", "description": "Number of tasks currently queued for this organization.", "example": 3 }, "processingTasks": { "type": "integer", "description": "Number of tasks currently being processed for this organization.", "example": 2 }, "priorityBreakdown": { "type": "array", "description": "Queued task counts per priority level, ordered by priority descending. Only includes priority levels that have queued tasks.", "items": { "type": "object", "required": [ "priority", "count" ], "properties": { "priority": { "type": "integer", "description": "The priority level (1-10).", "minimum": 1, "maximum": 10, "example": 5 }, "count": { "type": "integer", "description": "Number of queued tasks at this priority level.", "example": 2 } } } }, "concurrency": { "type": "object", "nullable": true, "description": "Current concurrency usage. Null if unable to retrieve concurrency information.", "properties": { "used": { "type": "integer", "description": "Number of concurrent slots currently in use.", "example": 2 }, "max": { "type": "integer", "description": "Maximum allowed concurrent tasks for this organization.", "example": 5 } } } } }, "BatchTaskRequest": { "type": "object", "required": [ "taskType", "payload" ], "properties": { "taskType": { "type": "string", "enum": [ "AIMODE", "GOOGLE", "GOOGLE_NEWS", "GEMINI", "CHATGPT", "COPILOT", "PERPLEXITY", "GROK" ], "description": "The AI provider to use for this task.", "example": "CHATGPT" }, "payload": { "type": "object", "description": "Provider-specific request payload. Must include at least `prompt` (or `query` for Google Search).", "example": { "prompt": "What do you know about Acme Corp?", "country": "US" } }, "priority": { "type": "integer", "description": "Task priority level (1-10). Higher numbers are processed first. Defaults to 1.", "minimum": 1, "maximum": 10, "default": 1, "example": 5 }, "idempotencyKey": { "type": "string", "description": "Unique string to prevent duplicate task creation. Must be unique across your account.", "example": "batch-chatgpt-001" }, "webhook": { "type": "object", "description": "Webhook configuration for task completion notification.", "properties": { "url": { "type": "string", "format": "uri", "description": "URL to receive the webhook POST request when the task completes.", "example": "https://your-app.com/webhook-handler" } }, "required": [ "url" ], "additionalProperties": false } }, "additionalProperties": false }, "BatchTaskResponse": { "type": "object", "required": [ "success", "summary", "results" ], "properties": { "success": { "type": "boolean", "description": "Always true for a successfully processed batch (individual tasks may still fail).", "example": true }, "summary": { "type": "object", "required": [ "total", "succeeded", "failed" ], "description": "Aggregate counts for the batch.", "properties": { "total": { "type": "integer", "description": "Total number of tasks submitted in the batch.", "example": 3 }, "succeeded": { "type": "integer", "description": "Number of tasks successfully created.", "example": 2 }, "failed": { "type": "integer", "description": "Number of tasks that failed validation or processing.", "example": 1 } } }, "results": { "type": "array", "description": "Per-task results preserving the original input order by index.", "items": { "oneOf": [ { "$ref": "#/components/schemas/BatchTaskSuccessResult" }, { "$ref": "#/components/schemas/BatchTaskFailureResult" } ], "discriminator": { "propertyName": "success", "mapping": { "true": "#/components/schemas/BatchTaskSuccessResult", "false": "#/components/schemas/BatchTaskFailureResult" } } } } } }, "BatchTaskSuccessResult": { "type": "object", "required": [ "success", "index", "task", "credits" ], "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Indicates this task was created successfully.", "example": true }, "index": { "type": "integer", "description": "The zero-based position of this task in the original request array.", "example": 0 }, "task": { "allOf": [ { "$ref": "#/components/schemas/AsyncTaskSummary" }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "QUEUED" ], "description": "Initial status of a newly created task.", "example": "QUEUED" } } } ] }, "credits": { "$ref": "#/components/schemas/AsyncTaskCredits" } } }, "BatchTaskFailureResult": { "type": "object", "required": [ "success", "index", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Indicates this task failed.", "example": false }, "index": { "type": "integer", "description": "The zero-based position of this task in the original request array.", "example": 2 }, "error": { "type": "object", "required": [ "code", "message", "timestamp" ], "properties": { "code": { "type": "string", "description": "Error code identifying the failure reason.", "enum": [ "VALIDATION_ERROR", "RESOURCE_ALREADY_EXISTS", "INSUFFICIENT_CREDITS" ], "example": "VALIDATION_ERROR" }, "message": { "type": "string", "description": "Human-readable error message.", "example": "Task validation failed" }, "details": { "type": "object", "description": "Additional context about the error, such as field-level validation failures.", "example": { "field": "payload.prompt", "message": "Required" } }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp when the error occurred.", "example": "2026-04-09T15:00:00.000Z" } } } } }, "QueueLimitError": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "required": [ "code", "message", "timestamp" ], "properties": { "code": { "type": "string", "enum": [ "QUEUE_LIMIT_EXCEEDED" ], "example": "QUEUE_LIMIT_EXCEEDED" }, "message": { "type": "string", "example": "Batch would exceed queue capacity" }, "details": { "type": "object", "properties": { "queuedCount": { "type": "integer", "description": "Current number of tasks in the queue.", "example": 99950 }, "batchSize": { "type": "integer", "description": "Number of tasks in the submitted batch.", "example": 100 }, "maxQueueSize": { "type": "integer", "description": "Maximum allowed queue size.", "example": 100000 }, "remainingCapacity": { "type": "integer", "description": "Number of tasks that can still be added to the queue.", "example": 50 } } }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-04-09T15:00:00.000Z" } } } } }, "ChatGPTMonitorRequest": { "required": [ "prompt", "country" ], "type": "object", "properties": { "prompt": { "description": "The prompt to send to ChatGPT", "type": "string", "minLength": 1, "maxLength": 10000, "example": "What do you know about Acme Corp?" }, "country": { "description": "Country/region code for localized response", "type": "string", "example": "US" }, "include": { "description": "Optional flags for including additional response formats", "type": "object", "default": { "html": false, "markdown": false, "rawResponse": false, "searchQueries": false, "ads": false, "shopping": false }, "properties": { "html": { "description": "Include a URL to the full HTML of the response", "type": "boolean", "default": false, "example": true }, "markdown": { "description": "Include markdown-formatted response in the result", "type": "boolean", "default": false, "example": true }, "rawResponse": { "description": "Include ChatGPT's raw response payload", "type": "boolean", "default": false, "example": true }, "searchQueries": { "description": "Include the query fan-out ChatGPT used to generate the response", "type": "boolean", "default": false, "example": true }, "ads": { "description": "Include ads displayed in ChatGPT response", "type": "boolean", "default": false, "example": true }, "shopping": { "description": "Include shopping cards and inline products with pricing and offers. Adds +2 credits to the base cost (shared with rawResponse, searchQueries, and ads — enabling any one or any combination adds the same +2).", "type": "boolean", "default": false, "example": true } }, "required": [], "example": { "html": true, "markdown": true, "rawResponse": true, "searchQueries": true, "ads": true, "shopping": true }, "additionalProperties": false }, "state": { "$ref": "#/components/schemas/StateParameter" } }, "additionalProperties": false }, "GeminiMonitorRequest": { "required": [ "prompt", "country" ], "type": "object", "properties": { "prompt": { "description": "The prompt to send to Gemini", "type": "string", "minLength": 1, "maxLength": 10000, "example": "Explain quantum computing" }, "country": { "description": "Country/region code for localized response", "type": "string", "example": "US" }, "include": { "description": "Optional flags for including additional response formats", "type": "object", "default": { "markdown": false, "html": false, "rawResponse": false }, "properties": { "markdown": { "description": "Include markdown-formatted response in the result", "type": "boolean", "default": false, "example": true }, "html": { "description": "Include HTML-formatted response in the result", "type": "boolean", "default": false, "example": true }, "rawResponse": { "description": "Include raw streaming response events", "type": "boolean", "default": false, "example": true } }, "required": [], "example": { "markdown": true, "html": false, "rawResponse": false }, "additionalProperties": false }, "state": { "$ref": "#/components/schemas/StateParameter" } }, "additionalProperties": false }, "GeminiMonitorResponse": { "required": [ "success", "result" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "description": "Gemini response data", "type": "object", "properties": { "text": { "type": "string", "description": "Gemini's response text", "example": "Quantum computing is a type of computation..." }, "markdown": { "type": "string", "description": "Gemini's response in Markdown format", "example": "**Quantum computing** is a type of computation..." }, "html": { "type": "string", "description": "Gemini's response in HTML format", "example": "

Quantum computing is a type of computation...

" }, "sources": { "type": "array", "description": "Sources cited by Gemini", "items": { "type": "object", "properties": { "position": { "type": "integer", "description": "Position of the source in the list", "example": 1 }, "label": { "type": "string", "description": "Label or title of the source", "example": "Wikipedia - Quantum Computing" }, "url": { "type": "string", "description": "URL of the source", "example": "https://en.wikipedia.org/wiki/Quantum_computing" }, "description": { "type": "string", "description": "Description or snippet of the source", "example": "Quantum computing is a multidisciplinary field..." } } } }, "citationPills": { "type": "array", "description": "Inline citation pills extracted from the Gemini answer. Each entry is one (pill, source) pair: when a chip cites N sources (Gemini's `+N` analog or section-summary chips), the array contains N entries sharing the same `citationPillId` but with per-source `label`, `url`, and `domain`. Group by `citationPillId` to recover the pill-level structure. `label` is always present on the wire; it can be an empty string when the rail has no title for a source. Omitted from `result` when the answer carries no pills.", "items": { "type": "object", "required": [ "label", "citationPillId", "url", "domain", "position" ], "properties": { "label": { "type": "string", "description": "Per-source title from the sources rail (for example `\"Quantum computing — Wikipedia\"`). Always present on the wire; may be an empty string when the rail has no title for this source — consumers should read `domain` / `url` for source identity in that case.", "example": "Quantum computing — Wikipedia" }, "citationPillId": { "type": "integer", "description": "1-based ordinal shared by all entries from the same chip. Group by `citationPillId` to reconstruct the visible chip; the per-source `label` differs across entries within a chip.", "example": 1 }, "url": { "type": "string", "description": "Direct URL of the cited source.", "example": "https://en.wikipedia.org/wiki/Quantum_computing" }, "domain": { "type": "string", "description": "Host extracted from `url`, for grouping and display.", "example": "en.wikipedia.org" }, "description": { "type": "string", "description": "Source description from the sources rail when Gemini ships one. Omitted when absent.", "example": "Quantum computing is a multidisciplinary field..." }, "position": { "type": "integer", "description": "1-based position of this source in the sibling `result.sources` array.", "example": 1 } } }, "example": [ { "label": "Quantum computing — Wikipedia", "citationPillId": 1, "url": "https://en.wikipedia.org/wiki/Quantum_computing", "domain": "en.wikipedia.org", "description": "Quantum computing is a multidisciplinary field...", "position": 1 }, { "label": "IBM Quantum", "citationPillId": 1, "url": "https://www.ibm.com/quantum", "domain": "ibm.com", "position": 3 } ] }, "rawResponse": { "type": "array", "description": "Raw upstream provider stream captured during the request. Each item is one chunk from the provider's wire protocol (SSE event, batchexecute frame, etc.). Format is provider-specific, undocumented, and may change without notice — use it for debugging or to access data not yet surfaced in the structured fields above.", "items": {} } } } } }, "GrokMonitorRequest": { "required": [ "prompt", "country" ], "type": "object", "properties": { "prompt": { "description": "The prompt to send to Grok", "type": "string", "minLength": 1, "maxLength": 10000, "example": "What are the best laptops for programming?" }, "country": { "description": "Country/region code for localized response", "type": "string", "example": "US" }, "include": { "description": "Optional flags for including additional response formats", "type": "object", "properties": { "markdown": { "description": "Include markdown-formatted response in the result", "type": "boolean", "default": false, "example": true }, "html": { "description": "Include HTML-formatted response in the result", "type": "boolean", "default": false, "example": true }, "rawResponse": { "description": "Include raw streaming response events", "type": "boolean", "default": false, "example": true } }, "default": { "markdown": false, "html": false, "rawResponse": false }, "additionalProperties": false }, "state": { "$ref": "#/components/schemas/StateParameter" } }, "additionalProperties": false }, "GrokMonitorResponse": { "required": [ "success", "result" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "description": "Grok response data", "type": "object", "properties": { "text": { "type": "string", "description": "Grok's response text", "example": "Based on current information and real-time web search, here are excellent laptop options for programming..." }, "html": { "type": "string", "format": "uri", "description": "A URL to the full HTML of the response.", "example": "https://storage.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html" }, "sources": { "type": "array", "description": "Array of sources referenced in the response with enhanced metadata", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "The position index of the source in the response", "example": 1 }, "url": { "type": "string", "description": "The URL of the source", "example": "https://example.com/article" }, "label": { "type": "string", "description": "The display label for the source", "example": "Tech Source" }, "description": { "type": "string", "description": "A description of the source content", "example": "In-depth laptop guide for developers" }, "preview": { "type": "string", "description": "Preview text snippet from the source", "example": "When choosing a laptop for programming, consider RAM, processor, storage..." }, "searchEngineText": { "type": "string", "description": "Search engine display text", "example": "Best Programming Laptops 2025" }, "siteName": { "type": "string", "description": "Website name", "example": "Tech Reviews" }, "metadataTitle": { "type": "string", "description": "Source metadata title", "example": "Complete Guide to Development Laptops" }, "creator": { "type": "string", "description": "Content creator/author", "example": "John Doe" }, "image": { "type": "string", "format": "uri", "description": "Source image URL", "example": "https://example.com/preview.jpg" }, "favicon": { "type": "string", "format": "uri", "description": "Website favicon URL", "example": "https://example.com/favicon.ico" } } }, "example": [ { "position": 1, "url": "https://techcrunch.com/programming-laptops", "label": "TechCrunch", "description": "Best laptops for coding and development", "preview": "When looking for a programming laptop, prioritize RAM and processor power...", "searchEngineText": "Top Development Laptops 2025", "siteName": "TechCrunch", "metadataTitle": "Ultimate Guide to Programming Laptops", "creator": "Tech Team", "image": "https://techcrunch.com/preview.jpg", "favicon": "https://techcrunch.com/favicon.ico" } ] }, "searchQueries": { "type": "array", "items": { "type": "string" }, "description": "Array of search queries Grok used to gather information for the response", "example": [ "best laptops for programming 2026", "top developer laptops 2026" ] }, "model": { "type": "string", "nullable": true, "description": "The model identifier used to generate the response", "example": "grok-4-auto" }, "markdown": { "type": "string", "description": "Grok's response formatted in Markdown (included when include.markdown is true)", "example": "Based on current information and real-time web search, here are excellent laptop options for programming..." }, "rawResponse": { "type": "array", "description": "Raw upstream provider stream captured during the request. Each item is one chunk from the provider's wire protocol (SSE event, batchexecute frame, etc.). Format is provider-specific, undocumented, and may change without notice — use it for debugging or to access data not yet surfaced in the structured fields above.", "items": {} } } } } }, "ChatGPTMonitorResponse": { "required": [ "success", "result" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "description": "ChatGPT's response data", "type": "object", "properties": { "text": { "type": "string", "description": "ChatGPT's response text", "example": "The name \"Acme Corporation\" is used in various contexts, both fictional and real. Here's an overview:\n\n🐾 Acme Corporation in Fiction\nThe Acme Corporation is a fictional company featured prominently in Warner Bros. cartoons, particularly the Road Runner/Wile E. Coyote series." }, "sources": { "type": "array", "description": "Array of sources referenced in the response. Returns empty array when no sources are available.", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "The position index of the source in the response", "example": 1 }, "url": { "type": "string", "description": "The URL of the source", "example": "https://www.rippling.com/blog/ai-recruiting?utm_source=chatgpt.com" }, "label": { "type": "string", "description": "The article title of the source", "example": "12 Best AI Recruiting Tools For HR in 2025" }, "description": { "type": "string", "description": "A snippet or summary of the source content", "example": "Discover the top AI recruiting tools that can help HR professionals streamline their hiring process..." }, "footnote": { "type": "boolean", "description": "Whether this source appears as a footnote (in a subsequent list in the sources modal)", "example": false }, "datePublished": { "type": "string", "description": "The publication date of the source. Omitted from the response when the source has no publish date — never emitted as `null`.", "example": "May 22, 2025" } } }, "example": [ { "position": 1, "url": "https://www.rippling.com/blog/ai-recruiting?utm_source=chatgpt.com", "label": "12 Best AI Recruiting Tools For HR in 2025", "description": "Discover the top AI recruiting tools that can help HR professionals streamline their hiring process...", "footnote": false, "datePublished": "May 22, 2025" }, { "position": 2, "url": "https://www.index.dev/blog/ai-recruiting-software-hiring-managers?utm_source=chatgpt.com", "label": "7 Best AI Recruiting Software for Hiring Managers in 2025", "description": "A comprehensive guide to the best AI recruiting software options available for hiring managers...", "footnote": false, "datePublished": "April 10, 2025" }, { "position": 3, "url": "https://www.selectsoftwarereviews.com/buyer-guide/ai-recruiting?utm_source=chatgpt.com", "label": "10+ Best AI Recruiting Software for 2025: Expert Reviews + Pricing", "description": "Expert reviews and pricing information for the best AI recruiting software solutions...", "footnote": true } ] }, "html": { "type": "string", "format": "uri", "description": "A URL to the full HTML of the response (included when include.html is true)", "example": "https://storage.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html" }, "markdown": { "type": "string", "description": "ChatGPT's response formatted in Markdown (included when include.markdown is true)", "example": "The name \"Acme Corporation\" is used in various contexts, both fictional and real. Here's an overview:\n\n🐾 Acme Corporation in Fiction\nThe Acme Corporation is a fictional company featured prominently in Warner Bros. cartoons, particularly the Road Runner/Wile E. Coyote series." }, "rawResponse": { "type": "array", "description": "Array of streaming events returned by ChatGPT (included when include.rawResponse is true)", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Event type identifier" }, "token": { "type": "string", "description": "Resume token used to continue the ChatGPT conversation" }, "conversation_id": { "type": "string", "description": "ChatGPT conversation identifier" }, "message": { "type": "object", "description": "Event payload describing the assistant message", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "model": { "type": "string" } } }, "delta": { "type": "object", "description": "Streaming delta payload from ChatGPT", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "text_delta": { "type": "string" } } } } } }, "reason": { "type": "string", "description": "Why ChatGPT stopped streaming" } } }, "example": [ { "type": "resume_conversation_token", "token": "eyJhbGciOiJFUzI1Ni...WaVoqQ", "conversation_id": "68efc64b-2d74-8012-b87d-28e59f3b8a49" }, { "type": "message_start", "message": { "id": "msg_01JD6Q7H1ZKWM9GD34V5ZW1TYM", "role": "assistant", "model": "gpt-5" } }, { "type": "message_delta", "delta": { "content": [ { "type": "output_text_delta", "text_delta": "The name \"Acme Corporation\" is used in various contexts..." } ] } }, { "type": "message_stop", "reason": "end_turn" } ] }, "searchQueries": { "type": "array", "description": "Array of query fan-out ChatGPT used to generate the response (included when include.searchQueries is true)", "items": { "type": "string" }, "example": [ "What is Acme Corporation?", "Acme Corp company overview", "Acme Corporation products and services" ] }, "model": { "type": "string", "description": "The ChatGPT model used to generate the response", "example": "gpt-5" }, "shoppingCards": { "type": "array", "description": "Array of shopping/product cards extracted from the response. The field is omitted entirely from `result` when `include.shopping` is `false` or unset — clients should treat it as optional rather than expecting an empty array.", "items": { "type": "object", "properties": { "tags": { "type": "array", "description": "Category tags for the shopping card", "items": { "type": "string" }, "example": [ "stylish casual leather sneaker", "heritage retro leather sneaker" ] }, "products": { "type": "array", "description": "Array of product information", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Product name", "example": "Adidas VL Court 3.0" }, "position": { "type": "integer", "description": "1-indexed rank across all products in all shopping cards in the response (flat, not reset per card).", "example": 1 }, "url": { "type": "string", "description": "Product page URL with ChatGPT attribution", "example": "https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html?utm_source=chatgpt.com" }, "price": { "type": "string", "description": "Current price", "example": "$57.00" }, "featured_tag": { "type": "string", "description": "Product category or style tag", "example": "stylish casual leather sneaker" }, "merchant": { "type": "string", "description": "Merchant information", "example": "adidas + others" }, "image_urls": { "type": "array", "description": "Array of product image URLs", "items": { "type": "string" }, "example": [ "https://images.openai.com/static-rsc-1/example.jpg" ] }, "rating": { "type": "number", "description": "Product rating (0-5 scale)", "example": 4.7 }, "num_reviews": { "type": "integer", "description": "Number of reviews", "example": 10394 }, "id": { "type": "string", "description": "Unique product identifier", "example": "3250714974047560249" }, "offers": { "type": "array", "description": "Array of shopping offers from different merchants", "items": { "type": "object", "properties": { "merchant_name": { "type": "string", "description": "Merchant name", "example": "adidas" }, "product_name": { "type": "string", "description": "Product name as listed by merchant", "example": "Adidas Women's VL Court 3.0" }, "url": { "type": "string", "description": "Offer URL with ChatGPT attribution", "example": "https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html?utm_source=chatgpt.com" }, "price": { "type": "string", "description": "Offer price", "example": "$57.00" }, "details": { "type": "string", "description": "Stock and delivery information", "example": "In stock online and nearby, Delivery between Sat - Mon $4.99" }, "available": { "type": "boolean", "description": "Offer availability status", "example": true }, "checkoutable": { "type": "boolean", "description": "Whether offer can be checked out directly", "example": false }, "price_details": { "type": "object", "description": "Detailed price breakdown", "properties": { "base": { "type": "string", "description": "Base product price", "example": "$57.00" }, "total": { "type": "string", "description": "Total price including any additional costs", "example": "$57.00" } } }, "tag": { "type": "object", "description": "Promotional tag", "properties": { "text": { "type": "string", "description": "Tag text", "example": "Best price" } } } } } }, "rating_grouped_citation": { "type": "object", "description": "Rating source information", "properties": { "title": { "type": "string", "description": "Source title", "example": "Adidas Women's VL Court 3.0" }, "url": { "type": "string", "description": "Source URL", "example": "https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html" }, "supporting_websites": { "type": "array", "description": "Array of supporting website references", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Website title", "example": "Adidas Women's VL Court 3.0" }, "url": { "type": "string", "description": "Website URL", "example": "https://www.macys.com/shop/product/adidas-womens-vl-court-3.0-casual-sneakers-from-finish-line?ID=21107988&pla_country=US&CAGPSPN=pla" } } } } } } } } } } }, "example": [ { "tags": [ "stylish casual leather sneaker", "heritage retro leather sneaker" ], "products": [ { "title": "Adidas VL Court 3.0", "url": "https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html?utm_source=chatgpt.com", "price": "$57.00", "featured_tag": "stylish casual leather sneaker", "merchant": "adidas + others", "image_urls": [ "https://images.openai.com/static-rsc-1/example.jpg" ], "rating": 4.7, "num_reviews": 10394, "id": "3250714974047560249", "offers": [ { "merchant_name": "adidas", "product_name": "Adidas Women's VL Court 3.0", "url": "https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html?utm_source=chatgpt.com", "price": "$57.00", "details": "In stock online and nearby, Delivery between Sat - Mon $4.99", "available": true, "checkoutable": false, "price_details": { "base": "$57.00", "total": "$57.00" }, "tag": { "text": "Best price" } } ], "rating_grouped_citation": { "title": "Adidas Women's VL Court 3.0", "url": "https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html", "supporting_websites": [ { "title": "Adidas Women's VL Court 3.0", "url": "https://www.macys.com/shop/product/adidas-womens-vl-court-3.0-casual-sneakers-from-finish-line?ID=21107988&pla_country=US&CAGPSPN=pla" } ] } } ] } ] }, "inlineProducts": { "type": "array", "description": "Array of inline products with pricing and offers. The field is omitted entirely from `result` when `include.shopping` is `false` or unset — clients should treat it as optional rather than expecting an empty array.", "items": { "$ref": "#/components/schemas/InlineProduct" } }, "entities": { "type": "array", "description": "Array of entities extracted from the response (when available)", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Entity type identifier", "example": "product" }, "name": { "type": "string", "description": "Entity name", "example": "adidas Grand Court Lo" } }, "required": [ "type", "name" ] }, "example": [ { "type": "product", "name": "adidas Grand Court Lo" }, { "type": "product", "name": "Reebok Club C 85 Vintage" }, { "type": "product", "name": "Nike Dunk Low Retro SE" } ] }, "map": { "type": "array", "description": "Array of business/place map entries extracted from the response (when available). Items come from ChatGPT's enriched providers (Yelp, Google Business) and use camelCase field names. The full field set is documented at /api-reference/endpoint/chatgpt/map; only the most commonly populated fields are listed here.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Business ID (Yelp ID or Google Place ID)", "example": "rVKID2OBQMyVpraqSjz9sg" }, "provider": { "type": "string", "description": "Data provider: \"yelp\", \"b1\"/\"b3\" (Google), or \"yelp-feed\"", "example": "yelp" }, "name": { "type": "string", "description": "Business name", "example": "Blue Bottle Coffee" }, "position": { "type": "integer", "description": "Position/ranking in results (added by parser)", "example": 1 }, "address": { "type": "string", "description": "Full street address", "example": "66 Mint St, San Francisco, CA 94103" }, "latitude": { "type": "number", "description": "GPS latitude coordinate", "example": 37.7811 }, "longitude": { "type": "number", "description": "GPS longitude coordinate", "example": -122.4076 }, "categories": { "type": "array", "description": "Business categories", "items": { "type": "string" }, "example": [ "Coffee shop" ] }, "rating": { "type": "number", "description": "Business rating (0-5 scale)", "example": 4.5 }, "reviewCount": { "type": "integer", "description": "Number of reviews", "example": 1234 }, "description": { "type": "string", "description": "Business description", "example": "Specialty coffee roaster known for their meticulous pour-over preparations" }, "phone": { "type": "string", "description": "Contact phone number", "example": "+1-415-555-0123" }, "websiteUrl": { "type": "string", "format": "uri", "description": "Business website URL", "example": "https://bluebottlecoffee.com" } } }, "example": [ { "id": "rVKID2OBQMyVpraqSjz9sg", "provider": "yelp", "name": "Blue Bottle Coffee", "position": 1, "address": "66 Mint St, San Francisco, CA 94103", "latitude": 37.7811, "longitude": -122.4076, "categories": [ "Coffee shop" ], "rating": 4.5, "reviewCount": 1234, "description": "Specialty coffee roaster known for their meticulous pour-over preparations", "phone": "+1-415-555-0123", "websiteUrl": "https://bluebottlecoffee.com" } ] }, "citationPills": { "type": "array", "description": "Array of inline citation pills extracted from the response (when available). These are citations that appear inline within the text. Each entry is one (pill, source) pair; group by `citationPillId` to recover pill-level structure.", "items": { "type": "object", "required": [ "label", "citationPillId", "url", "domain", "type", "position" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The URL of the citation", "example": "https://example.com/article" }, "label": { "type": "string", "description": "Per-source title of the citation. Always present; may be an empty string when the citation event ships no title — read `domain` / `url` for source identity in that case.", "example": "Example Article Title" }, "description": { "type": "string", "description": "Description of the citation content. Omitted when the citation event carries no snippet (e.g. grouped-webpage title-only cards).", "example": "A detailed description of the cited content" }, "domain": { "type": "string", "description": "Domain of the citation source", "example": "example.com" }, "datePublished": { "type": "string", "description": "ISO 8601 date string of when the source was published. Omitted when the citation event carries no publication date.", "example": "2025-01-01" }, "citationPillId": { "type": "integer", "description": "0-based identifier shared by all entries from the same chip. Group by `citationPillId` to recover the pill-level structure. **Note:** unlike the other providers (Google AIO, AI Mode, Copilot, Perplexity, Gemini) which use 1-based `citationPillId`, ChatGPT's IDs start at 0 for historical reasons.", "example": 0 }, "type": { "type": "string", "enum": [ "searchResult", "groupedWebpage" ], "description": "Discriminator for the underlying citation event: `searchResult` for inline search citations, `groupedWebpage` for grouped-webpage cards.", "example": "searchResult" }, "position": { "type": "integer", "description": "1-based position of this source in the sibling `result.sources` array.", "example": 1 } } }, "example": [ { "url": "https://example.com/article", "label": "Example Article Title", "description": "A detailed description of the cited content", "domain": "example.com", "datePublished": "2025-01-01", "citationPillId": 0, "type": "searchResult", "position": 1 } ] }, "ads": { "type": "array", "description": "Array of ads displayed in ChatGPT response (included when include.ads is true)", "items": { "type": "object", "properties": { "brand": { "type": "object", "description": "Advertiser brand information", "properties": { "name": { "type": "string", "description": "Advertiser brand name", "example": "Acme Shoes" }, "url": { "type": "string", "format": "uri", "description": "Advertiser brand URL", "example": "https://www.acmeshoes.com?utm_source=chatgpt.com" }, "favicon": { "type": "string", "format": "uri", "description": "Advertiser brand favicon URL", "example": "https://images.openai.com/favicon.ico" } }, "required": [ "name", "url" ] }, "cards": { "type": "array", "description": "Array of carousel cards in the ad", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Card title", "example": "Premium Running Shoes" }, "body": { "type": "string", "description": "Card description text", "example": "Lightweight performance running shoes with advanced cushioning technology" }, "url": { "type": "string", "format": "uri", "description": "Card destination URL", "example": "https://www.acmeshoes.com/running?utm_source=chatgpt.com" }, "image": { "type": "string", "format": "uri", "description": "Card image URL", "example": "https://images.openai.com/product.jpg" } }, "required": [ "title", "body", "url" ] } } }, "required": [ "brand", "cards" ] }, "example": [ { "brand": { "name": "Acme Shoes", "url": "https://www.acmeshoes.com?utm_source=chatgpt.com", "favicon": "https://images.openai.com/favicon.ico" }, "cards": [ { "title": "Premium Running Shoes", "body": "Lightweight performance running shoes with advanced cushioning technology", "url": "https://www.acmeshoes.com/running?utm_source=chatgpt.com", "image": "https://images.openai.com/product.jpg" }, { "title": "Trail Running Shoes", "body": "Durable shoes designed for off-road running with superior grip", "url": "https://www.acmeshoes.com/trail?utm_source=chatgpt.com", "image": "https://images.openai.com/product2.jpg" } ] } ] } } } } }, "Error": { "required": [ "error" ], "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message", "timestamp" ], "properties": { "code": { "type": "string", "description": "Error code identifier", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Request validation failed" }, "details": { "type": "object", "description": "Additional context-specific information" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the error occurred", "example": "2025-01-15T12:00:00.000Z" } } } } }, "ValidationError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Request validation failed" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "example": "prompt" }, "message": { "type": "string", "example": "Prompt cannot be empty" } } } } } }, "AuthenticationError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "MISSING_API_KEY", "INVALID_API_KEY_FORMAT", "INVALID_OR_EXPIRED_API_KEY" ], "example": "MISSING_API_KEY" }, "message": { "type": "string", "example": "Missing or invalid API key" }, "timestamp": { "type": "string", "format": "date-time", "example": "2025-01-15T12:00:00.000Z" } } } } }, "ForbiddenError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_PERMISSIONS", "INSUFFICIENT_CREDITS" ], "example": "INSUFFICIENT_PERMISSIONS" }, "message": { "type": "string", "example": "Insufficient permissions" }, "details": { "type": "object", "properties": { "requiredScopes": { "type": "array", "items": { "type": "string" }, "example": [ "read:monitor", "write:monitor" ] } }, "required": [] }, "timestamp": { "type": "string", "format": "date-time", "example": "2025-01-15T12:00:00.000Z" } } } } }, "NotFoundError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "RESOURCE_NOT_FOUND" }, "message": { "type": "string", "example": "Route not found" }, "details": { "type": "object", "properties": { "id": { "type": "string", "example": "/v1/invalid-endpoint" } } }, "timestamp": { "type": "string", "format": "date-time", "example": "2025-01-15T12:00:00.000Z" } } } } }, "ConflictError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "RESOURCE_CONFLICT" }, "message": { "type": "string", "example": "Resource conflict" }, "timestamp": { "type": "string", "format": "date-time", "example": "2025-01-15T12:00:00.000Z" } } } } }, "ConcurrentLimitError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "CONCURRENT_LIMIT_EXCEEDED" }, "message": { "type": "string", "example": "Concurrent limit exceeded" }, "details": { "type": "object", "properties": { "limit": { "type": "number", "example": 10 } } }, "timestamp": { "type": "string", "format": "date-time", "example": "2025-01-15T12:00:00.000Z" } } } } }, "CanceledError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Request was canceled" } } }, "InternalError": { "type": "object", "oneOf": [ { "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Maximum retries exceeded" } } }, { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "INTERNAL_SERVER_ERROR" }, "message": { "type": "string", "example": "Internal server error" }, "timestamp": { "type": "string", "format": "date-time", "example": "2025-01-15T12:00:00.000Z" } } } } } ] }, "ExternalServiceError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "EXTERNAL_SERVICE_ERROR" }, "message": { "type": "string", "example": "External service error: OpenAI" }, "details": { "type": "object", "properties": { "service": { "type": "string", "example": "OpenAI" } } }, "timestamp": { "type": "string", "format": "date-time", "example": "2025-01-15T12:00:00.000Z" } } } } }, "GoogleMonitorRequest": { "required": [ "query", "country" ], "type": "object", "properties": { "query": { "description": "The search query to execute on Google", "type": "string", "minLength": 1, "maxLength": 10000, "example": "best laptops for programming" }, "country": { "description": "ISO 3166-1 alpha-2 country code for localized search results", "type": "string", "example": "US" }, "location": { "description": "Google canonical location name for geo-targeted results, in comma-separated format: 'City,Region,Country' (see https://developers.google.com/google-ads/api/reference/data/geotargets for all ~100,000 supported locations). Use alongside 'country' for city-level precision. Mutually exclusive with 'uule' — provide one or the other, not both.", "type": "string", "example": "New York,New York,United States" }, "uule": { "description": "Pre-encoded Google UULE string for precise geo-targeting. Use this when you have a pre-built UULE value instead of a location name. Mutually exclusive with 'location' — provide one or the other, not both.", "type": "string", "example": "w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5" }, "device": { "description": "Device type for search results", "type": "string", "enum": [ "desktop", "mobile" ], "default": "desktop", "example": "desktop" }, "pages": { "description": "Number of search results pages to scrape (1-10)", "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "example": 3 }, "include": { "description": "Optional flags for including additional response data", "type": "object", "properties": { "html": { "description": "Include raw HTML response from Google search", "type": "boolean", "default": false, "example": false }, "aioverview": { "description": "Include Google AI Overview in the response", "type": "object", "properties": { "markdown": { "description": "Include AI Overview formatted as markdown", "type": "boolean", "default": false, "example": true } }, "default": { "markdown": false }, "additionalProperties": false }, "paaAioverview": { "description": "Hydrate AI-Overview-type People Also Ask items with markdown content and sources. Costs one extra request per AI-Overview-type PAA item (typically 1-2 per page).", "type": "boolean", "default": false, "example": true } }, "default": { "html": false }, "additionalProperties": false } }, "additionalProperties": false }, "GoogleMonitorResponse": { "required": [ "success", "result" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "description": "Google search results data", "type": "object", "properties": { "organicResults": { "type": "array", "description": "Organic search results from Google", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "Position in search results (1-indexed)", "example": 1 }, "title": { "type": "string", "description": "Title of the search result", "example": "Best Laptops for Programming in 2024" }, "link": { "type": "string", "description": "URL of the search result", "example": "https://example.com/best-programming-laptops" }, "displayedLink": { "type": "string", "description": "Formatted URL as displayed in search results", "example": "https://example.com" }, "snippet": { "type": "string", "description": "Text snippet describing the page content", "example": "Looking for the best programming laptops? We've tested and reviewed the top options..." }, "date": { "type": "string", "description": "Publication date if available", "example": "2 days ago" }, "page": { "type": "number", "description": "Page number this result appeared on (1-indexed)", "example": 1 }, "sitelinks": { "type": "object", "description": "Sitelinks displayed under the main result", "properties": { "inline": { "type": "array", "description": "Inline sitelinks", "items": { "type": "object", "properties": { "title": { "type": "string", "example": "Specifications" }, "link": { "type": "string", "example": "https://example.com/specs" } } } } } } } } }, "peopleAlsoAsk": { "type": "array", "description": "People Also Ask questions from Google", "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question text", "example": "What specs should I look for in a programming laptop?" }, "type": { "type": "string", "enum": [ "AIOVERVIEW", "LINK", "UNKNOWN" ], "description": "Type of question result" }, "snippet": { "type": "string", "description": "Answer snippet (for LINK type)", "example": "Key specifications include RAM, processor, storage, and display quality..." }, "title": { "type": "string", "description": "Result title (for LINK type)", "example": "Essential laptop specs for developers" }, "link": { "type": "string", "description": "Result URL (for LINK type)", "example": "https://example.com/laptop-specs" }, "markdown": { "type": "string", "description": "AI Overview markdown content (for AIOVERVIEW type, when include.paaAioverview is true)" }, "sources": { "type": "array", "description": "Cited sources (for AIOVERVIEW type, when include.paaAioverview is true)", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Title of the source", "example": "Programming Laptop Guide" }, "url": { "type": "string", "description": "URL of the source", "example": "https://example.com/guide" }, "description": { "type": "string", "description": "Description of the source" }, "position": { "type": "number", "description": "Position of source (1-indexed)" } } } } } } }, "peopleAreSaying": { "type": "array", "description": "Cards from Google's \"What people are saying\" / \"Trending posts and discussions\" SERP module. The field is omitted from `result` when no such module appears on the SERP, so clients should treat it as optional rather than expecting an empty array.", "items": { "type": "object", "required": [ "position", "title", "link", "date" ], "properties": { "position": { "type": "number", "description": "Position within the module (1-indexed)", "example": 1 }, "title": { "type": "string", "description": "Card title as displayed on the SERP", "example": "Best running shoes 2026 - what runners are saying" }, "link": { "type": "string", "description": "Destination URL the card points to (often a Reddit, Quora, or community forum thread)", "example": "https://www.reddit.com/r/running/comments/example/" }, "date": { "type": "string", "description": "Google's raw relative-time text (e.g., \"5 days ago\", \"2 weeks ago\"). Free-form string — not normalized to a timestamp.", "example": "5 days ago" } } } }, "localResults": { "type": "array", "description": "Places from Google's local pack (the map-backed \"3-pack\" of local businesses on local-intent queries, e.g. \"best pizza in new york city\"). The field is omitted from `result` when no local pack appears on the SERP, so clients should treat it as optional rather than expecting an empty array. Desktop only; mobile and the separate hotels/travel pack are not surfaced.", "items": { "type": "object", "required": [ "position", "title" ], "properties": { "position": { "type": "number", "description": "Position within the pack (1-indexed)", "example": 1 }, "title": { "type": "string", "description": "Business name as displayed on the SERP", "example": "Joe's Pizza Broadway" }, "placeId": { "type": "string", "description": "Google entity id for the place", "example": "/g/11bw4ws2mt" }, "rating": { "type": "number", "description": "Average star rating (0–5)", "example": 4.4 }, "reviews": { "type": "string", "description": "Review count as displayed by Google (e.g. \"26K\"). Free-form string — not normalized to a number.", "example": "26K" }, "price": { "type": "string", "description": "Price band as displayed by Google (e.g. \"$10–20\"). Currency symbol matches the locale.", "example": "$10–20" }, "type": { "type": "string", "description": "Business category (e.g. \"Pizza\", \"Plumber\")", "example": "Pizza" }, "yearsInBusiness": { "type": "string", "description": "Years-in-business badge, when shown (typical on service-style packs)", "example": "80+ years in business" }, "address": { "type": "string", "description": "Street address or locality as displayed on the SERP", "example": "1435 Broadway" }, "phone": { "type": "string", "description": "Phone number, when shown (locale-formatted)", "example": "(212) 555-0100" }, "hours": { "type": "string", "description": "Opening-hours text as displayed (e.g. \"Open · Closes 11 PM\", \"Open 24 hours\")", "example": "Open · Closes 11 PM" }, "description": { "type": "string", "description": "Trailing snippet — a review quote or a service-options line", "example": "\"Fast service, great atmosphere, and truly scrumptious pizza.\"" }, "links": { "type": "object", "description": "Action links rendered on the place, typically on business/service-style packs (plumbers, salons, …) and absent on restaurant packs whose places are plain buttons. Each key is present only when Google rendered that button.", "properties": { "website": { "type": "string", "description": "The business's own website URL", "example": "https://villageplumbing.com/" }, "directions": { "type": "string", "description": "Absolute Google Maps directions URL", "example": "https://www.google.com/maps/dir//Village+Plumbing,+Air+%26+Electric" } } } } } }, "localResultsMoreLink": { "type": "string", "description": "Absolute URL of the local pack's \"More places\" / \"More businesses\" control — Google's expanded Local Finder for the query. Returned only alongside `localResults` when the SERP renders the control.", "example": "https://www.google.com/search?q=italian+restaurants+in+toronto&udm=1" }, "relatedSearches": { "type": "array", "description": "Related search suggestions", "items": { "type": "object", "properties": { "query": { "type": "string", "description": "Related search query", "example": "best budget laptop for coding" }, "link": { "type": "string", "description": "Google search URL for the related query", "example": "https://google.com/search?q=best+budget+laptop+for+coding" } } } }, "ads": { "type": "array", "description": "Sponsored ad results from Google search, including text ads (`type: RESULT`) and shopping-style sponsored cards (`type: SHOPPING_CARD`) from the right-hand-side and top-of-page carousels.", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "Position within the ad block (1-indexed)", "example": 1 }, "blockPosition": { "type": "string", "enum": [ "top", "bottom", "middle", "rhs" ], "description": "Where the ad appeared on the SERP. `top`/`bottom` are text-ad blocks, `middle` covers direct/in-content ads, `rhs` is the right-hand-side sponsored-products carousel.", "example": "top" }, "type": { "type": "string", "enum": [ "RESULT", "SHOPPING_CARD" ], "description": "Discriminates plain text ads (`RESULT`) from shopping-style sponsored cards (`SHOPPING_CARD`). Shopping cards appear in the right-hand-side PLA carousel, the top-of-page PLA carousel, and the top-of-page sponsored shopping-card carousels (vehicles, products, hotels, …).", "example": "RESULT" }, "title": { "type": "string", "description": "Ad title", "example": "Best Programming Laptops - Shop Now" }, "url": { "type": "string", "format": "uri", "description": "Destination URL of the ad. For `type: SHOPPING_CARD` items this is a Google `aclk?`-redirected URL.", "example": "https://example.com/programming-laptops" }, "page": { "type": "number", "description": "Page number where the ad was found", "example": 1 }, "displayedUrl": { "type": "string", "description": "Formatted URL as displayed in the ad", "example": "example.com/laptops" }, "domain": { "type": "string", "description": "Domain name of the advertiser", "example": "example.com" }, "description": { "type": "string", "description": "Ad description text. For `type: RESULT` items this is classic ad copy. For `type: SHOPPING_CARD` items it carries category-specific subtitle fragments joined with `·` (e.g. vehicle condition + city: `Used - 94k miles · Greeley`).", "example": "Shop our selection of programming laptops with fast shipping." }, "category": { "type": "string", "description": "Carousel header label for shopping-card ads. Examples observed today include `Sponsored products`, `Sponsored vehicles`, and `Sponsored hotels`. Omitted for `type: RESULT` text ads.", "example": "Sponsored products" }, "price": { "type": "object", "description": "Product price for `type: SHOPPING_CARD` ads. `value` and `currency` are populated only when the visible price string parses unambiguously into a number + symbol. `raw` carries the visible text verbatim (e.g. `\"$0 down with 24 monthly payments\"` on installment offers) so consumers can disambiguate genuine zero prices from down-payment labels.", "properties": { "value": { "type": "number", "nullable": true, "description": "Numeric price value", "example": 1199 }, "currency": { "type": "string", "nullable": true, "description": "Currency symbol", "example": "$" }, "raw": { "type": "string", "nullable": true, "description": "Visible price text verbatim", "example": "$1,199" } } }, "oldPrice": { "type": "object", "description": "Original price before discount on `type: SHOPPING_CARD` ads that surface MSRP / sale messaging. Same shape as `price`.", "properties": { "value": { "type": "number", "nullable": true, "description": "Numeric price value", "example": 1299 }, "currency": { "type": "string", "nullable": true, "description": "Currency symbol", "example": "$" }, "raw": { "type": "string", "nullable": true, "description": "Visible price text verbatim", "example": "$1,299" } } }, "store": { "type": "string", "description": "Merchant/dealer name attached to a `type: SHOPPING_CARD` ad.", "example": "Apple" }, "imageUrl": { "type": "string", "format": "uri", "description": "Hero image URL served by Google's `encrypted-tbn` CDN for `type: SHOPPING_CARD` ads. Omitted when the lazy-image chain cannot resolve a non-placeholder source.", "example": "https://encrypted-tbn0.gstatic.com/images?q=tbn:..." }, "sitelinks": { "type": "array", "description": "Sitelinks displayed under the ad", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Sitelink URL", "example": "https://example.com/gaming-laptops" }, "title": { "type": "string", "description": "Sitelink title", "example": "Gaming Laptops" }, "description": { "type": "string", "description": "Sitelink description", "example": "High-performance laptops for gaming" } } } } } } }, "aioverview": { "oneOf": [ { "type": "object" }, { "type": "null" } ], "description": "Google AI Overview data (if requested). Returns null when AI Overview is not available after retries.", "properties": { "sources": { "type": "array", "description": "Sources referenced in the AI Overview", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "1-based position index of the source", "example": 1 }, "url": { "type": "string", "description": "Source URL", "example": "https://example.com/programming-laptops" }, "label": { "type": "string", "description": "Source title (the display label Google renders on the source rail)", "example": "Best Programming Laptops 2026" }, "description": { "type": "string", "description": "Source description / snippet", "example": "Comprehensive guide to choosing the perfect laptop for software development" } } } }, "citationPills": { "type": "array", "description": "Inline citation pills extracted from the AI Overview answer. Each entry is one (pill, source) pair: when a pill cites N sources (Google's `[Label +N]` chips), the array contains N entries sharing the same `citationPillId` but carrying per-source `label`, `url`, and `domain`. Group by `citationPillId` to recover the pill-level structure. Omitted from `result.aioverview` when the answer carries no pills.", "items": { "type": "object", "required": [ "label", "citationPillId", "url", "domain", "position" ], "properties": { "label": { "type": "string", "description": "Per-source title from the sources rail (for example `\"Chase Personal Credit Cards\"`). Empty string when the rail has no title for this source — consumers should read `domain` / `url` for source identity in that case. Entries grouped under the same `citationPillId` carry different per-source labels.", "example": "Chase Personal Credit Cards" }, "citationPillId": { "type": "integer", "description": "1-based ordinal shared by all entries from the same chip. Group by `citationPillId` to reconstruct the visible chip; the per-source `label` differs across entries within a chip.", "example": 1 }, "url": { "type": "string", "description": "Direct URL of the cited source.", "example": "https://www.chase.com/personal/credit-cards" }, "domain": { "type": "string", "description": "Host extracted from `url`, for grouping and display.", "example": "chase.com" }, "description": { "type": "string", "description": "Source description from the sources rail when Google ships one. Omitted when the source carries no snippet.", "example": "Personal credit cards from Chase." }, "position": { "type": "integer", "description": "1-based position of this source in the sibling `result.aioverview.sources` array.", "example": 2 } } }, "example": [ { "label": "Chase Personal Credit Cards", "citationPillId": 1, "url": "https://www.chase.com/personal/credit-cards", "domain": "chase.com", "description": "Personal credit cards from Chase.", "position": 2 }, { "label": "JustAnswer Computer Help", "citationPillId": 1, "url": "https://www.justanswer.com/computer/help", "domain": "justanswer.com", "position": 4 } ] }, "relatedLinks": { "type": "array", "description": "A citation chip's \"View related links\" flyout items — URLs Google groups under the chip that are NOT in the `sources` rail (for example a Google Shopping comparison link). Each entry shares the `citationPillId` of its chip so it can be grouped with that chip's `citationPills`, but carries no `position` (a related link is absent from `sources`). Related links also render inline in `markdown`, so `markdown` may contain more URLs than `sources` / `citationPills` — the extras are accounted for here. Omitted from `result.aioverview` when no chip carries related links.", "items": { "type": "object", "required": [ "label", "citationPillId", "url", "domain" ], "properties": { "label": { "type": "string", "description": "The related page's own title. Empty string when Google ships none — read `domain` / `url` for identity in that case.", "example": "Compare developer laptops" }, "citationPillId": { "type": "integer", "description": "Matches the `citationPillId` of the chip's `citationPills` entries, so a related link can be grouped with its pill.", "example": 1 }, "url": { "type": "string", "description": "Direct URL of the related link.", "example": "https://www.google.com/search?q=developer+laptops&ibp=oshop" }, "domain": { "type": "string", "description": "Host extracted from `url`, for grouping and display.", "example": "google.com" }, "description": { "type": "string", "description": "Snippet Google ships for the related link. Omitted when absent.", "example": "Shop and compare laptops for developers." } } }, "example": [ { "label": "Compare developer laptops", "citationPillId": 1, "url": "https://www.google.com/search?q=developer+laptops&ibp=oshop", "domain": "google.com" } ] }, "text": { "type": "string", "description": "AI Overview text content", "example": "Based on current information, the best laptops for programming typically include models from Apple MacBook Pro, Dell XPS, and Lenovo ThinkPad series..." }, "markdown": { "type": "string", "description": "AI Overview content formatted as markdown (if requested)", "example": "Based on current information, the best laptops for programming typically include models from Apple MacBook Pro, Dell XPS, and Lenovo ThinkPad series..." }, "videos": { "type": "array", "description": "Video content included in the AI Overview", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Direct URL to the video", "example": "https://www.youtube.com/watch?v=example" }, "title": { "type": "string", "description": "Video title", "example": "Best Laptops for Programming 2024" }, "thumbnail": { "type": "string", "format": "uri", "description": "Thumbnail image URL", "example": "https://example.com/thumbnail.jpg" }, "source": { "type": "string", "description": "Channel or source name", "example": "Tech Channel" }, "platform": { "type": "string", "description": "Video platform", "example": "YouTube" }, "date": { "type": "string", "description": "Upload date", "example": "2 days ago" }, "duration": { "type": "string", "description": "Video duration", "example": "12:34" } } } }, "ads": { "type": "array", "description": "Sponsored ads injected by Google inside the AI Overview", "items": { "type": "object", "required": [ "position", "title", "url", "type" ], "properties": { "position": { "type": "number", "description": "Position of the ad (1-indexed)", "example": 1 }, "title": { "type": "string", "description": "Ad title", "example": "QA Software Testing Services - On-Demand Software Testing" }, "url": { "type": "string", "description": "Ad destination URL", "example": "https://www.testlio.com" }, "type": { "type": "string", "enum": [ "TEXT", "SHOPPING" ], "description": "Sub-type discriminator. TEXT ads carry `domain` + `description`; SHOPPING ads carry `price` + `store` (+ optional `old_price`). Always present.", "example": "TEXT" }, "domain": { "type": "string", "description": "Domain name of the advertiser (present when `type` is `TEXT`)", "example": "Testlio" }, "description": { "type": "string", "description": "Ad description text (present when `type` is `TEXT`)", "example": "Dynamic staffing. Global coverage. Managed manual testing and test automation solutions." }, "price": { "type": "object", "description": "Product price (present when `type` is `SHOPPING`). `value` and `currency` are populated only when the visible price string parses unambiguously into a number + symbol; `raw` carries the visible text verbatim.", "properties": { "value": { "type": "number", "nullable": true, "description": "Numeric price value", "example": 69.99 }, "currency": { "type": "string", "nullable": true, "description": "Currency symbol", "example": "$" }, "raw": { "type": "string", "nullable": true, "description": "Visible price text verbatim", "example": "$69.99" } } }, "old_price": { "type": "object", "description": "Original price before discount (present when `type` is `SHOPPING` and the ad has sale pricing). Same shape as `price`.", "properties": { "value": { "type": "number", "nullable": true, "description": "Numeric price value", "example": 99.99 }, "currency": { "type": "string", "nullable": true, "description": "Currency symbol", "example": "$" }, "raw": { "type": "string", "nullable": true, "description": "Visible price text verbatim", "example": "$99.99" } } }, "store": { "type": "string", "description": "Retailer name (present when `type` is `SHOPPING`)", "example": "Best Buy" }, "image": { "type": "string", "description": "Ad image URL (product photo for shopping ads, hero image for text ads)", "example": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQ..." } } } } } }, "shoppingCards": { "type": "array", "description": "Shopping product cards extracted from the SERP's organic shopping grids (\"Popular products\" / \"More products\"). The field is omitted from `result` when no shopping section is present, so clients should treat it as optional rather than expecting an empty array. Wire shape borrows fields from AI Mode's `shopping_cards` for cross-API familiarity but uses camelCase keys (`productLink`, `oldPrice`) emitted by the Google mapper.", "items": { "type": "object", "required": [ "title", "productLink" ], "properties": { "title": { "type": "string", "description": "Product title", "example": "ASICS Women's Gel-Nimbus 28" }, "position": { "type": "integer", "description": "1-indexed rank across the whole `shoppingCards` array in DOM order (flat, does not reset per `category` section).", "example": 1 }, "productLink": { "type": "string", "description": "Direct product URL. Click destinations are JS-hydrated, so this is usually an empty string in the static HTML response — the card opens a Google-side sidebar overlay rather than navigating externally.", "example": "" }, "category": { "type": "string", "description": "Parent section header text. Lets callers distinguish cards from coexisting shopping panels on the same SERP. Current Google-emitted values include \"Popular products\" and \"More products\".", "example": "More products" }, "price": { "type": "object", "description": "Structured pricing information. `value` and `currency` are populated only when the visible price string parses unambiguously into a number + symbol; `raw` carries the visible text verbatim.", "properties": { "value": { "type": "number", "nullable": true, "description": "Numeric price", "example": 169.99 }, "currency": { "type": "string", "nullable": true, "description": "Currency symbol", "example": "$" }, "raw": { "type": "string", "nullable": true, "description": "Visible price text verbatim", "example": "$169.99" } } }, "oldPrice": { "type": "object", "description": "Original price before discount. Same shape as `price`.", "properties": { "value": { "type": "number", "nullable": true, "description": "Numeric price", "example": 199.99 }, "currency": { "type": "string", "nullable": true, "description": "Currency symbol", "example": "$" }, "raw": { "type": "string", "nullable": true, "description": "Visible price text verbatim", "example": "$199.99" } } }, "store": { "type": "string", "description": "Merchant/store name", "example": "DICK'S Sporting Goods" }, "rating": { "type": "number", "description": "Product rating", "example": 4.5 }, "reviews": { "type": "string", "description": "Review count", "example": "384" }, "thumbnail": { "type": "string", "format": "uri", "description": "Product image URL", "example": "https://example.com/product.jpg" } } } }, "knowledgeGraph": { "description": "Google's Knowledge Graph panel for the queried entity. Omitted from `result` when no Knowledge Graph panel appears on the SERP — treat it as optional rather than expecting null.", "type": "object", "properties": { "title": { "type": "string", "description": "Entity name as shown in the panel header", "example": "Eminem" }, "type": { "type": "string", "description": "Entity category label as rendered by Google (e.g. \"American rapper\", \"French museum\"). Free-form string, not an enum.", "example": "American rapper" }, "kgmid": { "type": "string", "description": "Google Knowledge Graph ID for the entity", "example": "/m/01vs_v8" }, "description": { "type": "string", "description": "Short description of the entity (may be sourced from Wikipedia or Google's own knowledge base)", "example": "Marshall Bruce Mathers III, known professionally as Eminem, is an American rapper, songwriter, and record producer." }, "imageUrl": { "type": "string", "description": "URL of the entity's image as served by Google", "example": "https://encrypted-tbn0.gstatic.com/images?q=tbn:..." }, "website": { "type": "string", "description": "Official website URL for the entity", "example": "https://www.eminem.com" }, "menu": { "type": "string", "description": "Menu URL — present for restaurants and food businesses", "example": "https://www.restaurant.com/menu" }, "trailer": { "type": "string", "description": "Trailer URL — present for films and TV shows", "example": "https://www.youtube.com/watch?v=example" }, "source": { "type": "object", "description": "Attribution source for the entity description (typically Wikipedia)", "properties": { "name": { "type": "string", "description": "Display name of the source", "example": "Wikipedia" }, "link": { "type": "string", "description": "URL of the source page", "example": "https://en.wikipedia.org/wiki/Eminem" } } }, "attributes": { "type": "array", "description": "Factual key-value pairs extracted from the panel (e.g. born, genre, label). Keys are free-form strings as rendered by Google.", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Attribute label", "example": "Born" }, "value": { "type": "string", "description": "Attribute value", "example": "October 17, 1972" } } } }, "profiles": { "type": "array", "description": "Social media and external profile links for the entity", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Platform or profile name", "example": "Instagram" }, "link": { "type": "string", "description": "Profile URL", "example": "https://www.instagram.com/eminem/" } } } }, "peopleAlsoSearchFor": { "type": "array", "description": "Related entities that users also search for", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Related entity name", "example": "Jay-Z" }, "link": { "type": "string", "description": "Google search URL for this related entity", "example": "https://www.google.com/search?q=Jay-Z" } } } }, "thingsToKnow": { "type": "array", "description": "\"Things to know\" topic clusters extracted from the panel", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Topic cluster label", "example": "Albums" }, "subtitle": { "type": "string", "description": "Subtitle or supporting text for the topic", "example": "The Slim Shady LP, The Marshall Mathers LP, ..." } } } }, "ratings": { "type": "array", "description": "Review platform ratings (e.g. Rotten Tomatoes, IMDb) — present for films and TV shows", "items": { "type": "object", "properties": { "platform": { "type": "string", "description": "Review platform name", "example": "Rotten Tomatoes" }, "rating": { "type": "string", "description": "Rating value as displayed", "example": "88%" }, "link": { "type": "string", "description": "URL to the review page", "example": "https://www.rottentomatoes.com/m/8_mile" } } } }, "streamingOptions": { "type": "array", "description": "Streaming platform links for films and TV shows", "items": { "type": "object", "properties": { "platform": { "type": "string", "description": "Streaming platform name", "example": "Netflix" }, "link": { "type": "string", "description": "Link to the content on the platform", "example": "https://www.netflix.com/title/example" } } } }, "webRatings": { "type": "array", "description": "Web ratings from review platforms — present for local businesses (e.g. Google, Tripadvisor, Yelp)", "items": { "type": "object", "properties": { "platform": { "type": "string", "description": "Rating platform name", "example": "Google" }, "rating": { "type": "string", "description": "Rating value as displayed", "example": "4.5" }, "link": { "type": "string", "description": "URL to the platform's review page", "example": "https://www.google.com/maps/place/..." }, "votes": { "type": "string", "description": "Number of votes or reviews (omitted when not available)", "example": "1,234" } } } }, "statsCard": { "type": "object", "description": "Statistics card — present for sports teams, organizations, and similar entities", "properties": { "context": { "type": "string", "description": "Context label for the stats (e.g. season or year)", "example": "2023-24 NBA season" }, "stats": { "type": "array", "description": "Individual stat items", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Stat label", "example": "Points per game" }, "value": { "type": "string", "description": "Stat value", "example": "27.1" } } } } } }, "socialPosts": { "type": "array", "description": "Recent social media posts from the entity's official accounts", "items": { "type": "object", "properties": { "platform": { "type": "string", "description": "Social platform name", "example": "X" }, "text": { "type": "string", "description": "Post text content", "example": "New album dropping Friday 🔥" }, "link": { "type": "string", "description": "URL to the post", "example": "https://x.com/eminem/status/..." }, "date": { "type": "string", "description": "Post date as displayed by Google", "example": "2 days ago" } } } }, "notableAlumni": { "type": "array", "description": "Notable alumni — present for universities and educational institutions", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Alumni name", "example": "Barack Obama" }, "link": { "type": "string", "description": "Google search URL for this person", "example": "https://www.google.com/search?q=Barack+Obama" } } } }, "contact": { "type": "array", "description": "Contact and ordering links — present for local businesses", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Link label", "example": "Order online" }, "url": { "type": "string", "description": "Link URL", "example": "https://www.restaurant.com/order" } } } }, "weather": { "type": "object", "description": "Current weather — present for geographic entities (cities, regions)", "properties": { "temperature": { "type": "string", "description": "Temperature as displayed", "example": "72°F" }, "condition": { "type": "string", "description": "Weather condition", "example": "Sunny" } } }, "rating": { "type": "object", "description": "Aggregate star rating — present for local businesses", "properties": { "rating": { "type": "string", "description": "Star rating value", "example": "4.5" }, "count": { "type": "string", "description": "Number of reviews", "example": "2,847" } } }, "admission": { "type": "array", "description": "Admission options — present for museums, parks, and ticketed venues", "items": { "type": "object", "properties": { "provider": { "type": "string", "description": "Ticket provider name", "example": "Official website" }, "price": { "type": "string", "description": "Admission price as displayed", "example": "$17" }, "link": { "type": "string", "description": "URL to purchase tickets", "example": "https://www.louvre.fr/en/tickets" }, "badge": { "type": "string", "description": "Optional badge text (e.g. \"Free\", \"Best price\") — omitted when not present", "example": "Best price" } } } }, "artworks": { "type": "array", "description": "Notable artworks — present for artists and art institutions", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Artwork title", "example": "Mona Lisa" }, "link": { "type": "string", "description": "Link to more information about the artwork", "example": "https://www.google.com/search?q=Mona+Lisa" }, "author": { "type": "string", "description": "Author or creator name — omitted when not present", "example": "Leonardo da Vinci" } } } }, "has3dModel": { "type": "boolean", "description": "True when Google surfaces a 3D model viewer for the entity", "example": true }, "hotelOptions": { "type": "array", "description": "Hotel booking options — present for hotel entities", "items": { "type": "object", "properties": { "provider": { "type": "string", "description": "Booking provider name", "example": "Booking.com" }, "price": { "type": "string", "description": "Price as displayed", "example": "$189/night" }, "link": { "type": "string", "description": "URL to book on this provider", "example": "https://www.booking.com/hotel/..." }, "note": { "type": "string", "description": "Optional note (e.g. \"Includes breakfast\") — omitted when not present", "example": "Includes breakfast" } } } }, "trendingProducts": { "type": "array", "description": "Trending products — present for retail brands", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Product title", "example": "Air Max 90" }, "price": { "type": "string", "description": "Price as displayed", "example": "$120" }, "link": { "type": "string", "description": "Link to the product", "example": "https://www.nike.com/t/air-max-90" } } } }, "merchantVideos": { "type": "array", "description": "Merchant or brand video content — present for retail businesses", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Video title", "example": "Foot Locker Week of Greatness" }, "link": { "type": "string", "description": "Video URL", "example": "https://www.youtube.com/watch?v=..." }, "platform": { "type": "string", "description": "Video platform — omitted when not available", "example": "YouTube" }, "duration": { "type": "string", "description": "Video duration as displayed — omitted when not available", "example": "2:34" } } } }, "listenOn": { "type": "array", "description": "Music streaming platform links — present for musicians and musical acts", "items": { "type": "object", "properties": { "platform": { "type": "string", "description": "Streaming platform name", "example": "Spotify" }, "link": { "type": "string", "description": "Link to the artist on the platform", "example": "https://open.spotify.com/artist/..." } } } } } }, "html": { "type": "array", "description": "Raw HTML from Google search page (if requested)", "items": { "type": "string", "format": "uri" }, "example": [ "https://storage.cloro.dev/results/b83e8dfd-c3a1-4b98-83b9-af91adc21e26/page-1.html" ] } } } } }, "GoogleNewsMonitorRequest": { "required": [ "query", "country" ], "type": "object", "properties": { "query": { "description": "The search query to execute on Google News", "type": "string", "minLength": 1, "maxLength": 10000, "example": "climate change" }, "country": { "description": "ISO 3166-1 alpha-2 country code for localized news results", "type": "string", "example": "US" }, "device": { "description": "Device type for news results", "type": "string", "enum": [ "desktop", "mobile" ], "default": "desktop", "example": "desktop" }, "pages": { "description": "Number of news results pages to scrape (1-10)", "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "example": 1 }, "include": { "description": "Optional flags for including additional response data", "type": "object", "properties": { "html": { "description": "Include raw HTML response from Google News", "type": "boolean", "default": false, "example": false } }, "default": { "html": false }, "additionalProperties": false } }, "additionalProperties": false }, "GoogleNewsMonitorResponse": { "required": [ "success", "result" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "description": "Google News results data", "type": "object", "properties": { "newsResults": { "type": "array", "description": "News articles from Google News", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "Position in news results (1-indexed)", "example": 1 }, "title": { "type": "string", "description": "Title of the news article", "example": "Major Climate Summit Reaches Historic Agreement" }, "link": { "type": "string", "description": "URL of the news article", "example": "https://example.com/climate-summit-agreement" }, "snippet": { "type": "string", "description": "Text snippet describing the article", "example": "World leaders agreed on new climate targets at the summit..." }, "source": { "type": "string", "description": "News source/publisher name", "example": "The Guardian" }, "date": { "type": "string", "description": "Publication date", "example": "2 hours ago" }, "page": { "type": "number", "description": "Page number this result appeared on (1-indexed)", "example": 1 }, "thumbnail": { "type": "string", "description": "Thumbnail image URL (if available)", "example": "https://example.com/images/climate-summit.jpg" } } } }, "html": { "type": "array", "description": "Raw HTML from Google News pages (if requested)", "items": { "type": "string", "format": "uri" }, "example": [ "https://storage.cloro.dev/results/a12b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6/page-1.html" ] } } } } }, "CopilotMonitorRequest": { "required": [ "prompt", "country" ], "type": "object", "properties": { "prompt": { "description": "The prompt to send to Copilot", "type": "string", "minLength": 1, "maxLength": 10000, "example": "What are the best laptops for programming?" }, "country": { "description": "Country/region code for localized response", "type": "string", "example": "US" }, "include": { "description": "Optional flags for including additional response formats", "type": "object", "properties": { "html": { "description": "Include a URL to the full HTML of the response", "type": "boolean", "default": false, "example": true }, "markdown": { "description": "Include markdown-formatted response in the result", "type": "boolean", "default": false, "example": true }, "rawResponse": { "description": "Include raw streaming response events", "type": "boolean", "default": false, "example": true } }, "default": { "html": false, "markdown": false, "rawResponse": false }, "additionalProperties": false }, "state": { "$ref": "#/components/schemas/StateParameter" } }, "additionalProperties": false }, "CopilotMonitorResponse": { "required": [ "success", "result" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "description": "Copilot response data", "type": "object", "properties": { "text": { "type": "string", "description": "Copilot's response text", "example": "As an AI assistant, I can help you find great laptops for programming..." }, "html": { "type": "string", "format": "uri", "description": "A URL to the full HTML of the response.", "example": "https://storage.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html" }, "sources": { "type": "array", "description": "Array of sources referenced in the response", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "The position index of the source in the response", "example": 1 }, "url": { "type": "string", "description": "The URL of the source", "example": "https://example.com/article" }, "label": { "type": "string", "description": "The display label for the source", "example": "Microsoft Docs" }, "description": { "type": "string", "description": "A description of the source content", "example": "Development hardware recommendations" } } }, "example": [ { "position": 1, "url": "https://docs.microsoft.com/", "label": "Microsoft Docs", "description": "Official development documentation" } ] }, "citationPills": { "type": "array", "description": "Inline citation pills extracted from the Copilot answer. Each entry is one (pill, source) pair: when a pill cites N sources (consecutive citation events grouped into a single chip), the array contains N entries sharing the same `citationPillId` but carrying per-source `label`, `url`, and `domain`. Group by `citationPillId` to recover the pill-level structure. Omitted from `result` when the answer carries no pills.", "items": { "type": "object", "required": [ "label", "citationPillId", "url", "domain", "position" ], "properties": { "label": { "type": "string", "description": "Per-source title from the citation event (e.g. `\"Microsoft 365 Documentation\"`, `\"Productivity Best Practices\"`). Always present; may be an empty string when the event ships no title — read `domain` / `url` for source identity in that case. Entries grouped under the same `citationPillId` carry different per-source labels.", "example": "Microsoft 365 Documentation" }, "citationPillId": { "type": "integer", "description": "1-based ordinal shared by all entries from the same chip. Group by `citationPillId` to reconstruct the visible chip; the per-source `label` differs across entries within a chip.", "example": 1 }, "url": { "type": "string", "description": "Direct URL of the cited source.", "example": "https://docs.microsoft.com/" }, "domain": { "type": "string", "description": "Host extracted from `url`, for grouping and display.", "example": "docs.microsoft.com" }, "description": { "type": "string", "description": "Source description from the sources rail when Copilot ships one. Omitted when absent.", "example": "Official development documentation" }, "position": { "type": "integer", "description": "1-based position of this source in the sibling `result.sources` array.", "example": 1 } } }, "example": [ { "label": "Microsoft 365 Documentation", "citationPillId": 1, "url": "https://docs.microsoft.com/", "domain": "docs.microsoft.com", "description": "Official development documentation", "position": 1 }, { "label": "VS Code on GitHub", "citationPillId": 1, "url": "https://github.com/microsoft/vscode", "domain": "github.com", "description": "Visual Studio Code repository", "position": 2 } ] }, "shoppingCards": { "type": "array", "description": "Array of shopping/product cards extracted from the response (when available)", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Shopping card type", "example": "shoppingProducts" }, "layout": { "type": "string", "description": "Layout style for the shopping card", "example": "Carousel" }, "products": { "type": "array", "description": "Array of product information", "items": { "type": "object", "properties": { "product": { "type": "object", "description": "Product identifier information", "properties": { "id": { "type": "string", "description": "Unique product ID" }, "groupId": { "type": "string", "description": "Product group ID" }, "brandGroupId": { "type": "string", "description": "Brand group ID (optional)" } } }, "position": { "type": "integer", "description": "1-indexed rank across all products in all shopping cards in the response (flat, not reset per card).", "example": 1 }, "offerId": { "type": "string", "description": "Unique offer identifier" }, "url": { "type": "string", "description": "Product page URL" }, "name": { "type": "string", "description": "Product name" }, "description": { "type": "string", "description": "Product description" }, "images": { "type": "array", "description": "Product images with titles and URLs", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Image title" }, "url": { "type": "string", "description": "Image URL" } } } }, "specifications": { "type": "array", "description": "Product specifications (e.g., Color, Size)", "items": { "type": "object", "properties": { "displayName": { "type": "string", "description": "Specification name" }, "values": { "type": "array", "description": "Available values", "items": { "type": "string" } } } } }, "tags": { "type": "array", "description": "Product tags", "items": { "type": "string" } }, "price": { "type": "object", "description": "Product pricing information", "properties": { "amount": { "type": "number", "description": "Price amount" }, "currency": { "type": "string", "description": "Currency code (optional)" }, "currencySymbol": { "type": "string", "description": "Currency symbol" } } }, "seller": { "type": "string", "description": "Seller name" }, "sellerLogoUrl": { "type": "string", "description": "Seller logo URL" }, "brandName": { "type": "string", "description": "Product brand name" }, "rating": { "type": "object", "description": "Product rating information", "properties": { "value": { "type": "number", "description": "Rating value" }, "count": { "type": "integer", "description": "Number of ratings" } } }, "canTrackPrice": { "type": "boolean", "description": "Whether price tracking is available" } } } } } } }, "map": { "type": "array", "description": "Array of business/place map entries extracted from the response (when available)", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Business name", "example": "WonderWorks Pigeon Forge" }, "position": { "type": "integer", "description": "Position in results (1-indexed)", "example": 1 }, "placeId": { "type": "string", "description": "Google Place ID", "example": "ChIJEYpTsk__W4gR2sQLGzOjE3o" }, "location": { "type": "object", "description": "Business location", "properties": { "address": { "type": "string", "description": "Full street address", "example": "100 Music Rd, Pigeon Forge, TN 37863" }, "latitude": { "type": "number", "description": "GPS latitude", "example": 35.823257 }, "longitude": { "type": "number", "description": "GPS longitude", "example": -83.5787498 } } }, "phoneNumber": { "type": "string", "description": "Contact phone number", "example": "(865) 868-1800" }, "url": { "type": "string", "format": "uri", "description": "Business website URL", "example": "http://www.wonderworksonline.com/pigeon-forge/" }, "reviews": { "type": "array", "description": "Review aggregations from providers", "items": { "type": "object", "properties": { "count": { "type": "integer", "description": "Number of reviews", "example": 10625 }, "rating": { "type": "number", "description": "Average rating", "example": 4.3 }, "providerName": { "type": "string", "description": "Review provider name", "example": "Google" }, "providerIconUrl": { "type": "string", "description": "Provider icon URL" }, "url": { "type": "string", "format": "uri", "description": "Reviews page URL", "example": "https://maps.google.com/?cid=8796553937077126362" } } } }, "photos": { "type": "array", "description": "Business photos", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Photo URL" }, "altText": { "type": "string", "description": "Alt text for the photo" }, "providerName": { "type": "string", "description": "Photo provider name" }, "providerUrl": { "type": "string", "format": "uri", "description": "Photo provider URL" } } } }, "openState": { "type": "string", "description": "Current open/closed status", "example": "Open · Closes 9 PM" }, "category": { "type": "string", "description": "Business category", "example": "Amusement park" }, "price": { "description": "Price level (if available)" }, "layerLabel": { "type": "string", "description": "Map layer grouping label", "example": "Theme Parks" } }, "example": { "name": "WonderWorks Pigeon Forge", "position": 1, "placeId": "ChIJEYpTsk__W4gR2sQLGzOjE3o", "location": { "address": "100 Music Rd, Pigeon Forge, TN 37863", "latitude": 35.823257, "longitude": -83.5787498 }, "phoneNumber": "(865) 868-1800", "url": "http://www.wonderworksonline.com/pigeon-forge/", "reviews": [ { "count": 10625, "rating": 4.3, "providerName": "Google", "providerIconUrl": null, "url": "https://maps.google.com/?cid=8796553937077126362" } ], "photos": [ { "url": "https://lh3.googleusercontent.com/gps-cs-s/example", "altText": null, "providerName": null, "providerUrl": "https://maps.google.com" } ], "openState": "Open · Closes 9 PM", "category": "Amusement park", "price": null, "layerLabel": "Theme Parks" } } }, "searchQueries": { "type": "array", "description": "Array of query fan-out — the web search queries Copilot ran while generating the response. Automatically included when at least one is available, no surcharge.", "items": { "type": "string" }, "example": [ "best laptops for programming 2025", "developer laptop reviews" ] }, "markdown": { "type": "string", "description": "Copilot's response formatted in Markdown (included when include.markdown is true)", "example": "As an AI assistant, I can help you find great laptops for programming..." }, "rawResponse": { "type": "array", "description": "Raw upstream provider stream captured during the request. Each item is one chunk from the provider's wire protocol (SSE event, batchexecute frame, etc.). Format is provider-specific, undocumented, and may change without notice — use it for debugging or to access data not yet surfaced in the structured fields above.", "items": {} } } } } }, "PerplexityMonitorRequest": { "required": [ "prompt", "country" ], "type": "object", "properties": { "prompt": { "description": "The prompt to send to Perplexity", "type": "string", "minLength": 1, "maxLength": 10000, "example": "What are the best laptops for programming?" }, "country": { "description": "Country/region code for localized response", "type": "string", "example": "US" }, "include": { "description": "Optional flags for including additional response formats", "type": "object", "properties": { "html": { "description": "Include a URL to the full HTML of the response", "type": "boolean", "default": false, "example": true }, "markdown": { "description": "Include markdown-formatted response in the result", "type": "boolean", "default": false, "example": true }, "rawResponse": { "description": "Include raw streaming response events", "type": "boolean", "default": false, "example": true } }, "default": { "html": false, "markdown": false, "rawResponse": false }, "additionalProperties": false }, "state": { "$ref": "#/components/schemas/StateParameter" } }, "additionalProperties": false }, "PerplexityMonitorResponse": { "required": [ "success", "result" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "description": "Perplexity response data", "type": "object", "properties": { "text": { "type": "string", "description": "Perplexity's response text", "example": "Based on current sources and information, here are the best laptops for programming..." }, "html": { "type": "string", "format": "uri", "description": "A URL to the full HTML of the response.", "example": "https://storage.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html" }, "sources": { "type": "array", "description": "Array of sources referenced in the response", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "The position index of the source in the response", "example": 1 }, "url": { "type": "string", "description": "The URL of the source", "example": "https://example.com/article" }, "label": { "type": "string", "description": "The display label for the source", "example": "Perplexity Search" }, "description": { "type": "string", "description": "A description of the source content", "example": "Real-time web search results" } } }, "example": [ { "position": 1, "url": "https://techcrunch.com/laptops", "label": "TechCrunch", "description": "Latest laptop reviews and recommendations" }, { "position": 2, "url": "https://www.youtube.com/watch?v=example", "label": "Best Laptops 2026", "description": "Video review of programming laptops" }, { "position": 3, "url": "https://wired.com/programming-laptops", "label": "Wired", "description": "Programming laptop buyer's guide" } ] }, "citationPills": { "type": "array", "description": "Inline citation pills extracted from the Perplexity answer. Each entry is one (pill, source) pair: when a pill cites N sources (Perplexity's `[1][2][3]` bracketed groups), the array contains N entries sharing the same `citationPillId` but carrying per-source `label`, `url`, and `domain`. Group by `citationPillId` to recover the pill-level structure. Omitted from `result` when the answer carries no pills.", "items": { "type": "object", "required": [ "label", "citationPillId", "url", "domain", "position" ], "properties": { "label": { "type": "string", "description": "Per-source title from the sources rail (e.g. `\"Best Programming Laptops 2026 — TechCrunch\"`). Always present; may be an empty string when the rail has no title for this source — read `domain` / `url` for source identity in that case. Entries grouped under the same `citationPillId` carry different per-source labels.", "example": "Best Programming Laptops 2026 — TechCrunch" }, "citationPillId": { "type": "integer", "description": "1-based ordinal shared by all entries from the same chip. Group by `citationPillId` to reconstruct the visible chip; the per-source `label` differs across entries within a chip.", "example": 1 }, "url": { "type": "string", "description": "Direct URL of the cited source.", "example": "https://techcrunch.com/laptops" }, "domain": { "type": "string", "description": "Host extracted from `url`, for grouping and display.", "example": "techcrunch.com" }, "description": { "type": "string", "description": "Source description from the sources rail when Perplexity ships one. Omitted when absent.", "example": "Latest laptop reviews and recommendations" }, "position": { "type": "integer", "description": "1-based position of this source in the sibling `result.sources` array.", "example": 1 } } }, "example": [ { "label": "Best Programming Laptops 2026 — TechCrunch", "citationPillId": 1, "url": "https://techcrunch.com/laptops", "domain": "techcrunch.com", "description": "Latest laptop reviews and recommendations", "position": 1 }, { "label": "Wired Laptop Buyer's Guide", "citationPillId": 1, "url": "https://wired.com/programming-laptops", "domain": "wired.com", "description": "Programming laptop buyer's guide", "position": 3 } ] }, "markdown": { "type": "string", "description": "Perplexity's response formatted in Markdown (included when include.markdown is true)", "example": "Based on current sources and information, here are the best laptops for programming..." }, "related_queries": { "type": "array", "description": "Suggested follow-up search queries", "items": { "type": "string" }, "example": [ "best neighborhoods to stay in Lisbon", "top-rated luxury hotels in Lisbon under €300", "highest-rated traditional Portuguese restaurants in Baixa" ] }, "videos": { "type": "array", "description": "Video content found in response", "items": { "$ref": "#/components/schemas/MediaItem" } }, "images": { "type": "array", "description": "Image content found in response", "items": { "$ref": "#/components/schemas/MediaItem" } }, "hotels": { "type": "array", "description": "Hotel listings (when travel intent detected)", "items": { "$ref": "#/components/schemas/HotelItem" } }, "places": { "type": "array", "description": "General places and locations", "items": { "$ref": "#/components/schemas/PlaceItem" } }, "shopping_cards": { "type": "array", "description": "Shopping product cards with detailed product information (when shopping intent detected)", "items": { "type": "object", "properties": { "tags": { "type": "array", "description": "Optional category tags for the shopping card", "items": { "type": "string" }, "example": [ "running", "athletic" ] }, "products": { "type": "array", "description": "Array of product objects", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Product name", "example": "Nike Pegasus 41" }, "id": { "type": "string", "description": "Product identifier", "example": "nike-pegasus-41" }, "url": { "type": "string", "description": "Product page URL", "example": "https://www.nike.com/t/pegasus-41" }, "price": { "type": "string", "description": "Current price", "example": "$140.00" }, "merchant": { "type": "string", "description": "Merchant name", "example": "Nike" }, "available": { "type": "boolean", "description": "Whether the product is currently available", "example": true }, "imageUrls": { "type": "array", "description": "Product image URLs", "items": { "type": "string" } }, "numReviews": { "type": "number", "description": "Number of reviews (0 when none)", "example": 1284 }, "offers": { "type": "array", "description": "Shopping offers from individual merchants", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Offer URL with Perplexity referral parameters" }, "price": { "type": "string", "description": "Offer price", "example": "$140.00" }, "merchant_name": { "type": "string", "description": "Merchant name", "example": "Nike" }, "product_name": { "type": "string", "description": "Product name as listed by the merchant", "example": "Nike Pegasus 41 Running Shoes" }, "available": { "type": "boolean", "description": "Whether the offer is in stock", "example": true }, "price_details": { "type": "object", "description": "Detailed price breakdown", "properties": { "display_price": { "type": "string", "description": "Formatted display price", "example": "$140.00" } } }, "original_price": { "type": "string", "nullable": true, "description": "Original price before discount; null when not on sale", "example": null } } } }, "position": { "type": "integer", "description": "1-indexed rank across all products in all shopping cards in the response (flat, not reset per card)", "example": 1 }, "rating": { "type": "number", "description": "Product rating (0-5 scale)", "example": 4.6 }, "original_price": { "type": "string", "nullable": true, "description": "Original price before discount; null when not on sale" }, "description": { "type": "string", "description": "Product description", "example": "Responsive cushioning for daily training runs." }, "variants": { "type": "array", "description": "Product variants (size, color, etc.)", "items": { "type": "object" } } } } } } } }, "search_model_queries": { "type": "array", "description": "Internal search queries used to generate response", "items": { "$ref": "#/components/schemas/SearchModelQuery" } }, "rawResponse": { "type": "array", "description": "Raw upstream provider stream captured during the request. Each item is one chunk from the provider's wire protocol (SSE event, batchexecute frame, etc.). Format is provider-specific, undocumented, and may change without notice — use it for debugging or to access data not yet surfaced in the structured fields above.", "items": {} } } } } }, "AiModeMonitorRequest": { "required": [ "prompt", "country" ], "type": "object", "properties": { "prompt": { "description": "The prompt to send to AI Mode", "type": "string", "minLength": 1, "maxLength": 10000, "example": "What are the best laptops for programming?" }, "country": { "description": "Country/region code for localized response", "type": "string", "example": "US" }, "location": { "description": "Google canonical location name for geo-targeted results, in comma-separated format: 'City,Region,Country' (see https://developers.google.com/google-ads/api/reference/data/geotargets for all ~100,000 supported locations). Use alongside 'country' for city-level precision. Mutually exclusive with 'uule' — provide one or the other, not both.", "type": "string", "example": "New York,New York,United States" }, "uule": { "description": "Pre-encoded Google UULE string for precise geo-targeting. Use this when you have a pre-built UULE value instead of a location name. Mutually exclusive with 'location' — provide one or the other, not both.", "type": "string", "example": "w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5" }, "device": { "description": "Device type for search results", "type": "string", "enum": [ "desktop", "mobile" ], "default": "desktop", "example": "desktop" }, "include": { "description": "Optional flags for including additional response formats", "type": "object", "properties": { "html": { "description": "Include a URL to the full HTML of the response", "type": "boolean", "default": false, "example": true }, "markdown": { "description": "Include markdown-formatted response in the result", "type": "boolean", "default": false, "example": true } }, "default": { "html": false, "markdown": false }, "additionalProperties": false } }, "additionalProperties": false }, "AiModeMonitorResponse": { "required": [ "success", "result" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "description": "AI Mode response data", "type": "object", "properties": { "text": { "type": "string", "description": "AI Mode's response text", "example": "Here are some excellent laptop recommendations for programming..." }, "html": { "type": "string", "format": "uri", "description": "A URL to the full HTML of the response.", "example": "https://storage.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html" }, "sources": { "type": "array", "description": "Array of sources referenced in the response", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "The position index of the source in the response", "example": 1 }, "url": { "type": "string", "description": "The URL of the source", "example": "https://example.com/article" }, "label": { "type": "string", "description": "The display label for the source", "example": "AI Source" }, "description": { "type": "string", "description": "A description of the source content", "example": "AI-generated recommendations" } } }, "example": [ { "position": 1, "url": "https://example.com/ai-recommendations", "label": "AI Source", "description": "AI-curated laptop recommendations" } ] }, "citationPills": { "type": "array", "description": "Inline citation pills extracted from the AI Mode answer. Each entry is one (pill, source) pair: when a pill cites N sources (Google's `[Label +N]` chips), the array contains N entries sharing the same `citationPillId` but carrying per-source `label`, `url`, and `domain`. Group by `citationPillId` to recover the pill-level structure. Omitted from `result` when the answer carries no pills.", "items": { "type": "object", "required": [ "label", "citationPillId", "url", "domain", "position" ], "properties": { "label": { "type": "string", "description": "Per-source title from the sources rail (for example `\"Best Laptops 2026 — Reuters\"`). Empty string when the rail has no title for this source — consumers should read `domain` / `url` for source identity in that case. Entries grouped under the same `citationPillId` carry different per-source labels.", "example": "Best Laptops 2026 — Reuters" }, "citationPillId": { "type": "integer", "description": "1-based ordinal shared by all entries from the same chip. Group by `citationPillId` to reconstruct the visible chip; the per-source `label` differs across entries within a chip.", "example": 1 }, "url": { "type": "string", "description": "Direct URL of the cited source.", "example": "https://example.com/best-laptops-2026" }, "domain": { "type": "string", "description": "Host extracted from `url`, for grouping and display.", "example": "example.com" }, "description": { "type": "string", "description": "Source description from the sources rail when Google ships one. Omitted when the source carries no snippet.", "example": "A guide to the top laptops for software development this year." }, "position": { "type": "integer", "description": "1-based position of this source in the sibling `result.sources` array.", "example": 1 } } }, "example": [ { "label": "Best Laptops 2026 — Reuters", "citationPillId": 1, "url": "https://example.com/best-laptops-2026", "domain": "example.com", "description": "A guide to the top laptops for software development this year.", "position": 1 }, { "label": "MacBook Pro M4 Hands-On Review", "citationPillId": 1, "url": "https://example.com/macbook-pro-review", "domain": "example.com", "position": 3 } ] }, "markdown": { "type": "string", "description": "AI Mode's response formatted in Markdown (included when include.markdown is true)", "example": "Here are some excellent laptop recommendations for programming..." }, "places": { "type": "array", "description": "Inline place cards extracted from the response", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Place name", "example": "Gion District" }, "link": { "type": "string", "format": "uri", "description": "Google viewer URL for the place", "example": "https://www.google.com/viewer/place?mid=/g/11bw3yq9kp" }, "placeId": { "type": "string", "description": "Google Places ID", "example": "/g/11bw3yq9kp" }, "index": { "type": "integer", "description": "Position index of the place in the results", "example": 0 }, "thumbnail": { "type": "string", "format": "uri", "description": "Place thumbnail image URL", "example": "https://lh5.googleusercontent.com/p/example" }, "rating": { "type": "number", "description": "Star rating (0-5)", "example": 4.5 }, "reviews": { "type": "integer", "description": "Number of reviews", "example": 2900 }, "type": { "type": "string", "description": "Place type or category", "example": "Tourist attraction" }, "priceLevel": { "type": "string", "description": "Price level indicator", "example": "$$" }, "address": { "type": "string", "description": "Full address", "example": "Gionmachi, Higashiyama Ward, Kyoto" }, "status": { "type": "string", "description": "Operating status", "example": "Open now" } } } }, "shoppingCards": { "type": "array", "description": "Shopping product information extracted from the response", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Product title", "example": "Wireless Headphones" }, "price": { "type": "object", "description": "Structured pricing information", "properties": { "value": { "type": "number", "description": "Numeric price", "example": 99.99 }, "currency": { "type": "string", "description": "Currency symbol", "example": "$" }, "raw": { "type": "string", "description": "Raw price string as returned by the upstream provider (e.g. \"$129.99\").", "example": "$129.99" } } }, "store": { "type": "string", "description": "Merchant/store name", "example": "Amazon" }, "rating": { "type": "number", "description": "Product rating", "example": 4.2 }, "reviews": { "type": "string", "description": "Review count", "example": "2.3k" }, "thumbnail": { "type": "string", "format": "uri", "description": "Product image", "example": "https://example.com/product.jpg" }, "productLink": { "type": "string", "format": "uri", "description": "Direct product URL", "example": "https://www.google.com/example" }, "oldPrice": { "type": "object", "description": "Original price before discount", "properties": { "value": { "type": "number", "description": "Numeric price", "example": 129.99 }, "currency": { "type": "string", "description": "Currency symbol", "example": "$" }, "raw": { "type": "string", "description": "Raw price string as returned by the upstream provider (e.g. \"$129.99\").", "example": "$129.99" } } }, "snippet": { "type": "string", "description": "Product description snippet", "example": "Noise-canceling wireless headphones with 30-hour battery life" }, "snippet_links": { "type": "array", "description": "Links found within the product snippet", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Link text", "example": "noise canceling" }, "link": { "type": "string", "format": "uri", "description": "Link URL", "example": "https://www.google.com/search?q=noise+canceling" } } } }, "position": { "type": "integer", "description": "Position of the product card in the shopping carousel (0-indexed).", "example": 0 } } } }, "ads": { "type": "object", "description": "Sponsored ad section extracted from the response", "properties": { "title": { "type": "string", "description": "Section title for the ads", "example": "Here are some 3D printers to consider" }, "ads": { "type": "array", "description": "Array of sponsored ads", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Ad product title", "example": "Bambu Lab X2D" }, "url": { "type": "string", "format": "uri", "description": "Ad click-through URL", "example": "https://www.google.com/aclk?sa=L&ai=abc" }, "position": { "type": "integer", "description": "Position index of the ad", "example": 1 }, "price": { "type": "object", "description": "Structured pricing information", "properties": { "value": { "type": "number", "description": "Numeric price", "example": 899 }, "currency": { "type": "string", "description": "Currency symbol", "example": "$" } } }, "store": { "type": "string", "description": "Merchant/store name", "example": "Bambu Lab US" }, "rating": { "type": "number", "description": "Product rating", "example": 4.7 }, "reviews": { "type": "string", "description": "Review count", "example": "584" } } } } } }, "inlineProducts": { "type": "array", "description": "Inline product cards found within the AI response text", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Product title", "example": "Sony WH-1000XM5" }, "position": { "type": "integer", "description": "1-indexed rank across the `inline_products` array in DOM/render order.", "example": 1 }, "price": { "type": "object", "description": "Structured pricing information", "properties": { "value": { "type": "number", "description": "Numeric price", "example": 298 }, "currency": { "type": "string", "description": "Currency symbol", "example": "$" } } }, "oldPrice": { "type": "object", "description": "Original price before discount", "properties": { "value": { "type": "number", "description": "Numeric price", "example": 399.99 }, "currency": { "type": "string", "description": "Currency symbol", "example": "$" } } }, "store": { "type": "string", "description": "Merchant/store name", "example": "Amazon" }, "thumbnail": { "type": "string", "format": "uri", "description": "Product image URL", "example": "https://encrypted-tbn0.gstatic.com/images?q=example" }, "productLink": { "type": "string", "format": "uri", "description": "Direct product URL", "example": "https://www.google.com/shopping/product/example" } } } }, "videos": { "type": "array", "description": "Inline video cards embedded in the AI response (currently YouTube)", "items": { "type": "object", "required": [ "title", "link" ], "properties": { "title": { "type": "string", "description": "Video title", "example": "The BEST 3D Printer for YOU - Don't Buy the Wrong One!" }, "link": { "type": "string", "format": "uri", "description": "Canonical watch URL (timestamp parameters stripped)", "example": "https://www.youtube.com/watch?v=g0DZnQdI-xQ" }, "platform": { "type": "string", "description": "Hosting platform parsed from the card byline", "example": "YouTube" }, "channel": { "type": "string", "description": "Channel or uploader name", "example": "3D Print Dood" }, "duration": { "type": "string", "description": "Visible duration label (mm:ss or hh:mm:ss)", "example": "08:49" }, "thumbnail": { "type": "string", "format": "uri", "description": "Public thumbnail URL", "example": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcS5Bntg3F0Y7P3YgTPgdyillyeCguV_YQJ99KFUmNYxmQtVt1f2" } } } }, "map": { "type": "array", "description": "GPS-enriched location data extracted from the response", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Place name", "example": "Central Park Cafe" }, "link": { "type": "string", "format": "uri", "description": "Google viewer URL for the place", "example": "https://www.google.com/viewer/place?mid=/g/11bw3yq9kp" }, "placeId": { "type": "string", "description": "Google Places ID", "example": "/g/11bw3yq9kp" }, "index": { "type": "integer", "description": "Position index of the place in the results", "example": 0 }, "gps_coordinates": { "type": "object", "description": "Geographic coordinates of the place", "properties": { "latitude": { "type": "number", "description": "Latitude coordinate", "example": 40.7831 }, "longitude": { "type": "number", "description": "Longitude coordinate", "example": -73.9712 } } }, "thumbnail": { "type": "string", "format": "uri", "description": "Place thumbnail image URL", "example": "https://lh5.googleusercontent.com/p/example" }, "rating": { "type": "number", "description": "Star rating (0-5)", "example": 4.5 }, "reviews": { "type": "integer", "description": "Number of reviews", "example": 1234 }, "type": { "type": "string", "description": "Place type or category", "example": "Coffee shop" }, "address": { "type": "string", "description": "Full address", "example": "123 Broadway, New York" }, "status": { "type": "string", "description": "Operating status", "example": "Open now" } } } } } } } }, "MediaItem": { "type": "object", "description": "Media content (video or image) found in response", "properties": { "title": { "type": "string", "description": "Media title", "example": "Best hotels in Lisbon, reviewed | The Independent" }, "url": { "type": "string", "description": "Media URL", "example": "https://www.independent.co.uk/travel/europe/portugal/lisbon/best-lisbon-portugal-hotels-b1987832.html" }, "thumbnail": { "type": "string", "description": "Thumbnail URL", "example": "https://d2u1z1lopyfwlx.cloudfront.net/thumbnails/636fbd12-6dee-5f44-a76d-fe7f9cd20e40/75ce41cb-6767-5082-a330-ee97c5866886.jpg" }, "medium": { "type": "string", "description": "Media type", "enum": [ "video", "image", "map" ], "example": "image" }, "source": { "type": "string", "description": "Source platform", "example": "web" }, "image_width": { "type": "number", "description": "Original image width", "example": 5600 }, "image_height": { "type": "number", "description": "Original image height", "example": 3733 }, "thumbnail_width": { "type": "number", "description": "Thumbnail width", "example": 300 }, "thumbnail_height": { "type": "number", "description": "Thumbnail height", "example": 200 } } }, "HotelItem": { "type": "object", "description": "Hotel listing with detailed information", "properties": { "name": { "type": "string", "description": "Hotel name", "example": "Corpo Santo Lisbon Historical Hotel" }, "url": { "type": "string", "description": "Hotel page URL", "example": "https://www.tripadvisor.com/Hotel_Review-g189158-d12659702-Reviews-Corpo_Santo_Lisbon_Historical_Hotel-Lisbon_District_Central_Portugal.html" }, "rating": { "type": "number", "description": "Hotel rating (0-5)", "example": 4.9 }, "num_reviews": { "type": "number", "description": "Number of reviews", "example": 4374 }, "address": { "type": "array", "description": "Address lines", "items": { "type": "string" }, "example": [ "Largo do Corpo Santo, 25, Lisbon 1200-129 Portugal" ] }, "phone": { "type": "string", "description": "Phone number", "example": "+351 21 828 8000" }, "description": { "type": "string", "description": "Hotel description", "example": "Located next to the riverside area, in one of the prime areas of the Lisbon Center..." }, "image_url": { "type": "string", "description": "Main hotel image URL", "example": "https://media-cdn.tripadvisor.com/media/photo-o/30/28/6c/86/caption.jpg" }, "images": { "type": "array", "description": "Additional hotel image URLs", "items": { "type": "string" } }, "lat": { "type": "number", "description": "Latitude", "example": 38.707397 }, "lng": { "type": "number", "description": "Longitude", "example": -9.142318 }, "price_level": { "type": "string", "description": "Price level indicator" }, "categories": { "type": "array", "description": "Hotel categories", "items": { "type": "string" }, "example": [ "Hotel" ] } } }, "PlaceItem": { "type": "object", "description": "General place or location information", "properties": { "name": { "type": "string", "description": "Place name", "example": "Floresta Das Escadinhas" }, "url": { "type": "string", "description": "Place page URL", "example": "https://www.tripadvisor.com/Restaurant_Review-g189158-d1520116-Reviews-Floresta_Das_Escadinhas-Lisbon_District_Central_Portugal.html" }, "rating": { "type": "number", "description": "Place rating (0-5)", "example": 4.8 }, "address": { "type": "array", "description": "Address lines", "items": { "type": "string" }, "example": [ "Rua de Santa Justa N°3, Lisbon 1100-483 Portugal" ] }, "lat": { "type": "number", "description": "Latitude", "example": 38.712717 }, "lng": { "type": "number", "description": "Longitude", "example": -9.136362 }, "categories": { "type": "array", "description": "Place categories", "items": { "type": "string" }, "example": [ "Healthy", "Grill", "Barbecue", "Mediterranean", "Portuguese", "European" ] }, "map_url": { "type": "string", "description": "Map URL", "example": "https://google.com/maps/?q=find+best+hotels+and+restaurants+in+lisbon&ll=38.720914,-9.147162&z=15" }, "images": { "type": "array", "description": "Place image URLs", "items": { "type": "string" } } } }, "ShoppingCard": { "type": "object", "description": "Shopping product card with detailed product information", "properties": { "products": { "type": "array", "description": "Array of product objects", "items": { "$ref": "#/components/schemas/ShoppingProduct" } }, "tags": { "type": "array", "description": "Category tags", "items": { "type": "string" }, "example": [ "electronics", "gadgets" ] } } }, "ImagePosition": { "type": "object", "description": "Pixel offset for image positioning within a slot", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] }, "SlotPlacement": { "type": "object", "description": "Percent-based placement of a showcase slot within its container", "properties": { "leftPercent": { "type": "number" }, "topPercent": { "type": "number" }, "widthPercent": { "type": "number" }, "heightPercent": { "type": "number" } } }, "ShowcaseSlot": { "type": "object", "description": "Single visual slot inside a product showcase", "properties": { "fit": { "type": "string" }, "position": { "$ref": "#/components/schemas/ImagePosition" }, "zoom": { "type": "number" }, "placement": { "$ref": "#/components/schemas/SlotPlacement" }, "imageBlendMode": { "type": "string" } } }, "ShowcaseImage": { "type": "object", "description": "Image rendered as the hero of a product showcase", "properties": { "url": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "url" ] }, "ShowcaseBackground": { "type": "object", "description": "Background styling for a product showcase", "properties": { "type": { "type": "string" }, "primary": { "type": "string" }, "secondary": { "type": "string" } } }, "ShowcaseMetadata": { "type": "object", "description": "Visual showcase metadata attached to a shopping product (image, background, and per-slot placement).", "properties": { "image": { "$ref": "#/components/schemas/ShowcaseImage" }, "background": { "$ref": "#/components/schemas/ShowcaseBackground" }, "slots": { "type": "object", "description": "Slot map keyed by slot identifier", "additionalProperties": { "$ref": "#/components/schemas/ShowcaseSlot" } }, "debug": { "type": "object", "description": "Free-form debug metadata; opaque to clients", "additionalProperties": true } } }, "ShoppingProduct": { "type": "object", "description": "Individual product information", "properties": { "title": { "type": "string", "description": "Product name", "example": "Nike Court Vision Low Next Nature Shoes" }, "position": { "type": "integer", "description": "1-indexed rank across all products in all shopping cards in the response (flat, not reset per card).", "example": 1 }, "url": { "type": "string", "description": "Product page URL", "example": "https://www.amazon.in/Nike-Court-Vision-Shoes/dp/B098F6QPLK?utm_source=chatgpt.com" }, "description": { "type": "string", "description": "Product description", "example": "Classic sneaker with modern comfort features" }, "price": { "type": "string", "description": "Current price", "example": "$79.99" }, "featured_tag": { "type": "string", "description": "Product category or style tag", "example": "stylish casual leather sneaker" }, "rating": { "type": "number", "description": "Product rating (0-5)", "example": 4.5 }, "num_reviews": { "type": "integer", "description": "Number of reviews", "example": 8703 }, "image_urls": { "type": "array", "description": "Product image URLs", "items": { "type": "string" } }, "id": { "type": "string", "description": "Product identifier", "example": "prod_12345" }, "variants": { "description": "Product variants (size, color, etc.)" }, "offers": { "type": "array", "description": "Shopping offers with pricing details from different merchants", "items": { "$ref": "#/components/schemas/ShoppingOffer" } }, "rating_grouped_citation": { "$ref": "#/components/schemas/RatingGroupedCitation" }, "provider": { "type": "string", "description": "Data provider identifier", "example": "deprecated" }, "providers": { "type": "array", "description": "List of data providers", "items": { "type": "string" }, "example": [ "product_info" ] }, "product_lookup_key": { "type": "object", "description": "Key used to look up product updates", "properties": { "data": { "type": "string", "description": "JSON-encoded product lookup data" } } }, "product_lookup_data": { "type": "object", "description": "Structured product lookup query data", "properties": { "request_query": { "type": "string", "description": "Search query used for this product" }, "all_ids": { "type": "object", "description": "Provider-to-ID mapping", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "metadata_sources": { "type": "array", "items": { "type": "string" } } } }, "showcase_metadata": { "$ref": "#/components/schemas/ShowcaseMetadata" }, "show_price_disclosure": { "type": "boolean", "description": "Whether to show price disclosure", "example": false }, "analytics_meta": { "type": "object", "description": "Analytics metadata", "properties": { "product_event_uuid": { "type": "string", "description": "UUID for product analytics event" } } }, "metadata_sources": { "type": "array", "description": "Sources of product metadata", "items": { "type": "string" }, "example": [ "p2" ] }, "product_event_uuid": { "type": "string", "description": "UUID for product event tracking" }, "generatedProductQuery": { "type": "string", "description": "Broad shopping query ChatGPT generated for this product (extracted from product_lookup_key.data). Useful for understanding the search intent behind the recommendation.", "example": "best microwaves uk 2026 countertop inverter combi microwave" } } }, "ShoppingOffer": { "type": "object", "description": "Shopping offer with pricing details from a specific merchant", "properties": { "merchant_name": { "type": "string", "description": "Merchant name", "example": "Amazon.in" }, "merchant_subtitle": { "type": "string", "description": "Merchant subtitle or additional info", "nullable": true }, "product_name": { "type": "string", "description": "Product name as listed by merchant", "example": "Nike Men's Court Vision Low Next Nature Shoes" }, "url": { "type": "string", "description": "Offer URL with attribution", "example": "https://www.amazon.in/dp/B098F6QPLK?utm_source=chatgpt.com" }, "price": { "type": "string", "description": "Offer price", "example": "$79.99" }, "details": { "type": "string", "description": "Stock and delivery information", "example": "In stock online, Free delivery" }, "original_price": { "type": "string", "description": "Original price before discount", "nullable": true }, "available": { "type": "boolean", "description": "Whether the product is available", "example": true }, "checkoutable": { "type": "boolean", "description": "Whether the product can be checked out directly", "example": false }, "is_digital": { "type": "boolean", "description": "Whether this is a digital product", "nullable": true }, "checkout_payload": { "type": "string", "description": "Checkout payload data", "nullable": true }, "checkout_image_urls": { "type": "array", "description": "Image URLs for checkout display", "items": { "type": "string" }, "nullable": true }, "shop_id": { "type": "string", "description": "Shop identifier", "nullable": true }, "provider": { "type": "string", "description": "Data provider identifier", "example": "p2" }, "price_details": { "$ref": "#/components/schemas/PriceDetails" }, "tag": { "$ref": "#/components/schemas/OfferTag" } } }, "PriceDetails": { "type": "object", "description": "Detailed price breakdown for an offer", "properties": { "display_price": { "type": "string", "description": "Formatted display price", "nullable": true }, "base": { "type": "string", "description": "Base product price", "example": "$79.99" }, "shipping": { "type": "string", "description": "Shipping cost", "nullable": true }, "tax": { "type": "string", "description": "Tax amount", "nullable": true }, "total": { "type": "string", "description": "Total price", "example": "$79.99" } } }, "OfferTag": { "type": "object", "description": "Promotional tag on an offer", "properties": { "text": { "type": "string", "description": "Tag text", "example": "Best price" }, "tooltip": { "type": "string", "description": "Tag tooltip text" } }, "nullable": true }, "RatingGroupedCitation": { "type": "object", "description": "Rating source information with supporting websites", "properties": { "title": { "type": "string", "description": "Source title", "example": "Nike Men's Court Vision Low Next Nature Shoes" }, "url": { "type": "string", "description": "Source URL", "example": "https://www.amazon.in/dp/B098F6QPLK" }, "supporting_websites": { "type": "array", "description": "Array of supporting website references", "items": { "type": "object" } } } }, "InlineProduct": { "type": "object", "description": "Inline product reference that appeared in the response text, including pricing and offers", "properties": { "product": { "$ref": "#/components/schemas/ShoppingProduct" }, "render_as": { "type": "string", "description": "How the product is rendered in the response", "enum": [ "inline", "hero", "block" ], "example": "hero" }, "details": { "type": "object", "description": "Product rationale and reviews fetched from sidebar API", "properties": { "rationale": { "type": "object", "properties": { "rationale": { "type": "string", "description": "AI-generated rationale for recommending this product" }, "citations": { "type": "array", "description": "Citations supporting the rationale", "items": { "type": "object" } } } }, "reviews": { "type": "object", "properties": { "summary": { "type": "string", "description": "Summary of product reviews" }, "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/ProductReview" } } } } } } } }, "ProductReview": { "type": "object", "description": "Individual product review extracted from sources", "properties": { "source": { "type": "string", "description": "Review source", "example": "Amazon" }, "theme": { "type": "string", "description": "Review theme or aspect", "example": "Ease of Use" }, "summary": { "type": "string", "description": "Review summary text" }, "sentiment": { "type": "string", "description": "Review sentiment", "enum": [ "positive", "neutral", "negative" ] }, "cite": { "type": "string", "description": "Citation reference", "nullable": true }, "rating": { "type": "number", "description": "Source rating", "nullable": true }, "num_reviews": { "type": "integer", "description": "Number of reviews at source", "nullable": true }, "cite_url": { "type": "string", "description": "Citation URL", "nullable": true } } }, "SearchModelQuery": { "type": "object", "description": "Internal search query used to generate response", "properties": { "query": { "type": "string", "description": "Actual search query used", "example": "find best hotels and restaurants in lisbon" }, "engine": { "type": "string", "description": "Search engine type", "example": "web" }, "limit": { "type": "number", "description": "Result limit", "example": 8 } } }, "StateParameter": { "description": "State code for sub-country geo-targeting (e.g., \"CA\"). Only valid with country \"US\".", "type": "string", "example": "CA", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$" } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } } }