{ "openapi": "3.1.0", "info": { "title": "Answerline API", "description": "Answerline tracks how AI assistants and search engines answer, across providers and regions. Each request comes back as structured JSON holding the engine's answer: the parsed text, its cited sources and whatever else the engine returned with them, geo-targeted to a country you choose (which countries are available depends on the engine; see [coverage](/docs/coverage)).\n\n## Authentication\n\nPass your API key in the header `Authorization: Bearer `. You can create keys yourself at https://dashboard.answerline.dev/keys, and each new account begins on a free tier with 500 one-time credits. A single key works for all endpoints; keys cannot currently be limited to particular scopes.\n\n## Versioning and deprecation\n\nThe URL path carries the version. All endpoints sit under `/v1/`; no header or query parameter selects a version.\n\nChanges inside a version only add things: new endpoints, optional request fields and response fields may be introduced at any moment. Clients have to skip response fields they don't know. Anything breaking ships under a new path (`/v2/`) and never replaces an existing version.\n\nDeprecation is announced in the endpoint's responses themselves, not just in a changelog: the `Deprecation` header (RFC 9745) gives the date it became deprecated, `Sunset` (RFC 8594) gives the date it will stop answering, and the replacement is given by a `Link` header carrying `rel=\"deprecation\"`. For generally available endpoints, those two dates are at least six months apart. No endpoint is currently deprecated.\n\n## Rate limits\n\nEach response reports the current limit state, letting a client pace itself using the response in hand: `X-RateLimit-Limit` and `X-RateLimit-Remaining`, plus the headers for concurrency and credits. Rate limiting uses a one-second window, so a `429` caused by it goes away almost at once; a `429` caused by the concurrency limit goes away once your running jobs complete. `Retry-After` is not set on either, and no IETF `RateLimit-*` headers are sent.\n\n## Errors\n\nAll 4xx and 5xx responses share the `Error` envelope: `{ \"error\": { \"code\", \"message\", \"details\", \"timestamp\" } }`. Clients should branch on `code`, a stable identifier meant for machines; `message` is meant for people reading logs.", "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }, "version": "1.0.0", "contact": { "name": "answerline support", "email": "support@answerline.dev" }, "termsOfService": "https://answerline.dev/legal/terms" }, "servers": [ { "url": "https://api.answerline.dev", "description": "Production server" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/monitor/chatgpt": { "post": { "summary": "Track ChatGPT answers", "description": "Get structured output from ChatGPT for any prompt in supported regions: the answer, its cited sources, ads, shopping cards and brand entities", "operationId": "monitorChatgpt", "requestBody": { "description": "Parameters for a ChatGPT monitoring request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatGPTMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "ChatGPT monitoring result (success)", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 3420 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatGPTMonitorResponse" } } } }, "400": { "description": "Bad Request - the request failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - missing permissions or not enough credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - No such route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - the resource is in a conflicting state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests - the request went over a rate limit or concurrency limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 12 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - the client cancelled the request", "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 - an upstream service failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/gemini": { "post": { "summary": "Track Gemini answers", "description": "Get structured output from Google Gemini for any prompt: the generated answer and the sources it cites, exportable as Markdown", "operationId": "monitorGemini", "requestBody": { "description": "Parameters for a Gemini monitoring request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "Gemini monitoring result (success)", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 3420 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiMonitorResponse" } } } }, "400": { "description": "Bad Request - the request failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - missing permissions or not enough credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - No such route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - the resource is in a conflicting state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests - the request went over a rate limit or concurrency limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 12 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - the client cancelled the request", "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 - an upstream service failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/grok": { "post": { "summary": "Track Grok answers", "description": "Get structured output from Grok for any prompt in supported regions: the answer and the sources it cites, X/Twitter posts included", "operationId": "monitorGrok", "requestBody": { "description": "Parameters for a Grok monitoring request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrokMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "Grok monitoring result (success)", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 3420 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrokMonitorResponse" } } } }, "400": { "description": "Bad Request - the request failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - missing permissions or not enough credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - No such route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - the resource is in a conflicting state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests - the request went over a rate limit or concurrency limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 12 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - the client cancelled the request", "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 - an upstream service failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/google": { "post": { "summary": "Track Google Search results", "description": "Get structured output from Google Search: organic listings, related searches, People Also Ask and, optionally, the AI Overview", "operationId": "monitorGoogle", "requestBody": { "description": "Parameters for a Google search monitoring request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "Google monitoring result (success)", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 3420 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleMonitorResponse" } } } }, "400": { "description": "Bad Request - one or more parameters are not valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - API key absent or not valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - not enough credits, or access was refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - No such route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - the resource is in a conflicting state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests - the request went over a rate limit or concurrency limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 12 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - the client cancelled the request", "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 - an upstream service failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/google/goto": { "post": { "summary": "Get the target of a Google redirect link", "description": "Returns the destination URL of a single Google redirect link. Pass the `redirectLink` value that accompanies each resolved link in a Google Search, Google News or AI Mode response; the reply contains the URL it leads to.\n\nFree of credit charges and takes no concurrency slot, but it counts toward the per-second rate limit the same way other calls do. One link is resolved per request, and Google is given up to 10 seconds to respond.", "operationId": "resolveGoogleGoto", "requestBody": { "description": "Google redirect link that should be resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleGotoRequest" } } }, "required": true }, "responses": { "200": { "description": "Target URL that the redirect link leads to", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleGotoResponse" } } } }, "400": { "description": "Bad Request - url is absent, badly formed, or not a /goto or /url link on google.com", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - API key absent or not valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "429": { "description": "Too Many Requests - the request went over a rate limit or concurrency limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "Bad Gateway - Google's reply was not a redirect, or calling Google failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/google/news": { "post": { "summary": "Track Google News results", "description": "Get structured articles from Google News: title, link, snippet, source, date and thumbnail for each", "operationId": "monitorGoogleNews", "requestBody": { "description": "Parameters for a Google News monitoring request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleNewsMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "Google News monitoring result (success)", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 3420 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleNewsMonitorResponse" } } } }, "400": { "description": "Bad Request - one or more parameters are not valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - API key absent or not valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - not enough credits, or access was refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - No such route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - the resource is in a conflicting state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests - the request went over a rate limit or concurrency limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 12 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - the client cancelled the request", "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 - an upstream service failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/copilot": { "post": { "summary": "Track Copilot answers", "description": "Get structured output from Microsoft Copilot on your brand, your products or any other topic, in many regions", "operationId": "monitorCopilot", "requestBody": { "description": "Parameters for a Copilot monitoring request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopilotMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "Copilot monitoring result (success)", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 3420 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopilotMonitorResponse" } } } }, "400": { "description": "Bad Request - the request failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - missing permissions or not enough credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - No such route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - the resource is in a conflicting state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests - the request went over a rate limit or concurrency limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 12 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - the client cancelled the request", "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 - an upstream service failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/perplexity": { "post": { "summary": "Track Perplexity answers", "description": "Get structured output from Perplexity AI on your brand, your products or any other topic, in many regions", "operationId": "monitorPerplexity", "requestBody": { "description": "Parameters for a Perplexity monitoring request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerplexityMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "Perplexity monitoring result (success)", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 3420 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerplexityMonitorResponse" } } } }, "400": { "description": "Bad Request - the request failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - missing permissions or not enough credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - No such route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - the resource is in a conflicting state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests - the request went over a rate limit or concurrency limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 12 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - the client cancelled the request", "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 - an upstream service failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/monitor/aimode": { "post": { "summary": "Track AI Mode answers", "description": "Get structured output from AI Mode on your brand, your products or any other topic, in many regions", "operationId": "monitorAiMode", "requestBody": { "description": "Parameters for an AI Mode monitoring request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiModeMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "AI Mode monitoring result (success)", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 3 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 7 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 3420 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiModeMonitorResponse" } } } }, "400": { "description": "Bad Request - the request failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - missing permissions or not enough credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found - No such route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict - the resource is in a conflicting state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "429": { "description": "Too Many Requests - the request went over a rate limit or concurrency limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-Concurrent-Limit": { "description": "Upper limit on requests running at once", "schema": { "type": "integer", "example": 10 } }, "X-Concurrent-Current": { "description": "How many requests are running concurrently now", "schema": { "type": "integer", "example": 11 } }, "X-Concurrent-Remaining": { "description": "Concurrency slots still free", "schema": { "type": "integer", "example": 0 } }, "X-Credits-Remaining": { "description": "Credits left on the account balance", "schema": { "type": "number", "example": 494.5 } }, "X-Credits-Charged": { "description": "Credits this request cost", "schema": { "type": "number", "example": 5.5 } }, "X-Latency-Ms": { "description": "Time the server spent handling this request, in milliseconds, not counting network transit.", "schema": { "type": "integer", "example": 12 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConcurrentLimitError" } } } }, "499": { "description": "Client Closed Request - the client cancelled the request", "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 - an upstream service failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalServiceError" } } } } } } }, "/v1/countries": { "get": { "summary": "Array of countries", "description": "Lists every supported country code in ISO 3166-1 alpha-2 format. Filter by model to see which countries a given AI provider supports.", "operationId": "getCountries", "parameters": [ { "name": "model", "in": "query", "description": "Limit the list to countries a given model supports", "schema": { "type": "string", "enum": [ "aimode", "aioverview", "chatgpt", "copilot", "gemini", "google", "grok", "perplexity" ] }, "example": "chatgpt" } ], "responses": { "200": { "description": "Country codes that are supported", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" }, "example": [ "AF", "AX", "AL", "DZ", "AS" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "400": { "description": "Bad Request - the model parameter is not valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "404": { "description": "Not Found - No such route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Too Many Requests - the API key went over its rate limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } }, "/v1/async/task": { "post": { "summary": "Submit an async task", "description": "Queue a task to run asynchronously in the background. The response contains a task ID you can poll for the result, or the result can be delivered by 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": "Which museums in Chicago are free on weekdays?", "country": "US" } } } } }, "responses": { "200": { "description": "Task created. The response includes its ID and starting status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncTaskCreateResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Unauthorized - authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "403": { "description": "Forbidden - missing permissions, or too few credits left to pay for this task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "409": { "description": "Conflict - a task already uses this idempotencyKey", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "422": { "description": "Validation Error - the body of the request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Queue Limit Exceeded - your organization already has the maximum number of queued tasks. This status is also returned when the API key's rate limit is hit and when the API sheds load (`SERVICE_OVERLOADED`, sent with `Retry-After` and without limit headers)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueLimitError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } }, "/v1/async/task/batch": { "post": { "summary": "Submit async tasks in a batch", "description": "Create as many as 500 async tasks in a single request. Tasks are validated one by one, so an invalid task does not stop the others from being accepted. The response lists a result for each task.", "operationId": "createBatchAsyncTasks", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 500, "description": "Tasks to create, one object each.", "items": { "$ref": "#/components/schemas/BatchTaskRequest" } }, "example": [ { "taskType": "CHATGPT", "priority": 5, "idempotencyKey": "batch-chatgpt-001", "webhook": { "url": "https://your-app.com/webhook-handler" }, "payload": { "prompt": "How is Northwind Traders reviewed by customers?", "country": "US" } }, { "taskType": "PERPLEXITY", "priority": 3, "idempotencyKey": "batch-perplexity-001", "payload": { "prompt": "Recent announcements from Northwind Traders", "country": "US" } } ] } } }, "responses": { "200": { "description": "The batch was processed. See the summary and each task's result to learn which tasks succeeded or failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchTaskResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Unauthorized - authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "422": { "description": "Validation Error - the body of the request is empty or not a proper array", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Queue Limit Exceeded - no task in the batch is accepted, because together they would take your organization beyond its queue capacity. This status is also returned when the API key's rate limit is hit and when the API sheds load (`SERVICE_OVERLOADED`, sent with `Retry-After` and without limit headers)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueLimitError" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } }, "/v1/async/task/{taskId}": { "get": { "summary": "Check an async task's status", "description": "Look up an asynchronous task by ID and get its state, plus the complete structured result payload once it finishes.", "operationId": "getTaskStatus", "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Identifier of the task you want to retrieve.", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success: the task's status, plus its result once finished.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskStatusResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Unauthorized - authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "404": { "description": "Not Found - No such task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "429": { "description": "Too Many Requests - the API key went over its rate limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } }, "/v1/async/status": { "get": { "summary": "Check the async queue", "description": "Returns async queue metrics for the whole organization: how many tasks are queued and processing, plus concurrency in use.", "operationId": "getAsyncStatus", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success: queue metrics returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncStatusResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Unauthorized - authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "429": { "description": "Too Many Requests - the API key went over its rate limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } }, "/v1/async/queue": { "delete": { "summary": "Remove queued async tasks", "description": "Removes all of the authenticated organization's tasks that are still `QUEUED`, so a pending backlog can be emptied with a single request rather than through support. `PROCESSING` tasks are already running and stay as they are, and so do `COMPLETED` and `FAILED` ones. No credits were charged for queued tasks, so removing them leaves your credit balance unchanged. Repeating the call is harmless: with nothing queued it returns `cleared: 0`.", "operationId": "clearAsyncQueue", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Queue emptied. The response reports how many queued tasks were deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClearQueueResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Unauthorized - authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "429": { "description": "Too Many Requests - the API key went over its rate limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } }, "/v1/credits": { "get": { "summary": "Read the credit balance", "description": "Get the credit balance and billing cycle currently on your organization's account. This lets you check the balance from code — even for workloads that only use async — without sending a sync /v1/monitor/* request merely to read the X-Credits-Remaining header. The definitive check still happens at the time each task is billed.", "operationId": "getCredits", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The credit balance as of now, with the billing cycle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsResponse" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "401": { "description": "Unauthorized - authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "429": { "description": "Too Many Requests - the API key went over its rate limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } } } }, "/v1/states": { "get": { "summary": "Array of states", "description": "Lists US state codes usable for state-level geo-targeting. That feature is not available yet: until it launches, a request that includes a state is rejected as a validation error. States exist only for the US; any other country value yields an empty array.", "operationId": "getStates", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "Country as an ISO 3166-1 alpha-2 code. Results are available only for \"US\".", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$" }, "example": "US" } ], "responses": { "200": { "description": "States that are supported", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Two-letter state abbreviation as defined by USPS", "example": "CA" }, "name": { "type": "string", "description": "State name written out in full", "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" } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } } }, "400": { "description": "Bad Request — country parameter absent or not valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthorized - authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } } }, "429": { "description": "Too Many Requests - the API key went over its rate limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "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": "Summary fields that every async task response includes.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier unique to the task.", "example": "b27a21e1-7c39-4aa2-a347-23e828c426f9" }, "taskType": { "type": "string", "enum": [ "AIMODE", "GOOGLE", "GOOGLE_NEWS", "GEMINI", "CHATGPT", "COPILOT", "PERPLEXITY", "GROK" ], "description": "AI provider that handles this task.", "example": "CHATGPT" }, "status": { "type": "string", "enum": [ "QUEUED", "PROCESSING", "COMPLETED", "FAILED" ], "description": "Status of the task right now.", "example": "QUEUED" }, "priority": { "type": "integer", "description": "Priority of the task, from 1 to 10; tasks with higher numbers run first. Default: 1.", "minimum": 1, "maximum": 10, "example": 1 }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation time of the task.", "example": "2026-04-09T15:00:00.000Z" }, "latencyMs": { "type": [ "integer", "null" ], "description": "Time spent processing, in milliseconds, measured from the first pickup until the final outcome. The initial wait in the queue is not counted, but for a retried task it spans all attempts plus the backoff in between. Null for tasks in `QUEUED` or `PROCESSING` state, and for tasks that failed before processing began.", "example": null }, "idempotencyKey": { "type": [ "string", "null" ], "description": "Idempotency key supplied with the request, if any.", "example": "batch-chatgpt-001" } } }, "AsyncTaskCredits": { "type": "object", "required": [ "creditsToCharge", "creditsCharged" ], "description": "Credit details for one async task.", "properties": { "creditsToCharge": { "type": "number", "description": "Credits held back for this task.", "example": 10 }, "creditsCharged": { "type": [ "number", "null" ], "description": "Credits billed for the task; null while it has not finished.", "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": "Complete response payload; included only once the task status is COMPLETED or FAILED." } } }, "AsyncStatusResponse": { "type": "object", "required": [ "queuedTasks", "processingTasks", "priorityBreakdown" ], "properties": { "queuedTasks": { "type": "integer", "description": "Tasks this organization currently has waiting in the queue.", "example": 3 }, "processingTasks": { "type": "integer", "description": "Tasks this organization has in progress right now.", "example": 2 }, "priorityBreakdown": { "type": "array", "description": "Number of queued tasks for each priority level, highest priority first. Priority levels with no queued tasks are left out.", "items": { "type": "object", "required": [ "priority", "count" ], "properties": { "priority": { "type": "integer", "description": "Priority on a scale of 1-10.", "minimum": 1, "maximum": 10, "example": 5 }, "count": { "type": "integer", "description": "Tasks waiting in the queue at this priority.", "example": 2 } } } }, "concurrency": { "type": "object", "nullable": true, "description": "Concurrency in use right now; null when it could not be read.", "properties": { "used": { "type": "integer", "description": "Concurrency slots occupied right now.", "example": 2 }, "max": { "type": "integer", "description": "Highest number of tasks this organization may run concurrently.", "example": 5 } } } } }, "CreditsResponse": { "type": "object", "required": [ "remaining", "perCycle", "cycleResetsAt" ], "properties": { "remaining": { "type": "number", "description": "Your organization's credit balance right now, in credits (fractional, in steps of 0.1).", "example": 48210.5 }, "perCycle": { "type": "integer", "nullable": true, "description": "Credits allotted each billing cycle; null for a free-tier organization without an active subscription.", "example": 1562500 }, "cycleResetsAt": { "type": "string", "format": "date-time", "nullable": true, "description": "End of the current billing period, at which point credits are replenished. Null for organizations on the free tier that have no active subscription.", "example": "2026-08-10T17:35:27.000Z" } } }, "ClearQueueResponse": { "type": "object", "required": [ "success", "cleared" ], "properties": { "success": { "type": "boolean", "description": "Confirms that the queue has been emptied.", "example": true }, "cleared": { "type": "integer", "description": "How many queued tasks were deleted.", "example": 42 } } }, "BatchTaskRequest": { "type": "object", "required": [ "taskType", "payload" ], "properties": { "taskType": { "type": "string", "enum": [ "AIMODE", "GOOGLE", "GOOGLE_NEWS", "GEMINI", "CHATGPT", "COPILOT", "PERPLEXITY", "GROK" ], "description": "AI provider that should handle this task.", "example": "CHATGPT" }, "payload": { "type": "object", "description": "Request body specific to the provider. Needs at least `prompt` (`query` for Google Search).", "example": { "prompt": "How is Northwind Traders reviewed by customers?", "country": "US" } }, "priority": { "type": "integer", "description": "Priority of the task, from 1 to 10; tasks with higher numbers run first. Default: 1.", "minimum": 1, "maximum": 10, "default": 1, "example": 5 }, "idempotencyKey": { "type": "string", "description": "Distinct string that stops the same task from being created twice. No two tasks in your account may share it.", "example": "batch-chatgpt-001" }, "webhook": { "type": "object", "description": "Settings for the webhook that reports a finished task.", "properties": { "url": { "type": "string", "format": "uri", "description": "Endpoint that gets the webhook POST request once the task finishes.", "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": "Set to true for every batch that was processed successfully; individual tasks inside it can still have failed.", "example": true }, "summary": { "type": "object", "required": [ "total", "succeeded", "failed" ], "description": "Totals across the whole batch.", "properties": { "total": { "type": "integer", "description": "How many tasks the batch submission contained.", "example": 3 }, "succeeded": { "type": "integer", "description": "How many tasks were created without error.", "example": 2 }, "failed": { "type": "integer", "description": "Tasks rejected during validation or failed during processing.", "example": 1 } } }, "results": { "type": "array", "description": "Result for each task, listed by index in the same order as the input.", "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": "Signals that the task was created.", "example": true }, "index": { "type": "integer", "description": "Index of this task within the submitted request array, starting at 0.", "example": 0 }, "task": { "allOf": [ { "$ref": "#/components/schemas/AsyncTaskSummary" }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "QUEUED" ], "description": "Status a task starts with when it is created.", "example": "QUEUED" } } } ] }, "credits": { "$ref": "#/components/schemas/AsyncTaskCredits" } } }, "BatchTaskFailureResult": { "type": "object", "required": [ "success", "index", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Signals that the task did not succeed.", "example": false }, "index": { "type": "integer", "description": "Index of this task within the submitted request array, starting at 0.", "example": 2 }, "error": { "type": "object", "required": [ "code", "message", "timestamp" ], "properties": { "code": { "type": "string", "description": "Code naming why the request failed.", "enum": [ "VALIDATION_ERROR", "RESOURCE_ALREADY_EXISTS", "INSUFFICIENT_CREDITS" ], "example": "VALIDATION_ERROR" }, "message": { "type": "string", "description": "Error description meant for people to read.", "example": "Task validation failed" }, "details": { "type": "object", "description": "Extra information about the error, for example which fields failed validation.", "example": { "field": "payload.prompt", "message": "Required" } }, "timestamp": { "type": "string", "format": "date-time", "description": "Time at which the error happened.", "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": "Accepting the batch would overflow the queue" }, "details": { "type": "object", "properties": { "queuedCount": { "type": "integer", "description": "How many tasks are waiting in the queue now.", "example": 99950 }, "batchSize": { "type": "integer", "description": "How many tasks the submitted batch contained.", "example": 100 }, "maxQueueSize": { "type": "integer", "description": "Largest queue size permitted.", "example": 100000 }, "remainingCapacity": { "type": "integer", "description": "Remaining queue capacity, in tasks.", "example": 50 } } }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-04-09T15:00:00.000Z" } } } } }, "ChatGPTMonitorRequest": { "required": [ "prompt", "country" ], "type": "object", "properties": { "prompt": { "description": "Prompt submitted to ChatGPT. ChatGPT takes up to 2,000 characters; a longer prompt is refused with a 400.", "type": "string", "minLength": 1, "maxLength": 10000, "example": "How is Northwind Traders reviewed by customers?" }, "country": { "description": "Code of the country or region used to localize the response", "type": "string", "example": "US" }, "include": { "description": "Flags that add extra output formats to the response (optional)", "type": "object", "default": { "html": false, "markdown": false, "rawResponse": false, "searchQueries": false, "ads": false, "shopping": false }, "properties": { "html": { "description": "Return a link to the complete HTML of the response", "type": "boolean", "default": false, "example": true }, "markdown": { "description": "Add a markdown version of the response to the result", "type": "boolean", "default": false, "example": true }, "rawResponse": { "description": "Return the unprocessed response payload from ChatGPT", "type": "boolean", "default": false, "example": true }, "searchQueries": { "description": "Return the fan-out queries ChatGPT issued while producing the response", "type": "boolean", "default": false, "example": true }, "ads": { "description": "Return ads that ChatGPT shows in its response", "type": "boolean", "default": false, "example": true }, "shopping": { "description": "Return shopping cards plus products shown inline, with their prices and offers. Adds an add-on charge to the base cost, the same one rawResponse adds: one flag or both, it is charged once. searchQueries and ads cost nothing.", "type": "boolean", "default": false, "example": true } }, "required": [], "example": { "html": true, "markdown": true, "rawResponse": true, "searchQueries": true, "ads": true, "shopping": true }, "additionalProperties": false }, "legacy": { "description": "Accepted for compatibility with clients that ask for ChatGPT's older desktop interface. Not served yet: the answer arrives in the same shape whatever its value. Default: false.", "type": "boolean", "default": false, "example": true }, "disableWebSearch": { "description": "Leave ChatGPT's web search unforced. Answerline then returns whatever ChatGPT answers by itself, searching the web only if ChatGPT chooses to, so `result.sources`, `result.citationPills` and `result.searchQueries` are frequently empty. Default is false, meaning every request forces web search.", "type": "boolean", "default": false, "example": true }, "state": { "$ref": "#/components/schemas/StateParameter" } }, "additionalProperties": false }, "GeminiMonitorRequest": { "required": [ "prompt", "country" ], "type": "object", "properties": { "prompt": { "description": "Prompt submitted to Gemini. Gemini takes up to 2,000 characters; a longer prompt is refused with a 400.", "type": "string", "minLength": 1, "maxLength": 10000, "example": "Summarize how solar panels work" }, "country": { "description": "Code of the country or region used to localize the response", "type": "string", "example": "US" }, "include": { "description": "Flags that add extra output formats to the response (optional)", "type": "object", "default": { "markdown": false, "html": false, "rawResponse": false }, "properties": { "markdown": { "description": "Add a markdown version of the response to the result", "type": "boolean", "default": false, "example": true }, "html": { "description": "Not available for Gemini: its answer is read without a page to snapshot, so `true` is refused with a validation error.", "type": "boolean", "default": false, "example": false }, "rawResponse": { "description": "Return the unprocessed stream of 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": "Data from Gemini's reply", "type": "object", "properties": { "text": { "type": "string", "description": "Text of Gemini's reply", "example": "Quantum computing applies quantum mechanics to..." }, "markdown": { "type": "string", "description": "Gemini's reply as Markdown", "example": "**Machine learning** is a branch of artificial intelligence..." }, "html": { "type": "string", "description": "Link to the response's complete HTML; it stops working 24 hours after it is generated.", "example": "https://files.answerline.dev/html/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/1/page-1.html" }, "sources": { "type": "array", "description": "Sources that Gemini cited", "items": { "type": "object", "properties": { "position": { "type": "integer", "description": "Where the source sits in the list", "example": 1 }, "label": { "type": "string", "description": "Title or label of the source", "example": "Wikipedia - Machine Learning" }, "url": { "type": "string", "description": "Link to the source", "example": "https://en.wikipedia.org/wiki/Quantum_computing" }, "description": { "type": "string", "description": "Snippet or description text for the source", "example": "Quantum computing uses qubits to process information..." } } } }, "citationPills": { "type": "array", "description": "Citation pills that appear inline in the Gemini answer. Every element pairs one chip with one source: a chip backed by N sources (Gemini's equivalent of `+N`, or a section-summary chip) yields N elements with the same `citationPillId`, each holding that source's own `label`, `url` and `domain`. Grouping by `citationPillId` rebuilds the pills. `label` is always sent; it may be an empty string if the rail gives that source no title. Not present in `result` if the answer has no pills.", "items": { "type": "object", "required": [ "label", "citationPillId", "url", "domain", "position" ], "properties": { "label": { "type": "string", "description": "Title of this individual source as shown in the sources rail (e.g. `\"Quantum computing — Wikipedia\"`). The field is always sent, though it can be an empty string if the rail gives no title for it — then identify the source by `domain` / `url`.", "example": "Photosynthesis — Wikipedia" }, "citationPillId": { "type": "integer", "description": "One-based number common to every entry that comes from one chip. Grouping on `citationPillId` rebuilds the chip as displayed; each entry's `label` is specific to its source, so it varies inside a chip.", "example": 1 }, "url": { "type": "string", "description": "Link straight to the cited source.", "example": "https://en.wikipedia.org/wiki/Quantum_computing" }, "domain": { "type": "string", "description": "Hostname taken from `url`, useful for grouping and display.", "example": "en.wikipedia.org" }, "description": { "type": "string", "description": "Source snippet shown in the sources rail, if Gemini supplies one; otherwise omitted.", "example": "Quantum computing uses qubits to process information..." }, "position": { "type": "integer", "description": "Index of this source within the sibling `result.sources` array, starting at 1.", "example": 1 } } }, "example": [ { "label": "Photosynthesis — Wikipedia", "citationPillId": 1, "url": "https://en.wikipedia.org/wiki/Quantum_computing", "domain": "en.wikipedia.org", "description": "Quantum computing uses qubits to process information...", "position": 1 }, { "label": "IBM Quantum", "citationPillId": 1, "url": "https://www.ibm.com/quantum", "domain": "ibm.com", "position": 3 } ] }, "places": { "type": "array", "description": "Place cards included in lodging and local answers", "items": { "type": "object", "required": [ "index", "title", "link" ], "properties": { "index": { "type": "integer", "description": "Index of the place's position in the results", "example": 0 }, "title": { "type": "string", "description": "Place name", "example": "Sofitel Sydney Darling Harbour" }, "link": { "type": "string", "format": "uri", "description": "The place's URL on Google", "example": "https://www.google.com/travel/search?q=Pullman+Quay+Grand+Sydney+Harbour" }, "thumbnail": { "type": "string", "format": "uri", "description": "URL of a photo of the place", "example": "https://lh3.googleusercontent.com/gps-cs-s/example" }, "rating": { "type": "number", "description": "Rating in stars (0-5)", "example": 4.4 }, "reviews": { "type": "integer", "description": "Review count", "example": 1307 }, "type": { "type": "string", "description": "Category or type of the place", "example": "5-star hotel" }, "description": { "type": "string", "description": "Brief summary of the place", "example": "Boutique riverside hotel with elegant rooms, a rooftop terrace, a spa & an all-day café." }, "price": { "type": "string", "description": "Per-night price exactly as Gemini shows it", "example": "$565" } } } }, "rawResponse": { "type": "array", "description": "Unprocessed stream from the upstream provider, recorded while the request ran. Every item is a single chunk of the engine's raw response. The format varies by engine, is not documented and can change at any time without warning; use it to debug or to read data not yet exposed by the structured fields above.", "items": {} }, "shoppingCards": { "type": "array", "description": "Product cards Gemini shows beside a shopping-related answer, in display order. Absent when the answer has none.", "items": { "type": "object", "required": [ "position", "title", "productLink", "productId" ], "properties": { "position": { "type": "integer", "description": "1-based order of the card among the answer's products.", "example": 1 }, "title": { "type": "string", "description": "Product name on the card.", "example": "Brooks Ghost 16" }, "productLink": { "type": "string", "description": "Google Shopping link for the product.", "example": "https://google.com/search?q=Brooks+Ghost+16&prds=productid%3A123", "format": "uri" }, "productId": { "type": "string", "description": "Google's identifier for the product.", "example": "16919532047675658099" }, "price": { "type": "object", "description": "Current price on the card.", "properties": { "value": { "type": "number", "description": "The amount as a number.", "example": 329.99 }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "USD" }, "raw": { "type": "string", "description": "The price exactly as displayed.", "example": "$329.99" } } }, "oldPrice": { "type": "object", "description": "Previous price, shown when the product is discounted.", "properties": { "value": { "type": "number", "description": "The amount as a number.", "example": 329.99 }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "USD" }, "raw": { "type": "string", "description": "The price exactly as displayed.", "example": "$329.99" } } }, "store": { "type": "string", "description": "Store offering the shown price.", "example": "Runner's Depot" }, "storeLink": { "type": "string", "description": "Link to the offer at that store, when the card has one.", "format": "uri" }, "storeCount": { "type": "integer", "description": "How many stores sell the product.", "example": 4 }, "shipping": { "type": "string", "description": "Shipping note as displayed, when present." }, "deliveryTime": { "type": "string", "description": "Delivery estimate as displayed, when present." }, "rating": { "type": "number", "description": "Average review score.", "example": 4.4 }, "reviews": { "type": "integer", "description": "Number of reviews behind the rating.", "example": 1261 }, "brand": { "type": "string", "description": "Manufacturer or brand.", "example": "Brooks" }, "description": { "type": "string", "description": "Short product description from the card." }, "thumbnail": { "type": "string", "description": "URL of the main product image.", "format": "uri" }, "images": { "type": "array", "description": "URLs of the product images, main image first.", "items": { "type": "string", "format": "uri" } }, "catalogId": { "type": "string", "description": "Google Shopping catalog identifier.", "example": "14325977521193745857" }, "gpcId": { "type": "string", "description": "Google product cluster identifier.", "example": "11523404812175301769" } } } } } } } }, "GrokMonitorRequest": { "required": [ "prompt", "country" ], "type": "object", "properties": { "prompt": { "description": "Prompt submitted to Grok", "type": "string", "minLength": 1, "maxLength": 10000, "example": "Which laptop should I buy for software development?" }, "country": { "description": "Code of the country or region used to localize the response", "type": "string", "example": "US" }, "include": { "description": "Flags that add extra output formats to the response (optional)", "type": "object", "properties": { "markdown": { "description": "Add a markdown version of the response to the result", "type": "boolean", "default": false, "example": true }, "html": { "description": "Add an HTML version of the response to the result", "type": "boolean", "default": false, "example": true }, "rawResponse": { "description": "Return the unprocessed stream of 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": "Response data from Grok", "type": "object", "properties": { "text": { "type": "string", "description": "Text of the answer from Grok", "example": "Drawing on a live web search, these monitors stand out for programming work..." }, "html": { "type": "string", "format": "uri", "description": "Link to the response's complete HTML.", "example": "https://files.answerline.dev/html/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/1/page-1.html" }, "sources": { "type": "array", "description": "Sources the response cites, with extra metadata", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "Where the source sits in the response, as an index", "example": 1 }, "url": { "type": "string", "description": "Link to the source", "example": "https://example.com/article" }, "label": { "type": "string", "description": "Label shown for this source", "example": "Tech Source" }, "description": { "type": "string", "description": "Text describing what the source contains", "example": "Complete tablet buying guide for students" }, "preview": { "type": "string", "description": "Short excerpt previewing the source", "example": "For development work, look first at memory, CPU speed, and SSD capacity..." }, "searchEngineText": { "type": "string", "description": "Display text shown by the search engine", "example": "Top Developer Monitors 2025" }, "siteName": { "type": "string", "description": "Website name", "example": "Tech Reviews" }, "metadataTitle": { "type": "string", "description": "Title from the source's metadata", "example": "Choosing a Laptop for Programming" }, "creator": { "type": "string", "description": "Content creator/author", "example": "John Doe" }, "image": { "type": "string", "format": "uri", "description": "URL of the source's image", "example": "https://example.com/preview.jpg" }, "favicon": { "type": "string", "format": "uri", "description": "URL of the site's favicon", "example": "https://example.com/favicon.ico" } } }, "example": [ { "position": 1, "url": "https://techcrunch.com/programming-laptops", "label": "TechCrunch", "description": "Top monitors for coding and development", "preview": "A good coding laptop needs plenty of memory and a fast multi-core CPU...", "searchEngineText": "Best Coding Laptops of 2025", "siteName": "TechCrunch", "metadataTitle": "The Complete Coding Laptop Handbook", "creator": "Tech Team", "image": "https://techcrunch.com/preview.jpg", "favicon": "https://techcrunch.com/favicon.ico" } ] }, "searchQueries": { "type": "array", "items": { "type": "string" }, "description": "Searches Grok ran to collect material for the response", "example": [ "coding laptop recommendations 2026", "leading laptops for developers 2026" ] }, "model": { "type": "string", "nullable": true, "description": "Identifier of the model that produced the response", "example": "grok-4-auto" }, "markdown": { "type": "string", "description": "Grok's answer rendered as Markdown (returned if include.markdown is set to true)", "example": "Drawing on a live web search, these monitors stand out for programming work..." }, "rawResponse": { "type": "array", "description": "Unprocessed stream from the upstream provider, recorded while the request ran. Every item is a single chunk of the engine's raw response. The format varies by engine, is not documented and can change at any time without warning; use it to debug or to read data not yet exposed by the structured fields above.", "items": {} } } } } }, "ChatGPTMonitorResponse": { "required": [ "success", "result" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "description": "Data from ChatGPT's reply", "type": "object", "properties": { "text": { "type": "string", "description": "Text of ChatGPT's reply", "example": "The Hubble Space Telescope is an observatory that has been in orbit since 1990. Here's a short summary:\n\n🔭 Hubble at a Glance\nHubble circles Earth about 540 km up and was built jointly by NASA and ESA; its images have shaped modern astronomy, from galaxy formation to the expansion rate of the universe." }, "sources": { "type": "array", "description": "Sources the response cites; an empty array if there are none.", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "Where the source sits in the response, as an index", "example": 1 }, "url": { "type": "string", "description": "Link to the source", "example": "https://www.rippling.com/blog/ai-recruiting?utm_source=chatgpt.com" }, "label": { "type": "string", "description": "Title of the source article", "example": "9 Leading Talent Sourcing Platforms for Recruiters in 2025" }, "description": { "type": "string", "description": "Excerpt or short summary taken from the source", "example": "Compare leading applicant tracking systems that help small teams screen candidates faster..." }, "footnote": { "type": "boolean", "description": "True if the source is shown as a footnote, i.e. in a later list inside the sources modal", "example": false }, "datePublished": { "type": "string", "description": "Date the source was published. If the source has no such date, the field is left out entirely rather than set to `null`.", "example": "May 22, 2025" } } }, "example": [ { "position": 1, "url": "https://www.rippling.com/blog/ai-recruiting?utm_source=chatgpt.com", "label": "9 Leading Talent Sourcing Platforms for Recruiters in 2025", "description": "Compare leading applicant tracking systems that help small teams screen candidates faster...", "footnote": false, "datePublished": "May 22, 2025" }, { "position": 2, "url": "https://www.index.dev/blog/ai-recruiting-software-hiring-managers?utm_source=chatgpt.com", "label": "8 Top Interview Scheduling Tools for Recruiting Teams in 2025", "description": "An in-depth comparison of applicant tracking systems that recruiting teams can adopt today...", "footnote": false, "datePublished": "April 10, 2025" }, { "position": 3, "url": "https://www.selectsoftwarereviews.com/buyer-guide/ai-recruiting?utm_source=chatgpt.com", "label": "15 Top Applicant Tracking Systems for 2025: Features and Pricing Compared", "description": "Hands-on comparisons and plan prices for popular applicant tracking software...", "footnote": true } ] }, "html": { "type": "string", "format": "uri", "description": "Link to the response's complete HTML (present when include.html is true)", "example": "https://files.answerline.dev/html/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/1/page-1.html" }, "markdown": { "type": "string", "description": "ChatGPT's reply as Markdown; returned only if include.markdown is true", "example": "The Hubble Space Telescope is an observatory that has been in orbit since 1990. Here's a short summary:\n\n🔭 Hubble at a Glance\nHubble circles Earth about 540 km up and was built jointly by NASA and ESA; its images have shaped modern astronomy, from galaxy formation to the expansion rate of the universe." }, "rawResponse": { "type": "array", "description": "Raw ChatGPT response chunks exactly as received, without processing (returned only if include.rawResponse is true)", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Identifier of the event's type" }, "token": { "type": "string", "description": "Token for picking the ChatGPT conversation back up" }, "conversation_id": { "type": "string", "description": "Identifier of the ChatGPT conversation" }, "message": { "type": "object", "description": "Payload of the event that describes the assistant's message", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "model": { "type": "string" } } }, "delta": { "type": "object", "description": "Delta payload streamed by ChatGPT", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "text_delta": { "type": "string" } } } } } }, "reason": { "type": "string", "description": "Reason ChatGPT ended the stream" } } }, "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": "Northwind Traders appears in several product reviews..." } ] } }, { "type": "message_stop", "reason": "end_turn" } ] }, "searchQueries": { "type": "array", "description": "The fan-out queries ChatGPT issued while producing the response (present when include.searchQueries is true)", "items": { "type": "string" }, "example": [ "What is the Hubble Space Telescope?", "Globex Inc. company profile", "Globex Corporation product catalog" ] }, "model": { "type": "string", "nullable": true, "description": "ChatGPT model that produced the answer. Empty when the response came through OpenAI's mobile-web format.", "example": "gpt-5-5" }, "shoppingCards": { "type": "array", "description": "Shopping/product cards parsed from the response. When `include.shopping` is `false` or not set, `result` does not contain this field at all, so treat it as optional instead of relying on an empty array.", "items": { "type": "object", "properties": { "tags": { "type": "array", "description": "Tags naming the shopping card's categories", "items": { "type": "string" }, "example": [ "cushioned everyday road shoe", "lightweight neutral trainer" ] }, "products": { "type": "array", "description": "List of product details", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Product name", "example": "Puma Carina Street" }, "position": { "type": "integer", "description": "Rank starting at 1, counted over every product in every shopping card of the response (one continuous sequence that does not restart for each card).", "example": 1 }, "url": { "type": "string", "description": "Product page link carrying 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": "Style or category tag for the product", "example": "cushioned everyday road shoe" }, "merchant": { "type": "string", "description": "Merchant information", "example": "Brooks + others" }, "image_urls": { "type": "array", "description": "URLs of the product's images", "items": { "type": "string" }, "example": [ "https://images.openai.com/static-rsc-1/example.jpg" ] }, "rating": { "type": "number", "description": "Rating of the product, on a 0-5 scale", "example": 4.7 }, "num_reviews": { "type": "integer", "description": "Review count", "example": 10394 }, "id": { "type": "string", "description": "Identifier unique to the product", "example": "3250714974047560249" }, "offers": { "type": "array", "description": "Offers for the product from various merchants", "items": { "type": "object", "properties": { "merchant_name": { "type": "string", "description": "Merchant name", "example": "adidas" }, "product_name": { "type": "string", "description": "Product title as the merchant lists it", "example": "Brooks Ghost 16 Women's" }, "url": { "type": "string", "description": "Offer link carrying 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": "Availability and delivery details", "example": "Available online, ships in 2-4 days for $5.95" }, "available": { "type": "boolean", "description": "Stock/availability status of the offer", "example": true }, "checkoutable": { "type": "boolean", "description": "True if the offer supports direct checkout", "example": false }, "price_details": { "type": "object", "description": "Itemized breakdown of the price", "properties": { "base": { "type": "string", "description": "Base price of the product", "example": "$57.00" }, "total": { "type": "string", "description": "Overall price with all extra charges added", "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": "Details about where the rating comes from", "properties": { "title": { "type": "string", "description": "Source title", "example": "Brooks Ghost 16 Women's" }, "url": { "type": "string", "description": "Source URL", "example": "https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html" }, "supporting_websites": { "type": "array", "description": "Websites cited in support", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Website title", "example": "Brooks Ghost 16 Women's" }, "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": [ "cushioned everyday road shoe", "lightweight neutral trainer" ], "products": [ { "title": "Puma Carina Street", "url": "https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html?utm_source=chatgpt.com", "price": "$57.00", "featured_tag": "cushioned everyday road shoe", "merchant": "Brooks + 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": "Brooks Ghost 16 Women's", "url": "https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html?utm_source=chatgpt.com", "price": "$57.00", "details": "Available online, ships in 2-4 days for $5.95", "available": true, "checkoutable": false, "price_details": { "base": "$57.00", "total": "$57.00" }, "tag": { "text": "Best price" } } ], "rating_grouped_citation": { "title": "Brooks Ghost 16 Women's", "url": "https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html", "supporting_websites": [ { "title": "Brooks Ghost 16 Women's", "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": "Products shown inline, with their prices and offers. When `include.shopping` is `false` or not set, `result` does not contain this field at all, so treat it as optional instead of relying on an empty array.", "items": { "$ref": "#/components/schemas/InlineProduct" } }, "entities": { "type": "array", "description": "Entities parsed from the response (if any)", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Identifier of the entity's type", "example": "product" }, "name": { "type": "string", "description": "Entity name", "example": "Nike Court Vision Low" } }, "required": [ "type", "name" ] }, "example": [ { "type": "product", "name": "Nike Court Vision Low" }, { "type": "product", "name": "Nike Air Force 1 '07" }, { "type": "product", "name": "New Balance 550 Leather" } ] }, "map": { "type": "array", "description": "Map entries for businesses or places parsed from the response (if any). Entries originate from the enrichment providers ChatGPT uses (Yelp, Google Business), with field names in camelCase. Only the fields filled in most often appear here; see the [API reference](/docs/reference) for every field.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the business (a Yelp ID or a Google Place ID)", "example": "rVKID2OBQMyVpraqSjz9sg" }, "provider": { "type": "string", "description": "Source of the data: \"yelp\", \"b1\" or \"b3\" (Google), or \"yelp-feed\"", "example": "yelp" }, "name": { "type": "string", "description": "Business name", "example": "Harbor Lane Roasters" }, "position": { "type": "integer", "description": "Rank/position in the results (set by the parser)", "example": 1 }, "address": { "type": "string", "description": "Complete street address", "example": "210 Valencia St, San Francisco, CA 94110" }, "latitude": { "type": "number", "description": "Latitude from GPS", "example": 37.7811 }, "longitude": { "type": "number", "description": "Longitude from GPS", "example": -122.4076 }, "categories": { "type": "array", "description": "Business categories", "items": { "type": "string" }, "example": [ "Coffee shop" ] }, "rating": { "type": "number", "description": "Rating of the business (scale of 0-5)", "example": 4.5 }, "reviewCount": { "type": "integer", "description": "Review count", "example": 1234 }, "description": { "type": "string", "description": "Business description", "example": "Family-run bakery famous for its slow-fermented sourdough loaves" }, "phone": { "type": "string", "description": "Phone number for contact", "example": "+1-415-555-0123" }, "websiteUrl": { "type": "string", "format": "uri", "description": "URL of the business's website", "example": "https://bluebottlecoffee.com" } } }, "example": [ { "id": "rVKID2OBQMyVpraqSjz9sg", "provider": "yelp", "name": "Harbor Lane Roasters", "position": 1, "address": "210 Valencia St, San Francisco, CA 94110", "latitude": 37.7811, "longitude": -122.4076, "categories": [ "Coffee shop" ], "rating": 4.5, "reviewCount": 1234, "description": "Family-run bakery famous for its slow-fermented sourdough loaves", "phone": "+1-415-555-0123", "websiteUrl": "https://bluebottlecoffee.com" } ] }, "citationPills": { "type": "array", "description": "Inline citation pills parsed from the response (if any), i.e. citations shown in the body of the text. Every entry represents a single (pill, source) pair; grouping on `citationPillId` rebuilds each pill.", "items": { "type": "object", "required": [ "label", "citationPillId", "url", "domain", "type", "position" ], "properties": { "url": { "type": "string", "format": "uri", "description": "URL the citation points to", "example": "https://example.com/article" }, "label": { "type": "string", "description": "Title of this individual cited source. Never missing, but can be an empty string if the citation event carries no title — then identify the source by `domain` / `url`.", "example": "Sample Guide Headline" }, "description": { "type": "string", "description": "Text describing what the citation contains; left out if the citation event has no snippet, as with grouped-webpage cards that show only a title.", "example": "Longer explanation of what the cited material covers" }, "domain": { "type": "string", "description": "Domain the cited source belongs to", "example": "example.com" }, "datePublished": { "type": "string", "description": "Publication date of the source as an ISO 8601 date string. Left out when the citation event has no publication date.", "example": "2025-01-01" }, "citationPillId": { "type": "integer", "description": "Zero-based ID common to every entry that comes from one chip; grouping on `citationPillId` rebuilds each pill. **Note:** ChatGPT numbers these from 0 for legacy reasons, whereas every other provider (Google AIO, AI Mode, Copilot, Perplexity, Gemini) numbers `citationPillId` from 1.", "example": 0 }, "type": { "type": "string", "enum": [ "searchResult", "groupedWebpage" ], "description": "Indicates which kind of citation event this came from: `searchResult` means an inline search citation, `groupedWebpage` a grouped-webpage card.", "example": "searchResult" }, "position": { "type": "integer", "description": "Index of this source within the sibling `result.sources` array, starting at 1.", "example": 1 } } }, "example": [ { "url": "https://example.com/article", "label": "Sample Guide Headline", "description": "Longer explanation of what the cited material covers", "domain": "example.com", "datePublished": "2025-01-01", "citationPillId": 0, "type": "searchResult", "position": 1 } ] }, "ads": { "type": "array", "description": "Ads delivered with the ChatGPT response (present when include.ads is true). Several candidate ads are sent by OpenAI, yet the interface displays one at most; check `rendered` to see which ones were really displayed.", "items": { "type": "object", "properties": { "brand": { "type": "object", "description": "Details about the advertiser's brand", "properties": { "name": { "type": "string", "description": "Name of the advertiser's brand", "example": "Acme Shoes" }, "url": { "type": "string", "format": "uri", "description": "URL of the advertiser's brand", "example": "https://www.acmeshoes.com?utm_source=chatgpt.com" }, "favicon": { "type": "string", "format": "uri", "description": "Favicon URL of the advertiser's brand", "example": "https://images.openai.com/favicon.ico" } }, "required": [ "name", "url" ] }, "cards": { "type": "array", "description": "Carousel cards contained in the ad", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Card title", "example": "Lightweight Trail Sneakers" }, "body": { "type": "string", "description": "Text describing the card", "example": "Responsive trainers with a soft foam midsole for daily miles" }, "url": { "type": "string", "format": "uri", "description": "URL the card links to", "example": "https://www.acmeshoes.com/running?utm_source=chatgpt.com" }, "image": { "type": "string", "format": "uri", "description": "URL of the card's image", "example": "https://images.openai.com/product.jpg" } }, "required": [ "title", "body", "url" ] } }, "visibility": { "type": "string", "description": "Whether OpenAI served the ad. `allowed`: the ad qualified to be shown; `hidden`: OpenAI suppressed it (an integrity check, for instance).", "example": "allowed" }, "adsResponseIndex": { "type": "integer", "description": "Position of the ad's slot in the ad response OpenAI served. It reflects the order ads were served in, not what was displayed; use `rendered` for real exposure.", "example": 0 }, "rendered": { "type": "boolean", "description": "Indicates if the ad was rendered on screen as a card within the response. ChatGPT returns multiple candidate ads, yet the UI displays one at most; an ad with `rendered: false` was delivered but never shown.", "example": true } }, "required": [ "brand", "cards", "visibility", "adsResponseIndex", "rendered" ] }, "example": [ { "brand": { "name": "Acme Shoes", "url": "https://www.acmeshoes.com?utm_source=chatgpt.com", "favicon": "https://images.openai.com/favicon.ico" }, "cards": [ { "title": "Lightweight Trail Sneakers", "body": "Responsive trainers with a soft foam midsole for daily miles", "url": "https://www.acmeshoes.com/running?utm_source=chatgpt.com", "image": "https://images.openai.com/product.jpg" }, { "title": "Waterproof Hiking Boots", "body": "Rugged trail shoes with deep lugs for loose terrain", "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": "Code that identifies the error", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "description": "Error description meant for people to read", "example": "Request validation failed" }, "details": { "type": "object", "description": "Extra information that depends on the context" }, "timestamp": { "type": "string", "format": "date-time", "description": "Time the error happened, as an ISO 8601 timestamp", "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 must not 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": "API key is missing or not valid" }, "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": "Upstream provider failed: OpenAI" }, "details": { "type": "object", "properties": { "service": { "type": "string", "example": "OpenAI" } } }, "timestamp": { "type": "string", "format": "date-time", "example": "2025-01-15T12:00:00.000Z" } } } } }, "GoogleMonitorRequest": { "anyOf": [ { "required": [ "query", "country" ] }, { "required": [ "query", "gl" ] }, { "required": [ "url" ] } ], "type": "object", "properties": { "query": { "description": "Query to run on Google. Mandatory when 'url' is not given; send one or the other, never both.", "type": "string", "minLength": 1, "maxLength": 10000, "example": "laptops for software developers" }, "url": { "description": "A full URL of a Google web search, executed as-is in place of a request assembled from 'query' plus the targeting fields. It has to be absolute and http(s), hosted on one of Google's web search domains (google.com, google.co.uk, www.google.de, ...), with '/search' as its path and a 'q' that is not empty. Cannot be combined with 'query', 'location', 'uule' or 'pages', since the URL already determines them. It may carry only these query parameters: 'q', 'gl', 'num' (treated as result depth), 'hl' and 'uule'; a URL with any other (such as 'start', 'tbs' or 'safe') is refused with a 400. A URL containing 'tbm' is refused: it points at a Google vertical that has a separate endpoint and price (for tbm=nws, call POST /v1/monitor/google/news).", "type": "string", "format": "uri", "example": "https://www.google.com/search?q=best+laptops+for+programming&hl=en&gl=us&num=30" }, "country": { "description": "Country for localized search results, as an ISO 3166-1 alpha-2 code. Mandatory in the standard request form. If you send 'url' instead, the country is taken from the URL's 'gl' parameter — set it yourself to override that value, or when the URL carries no 'gl'.", "type": "string", "example": "US" }, "gl": { "$ref": "#/components/schemas/GlParameter" }, "hl": { "$ref": "#/components/schemas/HlParameter" }, "location": { "description": "Location name in Google's canonical comma-separated form 'City,Region,Country' (roughly 100,000 accepted locations are listed at https://developers.google.com/google-ads/api/reference/data/geotargets). Combine with 'country' to target a specific city. Cannot be sent together with 'uule' — choose one of the two. Not allowed when 'url' is set.", "type": "string", "example": "Chicago,Illinois,United States" }, "uule": { "description": "A ready-made Google UULE string for exact geo-targeting, in the location-name form (starting w+CAIQICI); the coordinate form (a+) is refused with a 400. Supply it when you already have an encoded UULE rather than a location name. Cannot be sent together with 'location' — pass only one of the two. Not allowed together with 'url'; in that case add 'uule' to the URL's query string.", "type": "string", "example": "w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5" }, "device": { "description": "Device to run the search on. 'desktop' gives the desktop SERP, while 'ios' (Safari on an iPhone), 'android' (Chrome on an Android phone) and 'mobile' (same as 'android') each give the mobile SERP.", "type": "string", "enum": [ "desktop", "mobile", "ios", "android" ], "default": "desktop", "example": "desktop" }, "pages": { "description": "How many pages of search results to retrieve (1-10). Not allowed together with 'url' — when 'url' is given, depth is taken from the URL's 'num' parameter (rounded up to full 10-result pages, at most 10 pages).", "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "example": 3 }, "include": { "description": "Flags that add extra data to the response (optional)", "type": "object", "properties": { "html": { "description": "Return the unprocessed HTML page from Google Search", "type": "boolean", "default": false, "example": false }, "aioverview": { "description": "Add Google's AI Overview to the response", "type": "object", "properties": { "markdown": { "description": "Return the AI Overview in markdown form", "type": "boolean", "default": false, "example": true } }, "default": { "markdown": false }, "additionalProperties": false }, "paaAioverview": { "description": "Fill People Also Ask items of the AI Overview type with markdown content and their sources. Charges nothing past the AI Overview add-on; every hydrated item needs one more fetch (usually 1-2 on a page), which makes responses slower.", "type": "boolean", "default": false, "example": true }, "googleGoto": { "description": "Has had no effect since 8th September 2026. Each redirect link is now always returned as `redirectLink` next to its target, so you get both without setting this flag. Requests that still include it are handled as though it were omitted.", "type": "boolean", "default": false, "example": true, "deprecated": true } }, "default": { "html": false }, "additionalProperties": false } }, "additionalProperties": false }, "GoogleMonitorResponse": { "required": [ "success", "result" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "description": "Results returned by Google Search", "type": "object", "properties": { "organicResults": { "type": "array", "description": "Google organic results", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "Rank among search results (1-indexed)", "example": 1 }, "title": { "type": "string", "description": "Search result title", "example": "The Best Monitors for Developers in 2024" }, "link": { "type": "string", "description": "Link to the search result", "example": "https://example.com/best-programming-laptops" }, "displayedLink": { "type": "string", "description": "URL in the form shown on the results page", "example": "https://example.com" }, "snippet": { "type": "string", "description": "Short text summarizing what the page contains", "example": "Shopping for a tablet to draw on? We compared and ranked the leading models..." }, "date": { "type": "string", "description": "Date of publication, if known", "example": "2 days ago" }, "page": { "type": "number", "description": "Results page this item was found on (1-indexed)", "example": 1 }, "sitelinks": { "type": "object", "description": "Sitelinks shown beneath 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" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } } } }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "peopleAlsoAsk": { "type": "array", "description": "Google's \"People also ask\" questions", "items": { "type": "object", "properties": { "question": { "type": "string", "description": "Text of the question", "example": "How much RAM does a coding laptop really need?" }, "type": { "type": "string", "enum": [ "AIOVERVIEW", "LINK", "UNKNOWN" ], "description": "Kind of question result" }, "snippet": { "type": "string", "description": "Short excerpt of the answer (LINK type)", "example": "The main factors to weigh are screen size, battery life, and stylus support..." }, "title": { "type": "string", "description": "Title of the result (only for type LINK)", "example": "Key hardware specs for coding laptops" }, "link": { "type": "string", "description": "Result link URL (only for type LINK)", "example": "https://example.com/laptop-specs" }, "markdown": { "type": "string", "description": "Markdown of the AI Overview (AIOVERVIEW type only, when include.paaAioverview is true)" }, "sources": { "type": "array", "description": "Sources the answer cites; present for the AIOVERVIEW type if include.paaAioverview is true", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Source title", "example": "Coding Notebook Buyer's Notes" }, "url": { "type": "string", "description": "Link to the source", "example": "https://example.com/guide" }, "description": { "type": "string", "description": "Text describing the source" }, "position": { "type": "number", "description": "Rank of the source (1-indexed)" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "peopleAreSaying": { "type": "array", "description": "Items from the Google results module titled \"What people are saying\" or \"Trending posts and discussions\". When the page has no such module, `result` leaves this field out instead of returning an empty array, so treat it as optional.", "items": { "type": "object", "required": [ "position", "title", "link", "date" ], "properties": { "position": { "type": "number", "description": "Rank inside the module (1-indexed)", "example": 1 }, "title": { "type": "string", "description": "Title of the card as it appears on the results page", "example": "Top trail shoes of 2026 - runner reviews" }, "link": { "type": "string", "description": "URL the card links to, frequently a thread on Reddit, Quora or another community forum", "example": "https://www.reddit.com/r/running/comments/example/" }, "date": { "type": "string", "description": "Relative time exactly as Google printed it (for example \"3 hours ago\", \"1 month ago\"). Unstructured text; not converted into a timestamp.", "example": "5 days ago" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "localResults": { "type": "array", "description": "Businesses in Google's local pack (the map-based \"3-pack\" of nearby businesses shown for local-intent searches, e.g. \"best ramen in seattle\"). If the SERP has no local pack, `result` does not contain this field at all, so treat it as optional instead of relying on an empty array. Applies to desktop only; neither the mobile layout nor the hotels/travel pack (a separate panel) is returned.", "items": { "type": "object", "required": [ "position", "title" ], "properties": { "position": { "type": "number", "description": "Rank inside the pack (1-indexed)", "example": 1 }, "title": { "type": "string", "description": "Name of the business as the SERP shows it", "example": "Corner Slice Midtown" }, "placeId": { "type": "string", "description": "The place's entity identifier in Google", "example": "/g/11bw4ws2mt" }, "rating": { "type": "number", "description": "Mean star rating (0–5)", "example": 4.4 }, "reviews": { "type": "string", "description": "Number of reviews exactly as Google shows it (e.g. \"26K\"). Arbitrary text, not converted to a number.", "example": "26K" }, "price": { "type": "string", "description": "Price range as Google shows it (e.g. \"$20–30\"). The currency symbol follows the locale.", "example": "$10–20" }, "type": { "type": "string", "description": "Category of the business (for example \"Bakery\", \"Electrician\")", "example": "Pizza" }, "yearsInBusiness": { "type": "string", "description": "Badge showing how long the business has operated, if displayed (common in service-type packs)", "example": "45+ years in business" }, "address": { "type": "string", "description": "Street address or locality exactly as the results page shows it", "example": "1435 Broadway" }, "phone": { "type": "string", "description": "Phone number in local format, if shown", "example": "(212) 555-0100" }, "hours": { "type": "string", "description": "Opening hours exactly as shown (e.g. \"Open · Closes 10 PM\", \"Open 24 hours\")", "example": "Open · Closes 10 PM" }, "description": { "type": "string", "description": "Snippet shown at the end: either a quoted review or a line listing service options", "example": "\"Friendly staff, a cozy patio, and the best tacos in town.\"" }, "links": { "type": "object", "description": "Action links displayed for the place. They usually appear in packs of service businesses (plumbers, salons, …) and are missing from restaurant packs, where each place is just a plain button. A key is included only if Google showed the corresponding button.", "properties": { "website": { "type": "string", "description": "Website address of the business itself", "example": "https://villageplumbing.com/" }, "directions": { "type": "string", "description": "Full URL for directions in Google Maps", "example": "https://www.google.com/maps/dir//Village+Plumbing,+Air+%26+Electric" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } } } }, "localResultsMoreLink": { "type": "string", "description": "Full URL of the \"More places\" / \"More businesses\" control shown under the local pack; it opens Google's larger Local Finder for this query. Present only together with `localResults`, and only if the SERP shows that control.", "example": "https://www.google.com/search?q=italian+restaurants+in+toronto&udm=1" }, "relatedSearches": { "type": "array", "description": "Suggested related searches", "items": { "type": "object", "properties": { "query": { "type": "string", "description": "A related search query", "example": "cheap laptop for software development" }, "link": { "type": "string", "description": "URL of the Google results page for this related search", "example": "https://google.com/search?q=best+budget+laptop+for+coding" } } } }, "ads": { "type": "array", "description": "Sponsored results in Google search: text ads (`type: RESULT`), plus sponsored shopping cards (`type: SHOPPING_CARD`) drawn from the carousels at the top of the page and in the right-hand column.", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "Rank inside the ad block (1-indexed)", "example": 1 }, "blockPosition": { "type": "string", "enum": [ "top", "bottom", "middle", "rhs" ], "description": "Placement of the ad on the results page. `top`/`bottom` denote text-ad blocks, `middle` means direct or in-content ads, and `rhs` means the sponsored-products carousel on the right-hand side.", "example": "top" }, "type": { "type": "string", "enum": [ "RESULT", "SHOPPING_CARD" ], "description": "Tells plain text ads (`RESULT`) apart from sponsored shopping-style cards (`SHOPPING_CARD`). Shopping cards come from the PLA carousel on the right-hand side, the PLA carousel at the top of the page, and the sponsored shopping-card carousels at the top of the page (vehicles, products, hotels, …).", "example": "RESULT" }, "title": { "type": "string", "description": "Ad title", "example": "Coding Monitors on Sale - Buy Today" }, "url": { "type": "string", "format": "uri", "description": "URL the ad leads to. On `type: SHOPPING_CARD` items it is a URL that Google redirects through `aclk?`.", "example": "https://example.com/programming-laptops" }, "page": { "type": "number", "description": "Results page on which the ad appeared", "example": 1 }, "displayedUrl": { "type": "string", "description": "URL in the form shown in the ad", "example": "example.com/laptops" }, "domain": { "type": "string", "description": "Advertiser's domain name", "example": "example.com" }, "description": { "type": "string", "description": "Body copy of the ad. On `type: RESULT` items it is ordinary ad text. On `type: SHOPPING_CARD` items it holds subtitle pieces that depend on the category, separated by `·` (for instance vehicle condition plus city: `Used - 94k miles · Greeley`).", "example": "Order ergonomic coding keyboards with free returns." }, "category": { "type": "string", "description": "Heading shown above the carousel that holds shopping-card ads; values seen at present include `Sponsored products`, `Sponsored vehicles` and `Sponsored hotels`. Not set on text ads (`type: RESULT`).", "example": "Sponsored products" }, "price": { "type": "object", "description": "Price of the product on ads whose type is `SHOPPING_CARD`. `value` and `currency` are filled in only if the displayed price string can be read unambiguously as a number plus a symbol. `raw` holds the displayed text exactly as shown (e.g. `\"$0 down with 24 monthly payments\"` for installment offers), letting consumers tell a real zero price apart from a down-payment label.", "properties": { "value": { "type": "number", "nullable": true, "description": "Price as a number", "example": 1199 }, "currency": { "type": "string", "nullable": true, "description": "Currency symbol", "example": "$" }, "raw": { "type": "string", "nullable": true, "description": "Price text exactly as displayed", "example": "$1,199" } } }, "oldPrice": { "type": "object", "description": "Pre-sale price for ads of `type: SHOPPING_CARD` showing MSRP or sale wording. Uses the same shape as `price`.", "properties": { "value": { "type": "number", "nullable": true, "description": "Price as a number", "example": 1299 }, "currency": { "type": "string", "nullable": true, "description": "Currency symbol", "example": "$" }, "raw": { "type": "string", "nullable": true, "description": "Price text exactly as displayed", "example": "$1,299" } } }, "store": { "type": "string", "description": "Name of the merchant or dealer on a `type: SHOPPING_CARD` ad.", "example": "Apple" }, "imageUrl": { "type": "string", "format": "uri", "description": "URL of the main image for `type: SHOPPING_CARD` ads, hosted on Google's `encrypted-tbn` CDN. Left out when the lazy-loaded image chain yields only a placeholder.", "example": "https://encrypted-tbn0.gstatic.com/images?q=tbn:..." }, "sitelinks": { "type": "array", "description": "Sitelinks shown beneath 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": "Budget monitors for home offices" } } } } } } }, "aioverview": { "oneOf": [ { "type": "object" }, { "type": "null" } ], "description": "Data from Google's AI Overview, when requested; null if no AI Overview could be obtained after retrying.", "properties": { "sources": { "type": "array", "description": "Sources the AI Overview cites", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "Position of the source, counting from 1", "example": 1 }, "url": { "type": "string", "description": "Source URL", "example": "https://example.com/programming-laptops" }, "label": { "type": "string", "description": "Title of the source (the label Google shows on the sources rail)", "example": "Top Developer Monitors 2026" }, "description": { "type": "string", "description": "Snippet or description of the source", "example": "An in-depth walkthrough of picking the right laptop for writing code" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "citationPills": { "type": "array", "description": "Citation pills that appear inline in the AI Overview answer. Every element pairs one pill with one source: a pill backed by N sources (Google's `[Label +N]` chips) yields N elements with the same `citationPillId`, each holding that source's own `label`, `url` and `domain`. Grouping by `citationPillId` rebuilds the pills. Not present in `result.aioverview` if the answer has no pills.", "items": { "type": "object", "required": [ "label", "citationPillId", "url", "domain", "position" ], "properties": { "label": { "type": "string", "description": "Title of this individual source as shown in the sources rail (e.g. `\"Chase Personal Credit Cards\"`). Empty string if the rail gives no title for it; then identify the source by `domain` / `url`. Entries that share a `citationPillId` each have their own per-source label.", "example": "Harbor Bank Cash Back Cards" }, "citationPillId": { "type": "integer", "description": "One-based number common to every entry that comes from one chip. Grouping on `citationPillId` rebuilds the chip as displayed; each entry's `label` is specific to its source, so it varies inside a chip.", "example": 1 }, "url": { "type": "string", "description": "Link straight to the cited source.", "example": "https://www.chase.com/personal/credit-cards" }, "domain": { "type": "string", "description": "Hostname taken from `url`, useful for grouping and display.", "example": "chase.com" }, "description": { "type": "string", "description": "Source snippet shown in the sources rail, if Google supplies one; omitted when the source has no snippet.", "example": "Rewards credit cards for everyday spending." }, "position": { "type": "integer", "description": "Index of this source within the sibling `result.aioverview.sources` array, starting at 1.", "example": 2 }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } }, "example": [ { "label": "Harbor Bank Cash Back Cards", "citationPillId": 1, "url": "https://www.chase.com/personal/credit-cards", "domain": "chase.com", "description": "Rewards credit cards for everyday spending.", "position": 2 }, { "label": "TechForum Hardware Q&A", "citationPillId": 1, "url": "https://www.justanswer.com/computer/help", "domain": "justanswer.com", "position": 4 } ] }, "relatedLinks": { "type": "array", "description": "Items in the \"View related links\" flyout of a citation chip: URLs that Google files under the chip but that do NOT appear in the `sources` rail (a comparison link to Google Shopping, for instance). Every entry has its chip's `citationPillId`, so it can be matched with the `citationPills` of that chip; it has no `position`, since a related link is not part of `sources`. Because these links are also rendered inline in `markdown`, `markdown` can list URLs beyond those in `sources` / `citationPills`; this array accounts for the extra ones. Not present in `result.aioverview` if none of the chips has related links.", "items": { "type": "object", "required": [ "label", "citationPillId", "url", "domain" ], "properties": { "label": { "type": "string", "description": "Title taken from the related page itself. If Google provides no title this is an empty string; use `domain` / `url` to identify the page instead.", "example": "Laptops for software work, side by side" }, "citationPillId": { "type": "integer", "description": "Same value as `citationPillId` on the chip's `citationPills` entries, which lets you attach a related link to its pill.", "example": 1 }, "url": { "type": "string", "description": "URL the related link points to directly.", "example": "https://www.google.com/search?q=developer+laptops&ibp=oshop" }, "domain": { "type": "string", "description": "Hostname taken from `url`, useful for grouping and display.", "example": "google.com" }, "description": { "type": "string", "description": "Snippet that Google provides for the related link; left out when missing.", "example": "Browse mechanical keyboards built for coders." }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } }, "example": [ { "label": "Laptops for software work, side by side", "citationPillId": 1, "url": "https://www.google.com/search?q=developer+laptops&ibp=oshop", "domain": "google.com" } ] }, "text": { "type": "string", "description": "Plain text of the AI Overview", "example": "Going by recent reviews, top monitors for coding usually come from lines such as Dell UltraSharp, LG UltraFine, and BenQ's programming series..." }, "markdown": { "type": "string", "description": "The AI Overview rendered as markdown (only when requested)", "example": "Going by recent reviews, top monitors for coding usually come from lines such as Dell UltraSharp, LG UltraFine, and BenQ's programming series..." }, "videos": { "type": "array", "description": "Videos shown inside the AI Overview", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Link straight to the video", "example": "https://www.youtube.com/watch?v=example" }, "title": { "type": "string", "description": "Video title", "example": "Top Monitors for Coding 2024" }, "thumbnail": { "type": "string", "format": "uri", "description": "URL of the thumbnail image", "example": "https://example.com/thumbnail.jpg" }, "source": { "type": "string", "description": "Name of the channel or source", "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" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "ads": { "type": "array", "description": "Paid ads that Google places inside the AI Overview", "items": { "type": "object", "required": [ "position", "title", "url", "type" ], "properties": { "position": { "type": "number", "description": "Rank of the ad (1-indexed)", "example": 1 }, "title": { "type": "string", "description": "Ad title", "example": "Automated Regression Testing - Managed QA for Web Apps" }, "url": { "type": "string", "description": "Landing page URL of the ad", "example": "https://www.testlio.com" }, "type": { "type": "string", "enum": [ "TEXT", "SHOPPING" ], "description": "Sub-type discriminator, always present. TEXT ads include `domain` and `description`; SHOPPING ads include `price` and `store` (and optionally `old_price`).", "example": "TEXT" }, "domain": { "type": "string", "description": "Advertiser's domain name; set if `type` is `TEXT`", "example": "Testlio" }, "description": { "type": "string", "description": "Body copy of the ad (only when `type` is `TEXT`)", "example": "Flexible teams. Worldwide reach. Outsourced QA with manual and automated testing." }, "price": { "type": "object", "description": "Price of the product (given when `type` equals `SHOPPING`). `value` and `currency` are filled in only if the displayed price string can be read unambiguously as a number plus a symbol; `raw` holds the displayed text exactly as shown.", "properties": { "value": { "type": "number", "nullable": true, "description": "Price as a number", "example": 69.99 }, "currency": { "type": "string", "nullable": true, "description": "Currency symbol", "example": "$" }, "raw": { "type": "string", "nullable": true, "description": "Price text exactly as displayed", "example": "$69.99" } } }, "old_price": { "type": "object", "description": "Pre-sale price; included for ads whose `type` is `SHOPPING` if they carry sale pricing. Uses the same shape as `price`.", "properties": { "value": { "type": "number", "nullable": true, "description": "Price as a number", "example": 99.99 }, "currency": { "type": "string", "nullable": true, "description": "Currency symbol", "example": "$" }, "raw": { "type": "string", "nullable": true, "description": "Price text exactly as displayed", "example": "$99.99" } } }, "store": { "type": "string", "description": "Retailer's name; included when `type` equals `SHOPPING`", "example": "Best Buy" }, "image": { "type": "string", "description": "URL of the ad's image (the product photo on shopping ads, the hero image on text ads)", "example": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQ..." } } } } } }, "shoppingCards": { "type": "array", "description": "Product cards taken from the organic shopping grids on the results page (\"Popular products\" / \"More products\"). When the page has no shopping section, `result` does not include this field at all, so clients should handle it as optional instead of relying on an empty array. The shape reuses field names from `shopping_cards` in AI Mode for consistency across endpoints, but its keys are camelCase (`productLink`, `oldPrice`) in the Google response.", "items": { "type": "object", "required": [ "title", "productLink" ], "properties": { "title": { "type": "string", "description": "Product title", "example": "Brooks Women's Ghost 17" }, "position": { "type": "integer", "description": "Rank starting at 1 over the entire `shoppingCards` array, following the order on the page (one continuous sequence that does not restart at each `category` section).", "example": 1 }, "productLink": { "type": "string", "description": "Link straight to the product. Where a click leads is filled in by JavaScript, so the static HTML usually yields an empty string here; clicking the card opens an overlay sidebar on Google instead of leaving the page.", "example": "" }, "promoLabel": { "type": "string", "description": "Discount label exactly as Google shows it, in the language of the SERP (e.g. \"LOW PRICE\", \"OFERTA\", \"PROMOÇÃO\", \"20% OFF\"), shown over the product name on cards with a discount. Set only on cards that show the label, and only for Google; AI Mode never shows it.", "example": "20% OFF" }, "category": { "type": "string", "description": "Text of the enclosing section heading, so callers can tell cards apart from other shopping panels shown on the same SERP. Google currently emits values such as \"More products\" and \"Popular products\".", "example": "More products" }, "price": { "type": "object", "description": "Price details in structured form. `value` and `currency` are set only if the visible price text can be parsed without ambiguity into a number and a symbol; `raw` holds the visible text exactly as shown.", "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": "Price text exactly as displayed", "example": "$169.99" } } }, "oldPrice": { "type": "object", "description": "Price before the discount. Uses the 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": "Price text exactly as displayed", "example": "$199.99" } } }, "store": { "type": "string", "description": "Merchant/store name", "example": "Runner's Depot" }, "rating": { "type": "number", "description": "Product rating", "example": 4.5 }, "reviews": { "type": "string", "description": "Review count", "example": "384" }, "thumbnail": { "type": "string", "format": "uri", "description": "URL of the product image", "example": "https://example.com/product.jpg" } } } }, "knowledgeGraph": { "description": "Knowledge Graph panel Google shows for the entity in the query. Not included in `result` if the results page has no such panel — handle the field as optional; it is not sent as null.", "type": "object", "properties": { "title": { "type": "string", "description": "Name of the entity from the panel's heading", "example": "Eminem" }, "type": { "type": "string", "description": "Category label for the entity exactly as Google shows it (for instance \"British singer\", \"Italian cathedral\"). Any string is possible; it is not an enum.", "example": "American rapper" }, "kgmid": { "type": "string", "description": "The entity's ID in the Google Knowledge Graph", "example": "/m/01vs_v8" }, "description": { "type": "string", "description": "Brief summary of the entity (can come from Wikipedia or from Google's knowledge base)", "example": "Robyn Rihanna Fenty, known professionally as Rihanna, is a Barbadian singer, businesswoman, and actress." }, "imageUrl": { "type": "string", "description": "Image URL for the entity, as Google delivers it", "example": "https://encrypted-tbn0.gstatic.com/images?q=tbn:..." }, "website": { "type": "string", "description": "The entity's official website URL", "example": "https://www.eminem.com" }, "menu": { "type": "string", "description": "Link to the menu — given for restaurants and other food businesses", "example": "https://www.restaurant.com/menu" }, "trailer": { "type": "string", "description": "Link to the trailer; included for movies and TV series", "example": "https://www.youtube.com/watch?v=example" }, "source": { "type": "object", "description": "Where the entity description comes from (usually Wikipedia)", "properties": { "name": { "type": "string", "description": "Name shown for the source", "example": "Wikipedia" }, "link": { "type": "string", "description": "Link to the source page", "example": "https://en.wikipedia.org/wiki/Eminem" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } }, "attributes": { "type": "array", "description": "Facts from the panel as key-value pairs (such as founded, headquarters, CEO). Keys are arbitrary strings, taken as Google shows them.", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Attribute label", "example": "Born" }, "value": { "type": "string", "description": "Attribute value", "example": "March 3, 1968" } } } }, "profiles": { "type": "array", "description": "Links to the entity's social media and other external profiles", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the platform or profile", "example": "Instagram" }, "link": { "type": "string", "description": "Profile URL", "example": "https://www.instagram.com/eminem/" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "peopleAlsoSearchFor": { "type": "array", "description": "Other entities people search for alongside this one", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the related entity", "example": "Jay-Z" }, "link": { "type": "string", "description": "URL of a Google search for this related entity", "example": "https://www.google.com/search?q=Jay-Z" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "thingsToKnow": { "type": "array", "description": "Topic groups parsed from the \"Things to know\" panel", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Label of the topic cluster", "example": "Albums" }, "subtitle": { "type": "string", "description": "Subtitle or extra text accompanying the topic", "example": "Abbey Road, Revolver, Let It Be, ..." } } } }, "ratings": { "type": "array", "description": "Ratings from review platforms (e.g. Rotten Tomatoes, IMDb); included for movies and TV series", "items": { "type": "object", "properties": { "platform": { "type": "string", "description": "Name of the review platform", "example": "Rotten Tomatoes" }, "rating": { "type": "string", "description": "Rating exactly as shown", "example": "88%" }, "link": { "type": "string", "description": "Link to the reviews page", "example": "https://www.rottentomatoes.com/m/8_mile" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "streamingOptions": { "type": "array", "description": "Links to streaming platforms for movies and TV series", "items": { "type": "object", "properties": { "platform": { "type": "string", "description": "Name of the streaming platform", "example": "Netflix" }, "link": { "type": "string", "description": "URL where the platform hosts the content", "example": "https://www.netflix.com/title/example" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "webRatings": { "type": "array", "description": "Ratings collected from online review sites; included when the result is a local business (such as Google, Tripadvisor, Yelp)", "items": { "type": "object", "properties": { "platform": { "type": "string", "description": "Name of the rating platform", "example": "Google" }, "rating": { "type": "string", "description": "Rating exactly as shown", "example": "4.5" }, "link": { "type": "string", "description": "Link to this platform's reviews page", "example": "https://www.google.com/maps/place/..." }, "votes": { "type": "string", "description": "Vote or review count (absent when unavailable)", "example": "1,234" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "statsCard": { "type": "object", "description": "Card with statistics; included for entities such as sports teams and organizations", "properties": { "context": { "type": "string", "description": "Label giving the stats their context, such as a year or season", "example": "2024-25 regular season" }, "stats": { "type": "array", "description": "Entries for each statistic", "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": "Latest social media posts published by the entity's official accounts", "items": { "type": "object", "properties": { "platform": { "type": "string", "description": "Name of the social platform", "example": "X" }, "text": { "type": "string", "description": "Text of the post", "example": "Tour dates announced tonight 🎤" }, "link": { "type": "string", "description": "Link to the post", "example": "https://x.com/eminem/status/..." }, "date": { "type": "string", "description": "Posting date as Google displays it", "example": "2 days ago" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "notableAlumni": { "type": "array", "description": "Well-known alumni — given for universities and other educational institutions", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Alumni name", "example": "Barack Obama" }, "link": { "type": "string", "description": "URL of a Google search for this person", "example": "https://www.google.com/search?q=Barack+Obama" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "contact": { "type": "array", "description": "Links for contacting or ordering; included 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" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "weather": { "type": "object", "description": "Weather right now; included for geographic entities such as cities and regions", "properties": { "temperature": { "type": "string", "description": "Temperature exactly as shown", "example": "72°F" }, "condition": { "type": "string", "description": "Weather condition", "example": "Sunny" } } }, "rating": { "type": "object", "description": "Overall star rating; included for local businesses", "properties": { "rating": { "type": "string", "description": "Value of the star rating", "example": "4.5" }, "count": { "type": "string", "description": "Review count", "example": "2,847" } } }, "admission": { "type": "array", "description": "Ticket choices; included for museums, parks and other venues that charge entry", "items": { "type": "object", "properties": { "provider": { "type": "string", "description": "Name of the ticket seller", "example": "Official website" }, "price": { "type": "string", "description": "Entry price exactly as shown", "example": "$17" }, "link": { "type": "string", "description": "Link for buying tickets", "example": "https://www.louvre.fr/en/tickets" }, "badge": { "type": "string", "description": "Badge label, if any (e.g. \"Free\", \"Best price\"); absent otherwise", "example": "Best price" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "artworks": { "type": "array", "description": "Well-known artworks — given for artists and for art institutions", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Artwork title", "example": "Mona Lisa" }, "link": { "type": "string", "description": "URL with further details about the artwork", "example": "https://www.google.com/search?q=Mona+Lisa" }, "author": { "type": "string", "description": "Name of the author or creator; absent if not shown", "example": "Claude Monet" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "has3dModel": { "type": "boolean", "description": "True if Google offers an interactive 3D view of the entity", "example": true }, "hotelOptions": { "type": "array", "description": "Options for booking the hotel — only for hotel entities", "items": { "type": "object", "properties": { "provider": { "type": "string", "description": "Name of the booking provider", "example": "Booking.com" }, "price": { "type": "string", "description": "Price exactly as shown", "example": "$189/night" }, "link": { "type": "string", "description": "Booking link for this provider", "example": "https://www.booking.com/hotel/..." }, "note": { "type": "string", "description": "Note text, if any (e.g. \"Free cancellation\"); absent otherwise", "example": "Includes breakfast" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "trendingProducts": { "type": "array", "description": "Products currently trending; included for retail brands", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Product title", "example": "Cloudsurfer 7" }, "price": { "type": "string", "description": "Price exactly as shown", "example": "$120" }, "link": { "type": "string", "description": "URL of the product", "example": "https://www.nike.com/t/air-max-90" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "merchantVideos": { "type": "array", "description": "Videos from the merchant or brand — given for retail businesses", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Video title", "example": "Spring Running Shoe Event" }, "link": { "type": "string", "description": "Video URL", "example": "https://www.youtube.com/watch?v=..." }, "platform": { "type": "string", "description": "Platform hosting the video; left out if unknown", "example": "YouTube" }, "duration": { "type": "string", "description": "Length of the video as shown; left out if unknown", "example": "2:34" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "listenOn": { "type": "array", "description": "Links to music streaming services — given for musicians and bands", "items": { "type": "object", "properties": { "platform": { "type": "string", "description": "Name of the streaming platform", "example": "Spotify" }, "link": { "type": "string", "description": "URL of the artist's page on the platform", "example": "https://open.spotify.com/artist/..." }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } }, "html": { "type": "array", "description": "Raw HTML of the Google search page (when requested)", "items": { "type": "string", "format": "uri" }, "example": [ "https://files.answerline.dev/html/b83e8dfd-c3a1-4b98-83b9-af91adc21e26/1/page-1.html" ] } } } } }, "GoogleGotoRequest": { "required": [ "url" ], "type": "object", "properties": { "url": { "description": "Absolute URL of a Google redirect link that you want resolved. It must point to `google.com` or `www.google.com` and use a path of `/goto` or `/url`, which is the form returned as `redirectLink` alongside each resolved link in AI Mode, Google Search and Google News responses.", "type": "string", "format": "uri", "example": "https://www.google.com/goto?url=CAESaQHrOzAVqzmLoOGwx_6OnzSPRKSyqmXD3yEDa0VIkUCfa5RKEaB9eIJOYz_M1y_VwKrr5jrSlrFlZlBUbe9DQXMPRUiSOrjBMQ78vpRZtXEhawDDabM58DDRHnv2f-XOQAWw-nwkup9ptQ" } }, "additionalProperties": false }, "GoogleGotoResponse": { "required": [ "url" ], "type": "object", "properties": { "url": { "description": "Target URL that the redirect link leads to", "type": "string", "format": "uri", "example": "https://www.youtube.com/watch?v=pma08NXw8Ts&t=541" } } }, "GoogleNewsMonitorRequest": { "required": [ "query" ], "type": "object", "properties": { "query": { "description": "Query to run on Google News", "type": "string", "minLength": 1, "maxLength": 10000, "example": "climate change" }, "country": { "description": "Country for localized news, as an ISO 3166-1 alpha-2 code. Google News publishes an edition in 71 countries, listed at https://answerline.dev/docs/coverage#countries; a request for another country is refused with a 400.", "type": "string", "example": "US" }, "gl": { "$ref": "#/components/schemas/GlParameter" }, "hl": { "$ref": "#/components/schemas/HlParameter" }, "device": { "description": "Device to run the search on. Not served for Google News yet: its results are read without a device, and a request that sets one is refused with a 400.", "type": "string", "enum": [ "desktop", "mobile", "ios", "android" ], "default": "desktop", "example": "desktop" }, "pages": { "description": "How many pages of news results to retrieve (1-10)", "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "example": 1 }, "include": { "description": "Flags that add extra data to the response (optional)", "type": "object", "properties": { "html": { "description": "Not available for Google News: results are read from the news feed, with no page to snapshot, so `true` is refused with a validation error.", "type": "boolean", "default": false, "example": false } }, "default": { "html": false }, "additionalProperties": false } }, "additionalProperties": false, "anyOf": [ { "required": [ "country" ] }, { "required": [ "gl" ] } ] }, "GoogleNewsMonitorResponse": { "required": [ "success", "result" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "description": "Data from the Google News results", "type": "object", "properties": { "newsResults": { "type": "array", "description": "Articles returned by Google News", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "Rank among news results (1-indexed)", "example": 1 }, "title": { "type": "string", "description": "News article headline", "example": "Global Ocean Treaty Wins Final Ratification Vote" }, "link": { "type": "string", "description": "Link to the news article", "example": "https://example.com/climate-summit-agreement" }, "snippet": { "type": "string", "description": "Short text summarizing the article", "example": "Central banks signaled further interest rate cuts this quarter..." }, "source": { "type": "string", "description": "Name of the news outlet or publisher", "example": "The Guardian" }, "date": { "type": "string", "description": "Publication date", "example": "2 hours ago" }, "page": { "type": "number", "description": "Results page this item was found on (1-indexed)", "example": 1 }, "thumbnail": { "type": "string", "description": "URL of the thumbnail image, when one exists", "example": "https://example.com/images/climate-summit.jpg" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "html": { "type": "array", "description": "Raw HTML of the Google News pages (when requested)", "items": { "type": "string", "format": "uri" }, "example": [ "https://files.answerline.dev/html/a12b3c4d-5e6f-47a8-9b0c-a1b2c3d4e5f6/1/page-1.html" ] } } } } }, "CopilotMonitorRequest": { "required": [ "prompt", "country" ], "type": "object", "properties": { "prompt": { "description": "Prompt submitted to Copilot", "type": "string", "minLength": 1, "maxLength": 10000, "example": "Which laptop should I buy for software development?" }, "country": { "description": "Code of the country or region used to localize the response", "type": "string", "example": "US" }, "include": { "description": "Flags that add extra output formats to the response (optional)", "type": "object", "properties": { "html": { "description": "Return a link to the complete HTML of the response", "type": "boolean", "default": false, "example": true }, "markdown": { "description": "Add a markdown version of the response to the result", "type": "boolean", "default": false, "example": true }, "rawResponse": { "description": "Return the unprocessed stream of 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": "Data from Copilot's reply", "type": "object", "properties": { "text": { "type": "string", "description": "Text of Copilot's reply", "example": "Happy to help you pick a monitor that works well for coding..." }, "html": { "type": "string", "format": "uri", "description": "Link to the response's complete HTML.", "example": "https://files.answerline.dev/html/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/1/page-1.html" }, "sources": { "type": "array", "description": "Sources the response cites", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "Where the source sits in the response, as an index", "example": 1 }, "url": { "type": "string", "description": "Link to the source", "example": "https://example.com/article" }, "label": { "type": "string", "description": "Label shown for this source", "example": "Microsoft Docs" }, "description": { "type": "string", "description": "Text describing what the source contains", "example": "Hardware picks for programmers" } } }, "example": [ { "position": 1, "url": "https://docs.microsoft.com/", "label": "Microsoft Docs", "description": "Official developer docs" } ] }, "citationPills": { "type": "array", "description": "Citation pills that appear inline in the Copilot answer. Every element pairs one pill with one source: a pill backed by N sources (a chip made from consecutive citation events) yields N elements with the same `citationPillId`, each holding that source's own `label`, `url` and `domain`. Grouping by `citationPillId` rebuilds the pills. Not present in `result` if the answer has no pills.", "items": { "type": "object", "required": [ "label", "citationPillId", "url", "domain", "position" ], "properties": { "label": { "type": "string", "description": "Title of this individual source, taken from the citation event (for instance `\"Microsoft 365 Documentation\"`, `\"Productivity Best Practices\"`). Never missing, but can be an empty string if the event carries no title — in that case identify the source by `domain` / `url`. Entries that share a `citationPillId` each have their own per-source label.", "example": "Vendor Help Center" }, "citationPillId": { "type": "integer", "description": "One-based number common to every entry that comes from one chip. Grouping on `citationPillId` rebuilds the chip as displayed; each entry's `label` is specific to its source, so it varies inside a chip.", "example": 1 }, "url": { "type": "string", "description": "Link straight to the cited source.", "example": "https://docs.microsoft.com/" }, "domain": { "type": "string", "description": "Hostname taken from `url`, useful for grouping and display.", "example": "docs.microsoft.com" }, "description": { "type": "string", "description": "Source snippet shown in the sources rail, if Copilot supplies one; otherwise omitted.", "example": "Official developer docs" }, "position": { "type": "integer", "description": "Index of this source within the sibling `result.sources` array, starting at 1.", "example": 1 } } }, "example": [ { "label": "Vendor Help Center", "citationPillId": 1, "url": "https://docs.microsoft.com/", "domain": "docs.microsoft.com", "description": "Official developer docs", "position": 1 }, { "label": "Neovim source on GitHub", "citationPillId": 1, "url": "https://github.com/microsoft/vscode", "domain": "github.com", "description": "Neovim repository", "position": 2 } ] }, "shoppingCards": { "type": "array", "description": "Shopping/product cards parsed from the response (if any)", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of shopping card", "example": "shoppingProducts" }, "layout": { "type": "string", "description": "Visual layout used for the shopping card", "example": "Carousel" }, "products": { "type": "array", "description": "List of product details", "items": { "type": "object", "properties": { "product": { "type": "object", "description": "Identifiers for the product", "properties": { "id": { "type": "string", "description": "Product's unique ID" }, "groupId": { "type": "string", "description": "ID of the product group" }, "brandGroupId": { "type": "string", "description": "ID of the brand group (optional)" } } }, "position": { "type": "integer", "description": "Rank starting at 1, counted over every product in every shopping card of the response (one continuous sequence that does not restart for each card).", "example": 1 }, "offerId": { "type": "string", "description": "Identifier unique to the offer" }, "url": { "type": "string", "description": "URL of the product page" }, "name": { "type": "string", "description": "Product name" }, "description": { "type": "string", "description": "Product description" }, "images": { "type": "array", "description": "Product images, each with a title and URL", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Image title" }, "url": { "type": "string", "description": "Image URL" } } } }, "specifications": { "type": "array", "description": "Product attributes such as Color or 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": "Pricing details for the product", "properties": { "amount": { "type": "number", "description": "Price amount" }, "currency": { "type": "string", "description": "Code of the currency, if given" }, "currencySymbol": { "type": "string", "description": "Currency symbol" } } }, "seller": { "type": "string", "description": "Seller name" }, "sellerLogoUrl": { "type": "string", "description": "URL of the seller's logo" }, "brandName": { "type": "string", "description": "Brand of the product" }, "rating": { "type": "object", "description": "Rating details for the product", "properties": { "value": { "type": "number", "description": "Rating value" }, "count": { "type": "integer", "description": "Rating count" } } }, "canTrackPrice": { "type": "boolean", "description": "Indicates if price tracking is offered" } } } } } } }, "map": { "type": "array", "description": "Map entries for businesses or places parsed from the response (if any)", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Business name", "example": "Lakeside Science Museum" }, "position": { "type": "integer", "description": "Rank in the results (1-indexed)", "example": 1 }, "placeId": { "type": "string", "description": "Place ID on Google", "example": "ChIJEYpTsk__W4gR2sQLGzOjE3o" }, "location": { "type": "object", "description": "Business location", "properties": { "address": { "type": "string", "description": "Complete street address", "example": "250 Harbor Dr, Duluth, MN 55802" }, "latitude": { "type": "number", "description": "GPS latitude", "example": 35.823257 }, "longitude": { "type": "number", "description": "GPS longitude", "example": -83.5787498 } } }, "phoneNumber": { "type": "string", "description": "Phone number for contact", "example": "(865) 868-1800" }, "url": { "type": "string", "format": "uri", "description": "URL of the business's website", "example": "http://www.wonderworksonline.com/pigeon-forge/" }, "reviews": { "type": "array", "description": "Aggregated review data from providers", "items": { "type": "object", "properties": { "count": { "type": "integer", "description": "Review count", "example": 10625 }, "rating": { "type": "number", "description": "Average rating", "example": 4.3 }, "providerName": { "type": "string", "description": "Name of the review provider", "example": "Google" }, "providerIconUrl": { "type": "string", "description": "URL of the provider's icon" }, "url": { "type": "string", "format": "uri", "description": "URL of the reviews page", "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": "The photo's alt text" }, "providerName": { "type": "string", "description": "Name of the photo provider" }, "providerUrl": { "type": "string", "format": "uri", "description": "URL of the photo provider" } } } }, "openState": { "type": "string", "description": "Whether it is open or closed now", "example": "Open · Closes 8 PM" }, "category": { "type": "string", "description": "Business category", "example": "Amusement park" }, "price": { "description": "Price tier, if known" }, "layerLabel": { "type": "string", "description": "Grouping label for the map layer", "example": "Theme Parks" } }, "example": { "name": "Lakeside Science Museum", "position": 1, "placeId": "ChIJEYpTsk__W4gR2sQLGzOjE3o", "location": { "address": "250 Harbor Dr, Duluth, MN 55802", "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 8 PM", "category": "Amusement park", "price": null, "layerLabel": "Theme Parks" } } }, "searchQueries": { "type": "array", "description": "Query fan-out: the web searches Copilot performed as it wrote the response. Returned automatically whenever there is at least one, at no extra cost.", "items": { "type": "string" }, "example": [ "coding laptop recommendations 2025", "laptop reviews for programmers" ] }, "markdown": { "type": "string", "description": "Copilot's reply as Markdown; returned only if include.markdown is true", "example": "Happy to help you pick a monitor that works well for coding..." }, "rawResponse": { "type": "array", "description": "Unprocessed stream from the upstream provider, recorded while the request ran. Every item is a single chunk of the engine's raw response. The format varies by engine, is not documented and can change at any time without warning; use it to debug or to read data not yet exposed by the structured fields above.", "items": {} } } } } }, "PerplexityMonitorRequest": { "required": [ "prompt", "country" ], "type": "object", "properties": { "prompt": { "description": "Prompt submitted to Perplexity", "type": "string", "minLength": 1, "maxLength": 10000, "example": "Which laptop should I buy for software development?" }, "country": { "description": "Code of the country or region used to localize the response", "type": "string", "example": "US" }, "include": { "description": "Flags that add extra output formats to the response (optional)", "type": "object", "properties": { "html": { "description": "Return a link to the complete HTML of the response", "type": "boolean", "default": false, "example": true }, "markdown": { "description": "Add a markdown version of the response to the result", "type": "boolean", "default": false, "example": true }, "rawResponse": { "description": "Return the unprocessed stream of 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": "Data returned by Perplexity", "type": "object", "properties": { "text": { "type": "string", "description": "Text of Perplexity's answer", "example": "According to recent sources, these are the strongest monitors for coding..." }, "html": { "type": "string", "format": "uri", "description": "Link to the response's complete HTML.", "example": "https://files.answerline.dev/html/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/1/page-1.html" }, "sources": { "type": "array", "description": "Sources the response cites", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "Where the source sits in the response, as an index", "example": 1 }, "url": { "type": "string", "description": "Link to the source", "example": "https://example.com/article" }, "label": { "type": "string", "description": "Label shown for this source", "example": "Perplexity Search" }, "description": { "type": "string", "description": "Text describing what the source contains", "example": "Live results from web search" } } }, "example": [ { "position": 1, "url": "https://techcrunch.com/laptops", "label": "TechCrunch", "description": "Recent tablet reviews and buying advice" }, { "position": 2, "url": "https://www.youtube.com/watch?v=example", "label": "Top Notebooks This Year", "description": "Hands-on test of coding laptops" }, { "position": 3, "url": "https://wired.com/programming-laptops", "label": "Wired", "description": "Guide to picking a laptop for coding" } ] }, "citationPills": { "type": "array", "description": "Citation pills that appear inline in the Perplexity answer. Every element pairs one pill with one source: a pill backed by N sources (bracketed groups like Perplexity's `[1][2][3]`) yields N elements with the same `citationPillId`, each holding that source's own `label`, `url` and `domain`. Grouping by `citationPillId` rebuilds the pills. Not present in `result` if the answer has no pills.", "items": { "type": "object", "required": [ "label", "citationPillId", "url", "domain", "position" ], "properties": { "label": { "type": "string", "description": "Title of this individual source as shown in the sources rail (for instance `\"Best Programming Laptops 2026 — TechCrunch\"`). Never missing, but can be an empty string if the rail gives no title for it — in that case identify the source by `domain` / `url`. Entries that share a `citationPillId` each have their own per-source label.", "example": "Top Developer Monitors 2026 — Wired" }, "citationPillId": { "type": "integer", "description": "One-based number common to every entry that comes from one chip. Grouping on `citationPillId` rebuilds the chip as displayed; each entry's `label` is specific to its source, so it varies inside a chip.", "example": 1 }, "url": { "type": "string", "description": "Link straight to the cited source.", "example": "https://techcrunch.com/laptops" }, "domain": { "type": "string", "description": "Hostname taken from `url`, useful for grouping and display.", "example": "techcrunch.com" }, "description": { "type": "string", "description": "Source snippet shown in the sources rail, if Perplexity supplies one; otherwise omitted.", "example": "Recent tablet reviews and buying advice" }, "position": { "type": "integer", "description": "Index of this source within the sibling `result.sources` array, starting at 1.", "example": 1 } } }, "example": [ { "label": "Top Developer Monitors 2026 — Wired", "citationPillId": 1, "url": "https://techcrunch.com/laptops", "domain": "techcrunch.com", "description": "Recent tablet reviews and buying advice", "position": 1 }, { "label": "Tom's Hardware Laptop Buying Guide", "citationPillId": 1, "url": "https://wired.com/programming-laptops", "domain": "wired.com", "description": "Guide to picking a laptop for coding", "position": 3 } ] }, "markdown": { "type": "string", "description": "Perplexity's answer rendered as Markdown (present when include.markdown is true)", "example": "According to recent sources, these are the strongest monitors for coding..." }, "related_queries": { "type": "array", "description": "Suggested searches to follow up with", "items": { "type": "string" }, "example": [ "safest areas to book accommodation in Lisbon", "best-reviewed boutique hotels in Lisbon below €250", "best-reviewed seafood tascas in Alfama" ] }, "videos": { "type": "array", "description": "Videos that appear in the response", "items": { "$ref": "#/components/schemas/MediaItem" } }, "images": { "type": "array", "description": "Image found in the response", "items": { "$ref": "#/components/schemas/MediaItem" } }, "hotels": { "type": "array", "description": "Hotels listed when the query shows travel intent", "items": { "$ref": "#/components/schemas/HotelItem" } }, "places": { "type": "array", "description": "Places and locations in general", "items": { "$ref": "#/components/schemas/PlaceItem" } }, "shopping_cards": { "type": "array", "description": "Product cards for shopping with full product details (present when the query shows shopping intent)", "items": { "type": "object", "properties": { "tags": { "type": "array", "description": "Category tags on the shopping card, if any", "items": { "type": "string" }, "example": [ "running", "athletic" ] }, "products": { "type": "array", "description": "List of products", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Product name", "example": "Brooks Ghost 16" }, "id": { "type": "string", "description": "Product identifier", "example": "nike-pegasus-41" }, "url": { "type": "string", "description": "URL of the product page", "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": "True if the product is available right now", "example": true }, "imageUrls": { "type": "array", "description": "URLs of the product images", "items": { "type": "string" } }, "numReviews": { "type": "number", "description": "Review count (0 if there are none)", "example": 1284 }, "offers": { "type": "array", "description": "Per-merchant shopping offers", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Offer link including 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 title as given by the merchant", "example": "Brooks Ghost 16 Running Shoes" }, "available": { "type": "boolean", "description": "True if this offer currently has stock", "example": true }, "price_details": { "type": "object", "description": "Itemized breakdown of the price", "properties": { "display_price": { "type": "string", "description": "Price formatted for display", "example": "$140.00" } } }, "original_price": { "type": "string", "nullable": true, "description": "Pre-discount price; null if the item isn't on sale", "example": null } } } }, "position": { "type": "integer", "description": "Rank starting at 1, counted over every product in every shopping card of the response (one continuous sequence that does not restart for each card)", "example": 1 }, "rating": { "type": "number", "description": "Rating of the product, on a 0-5 scale", "example": 4.6 }, "original_price": { "type": "string", "nullable": true, "description": "Pre-discount price; null if the item isn't on sale" }, "description": { "type": "string", "description": "Product description", "example": "Lightweight support for long-distance road racing." }, "variants": { "type": "array", "description": "Variants of the product (e.g. size or color)", "items": { "type": "object" } } } } } } } }, "search_model_queries": { "type": "array", "description": "Search queries the engine ran internally to build the response", "items": { "type": "string", "example": "top places to eat and stay in lisbon" } }, "rawResponse": { "type": "array", "description": "Unprocessed stream from the upstream provider, recorded while the request ran. Every item is a single chunk of the engine's raw response. The format varies by engine, is not documented and can change at any time without warning; use it to debug or to read data not yet exposed by the structured fields above.", "items": {} } } } } }, "AiModeMonitorRequest": { "required": [ "prompt" ], "type": "object", "properties": { "prompt": { "description": "Prompt submitted to AI Mode", "type": "string", "minLength": 1, "maxLength": 10000, "example": "Which laptop should I buy for software development?" }, "country": { "description": "Code of the country or region used to localize the response", "type": "string", "example": "US" }, "gl": { "$ref": "#/components/schemas/GlParameter" }, "hl": { "$ref": "#/components/schemas/HlParameter" }, "location": { "description": "Location name in Google's canonical form, used for geo-targeted results, written comma-separated as 'City,Region,Country' (https://developers.google.com/google-ads/api/reference/data/geotargets lists every supported location, ~100,000 in all). Combine it with 'country' to target a specific city. Cannot be combined with 'uule'; send only one of the two.", "type": "string", "example": "Chicago,Illinois,United States" }, "uule": { "description": "A ready-made Google UULE string for exact geo-targeting, in the location-name form (starting w+CAIQICI); the coordinate form (a+) is refused with a 400. Supply it when you already have an encoded UULE rather than a location name. Cannot be sent together with 'location' — pass only one of the two.", "type": "string", "example": "w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5" }, "device": { "description": "Type of device the results are fetched for", "type": "string", "enum": [ "desktop", "mobile" ], "default": "desktop", "example": "desktop" }, "include": { "description": "Flags that add extra output formats to the response (optional)", "type": "object", "properties": { "html": { "description": "Return a link to the complete HTML of the response", "type": "boolean", "default": false, "example": true }, "markdown": { "description": "Add a markdown version of the response to the result", "type": "boolean", "default": false, "example": true }, "expandProducts": { "description": "Look up merchant offers for the response's product clusters and return them in 'result.productResults'. Clusters found in both inline products and shopping cards count once, and no more than 6 are expanded per request. Each returned cluster adds a per-cluster charge. Disabled by default.", "type": "boolean", "default": false, "example": true }, "googleGoto": { "description": "Has had no effect since 8th September 2026. Each redirect link is now always returned as `redirectLink` next to its target, so you get both without setting this flag. Requests that still include it are handled as though it were omitted.", "type": "boolean", "default": false, "example": true, "deprecated": true } }, "default": { "html": false, "markdown": false, "expandProducts": false }, "additionalProperties": false } }, "additionalProperties": false, "anyOf": [ { "required": [ "country" ] }, { "required": [ "gl" ] } ] }, "AiModeMonitorResponse": { "required": [ "success", "result" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "description": "Data returned by AI Mode", "type": "object", "properties": { "text": { "type": "string", "description": "Text of the AI Mode answer", "example": "These are strong tablet picks for digital drawing and note-taking..." }, "html": { "type": "string", "format": "uri", "description": "Link to the response's complete HTML.", "example": "https://files.answerline.dev/html/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/1/page-1.html" }, "sources": { "type": "array", "description": "Sources the response cites", "items": { "type": "object", "properties": { "position": { "type": "number", "description": "Where the source sits in the response, as an index", "example": 1 }, "url": { "type": "string", "description": "Link to the source", "example": "https://example.com/article" }, "label": { "type": "string", "description": "Label shown for this source", "example": "AI Source" }, "description": { "type": "string", "description": "Text describing what the source contains", "example": "AI-generated recommendations" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } }, "example": [ { "position": 1, "url": "https://example.com/ai-recommendations", "label": "AI Source", "description": "AI-selected monitor picks" } ] }, "citationPills": { "type": "array", "description": "Citation pills that appear inline in the AI Mode answer. Every element pairs one pill with one source: a pill backed by N sources (Google's `[Label +N]` chips) yields N elements with the same `citationPillId`, each holding that source's own `label`, `url` and `domain`. Grouping by `citationPillId` rebuilds the pills. Not present in `result` if the answer has no pills.", "items": { "type": "object", "required": [ "label", "citationPillId", "url", "domain", "position" ], "properties": { "label": { "type": "string", "description": "Title of this individual source as shown in the sources rail (e.g. `\"Best Laptops 2026 — Reuters\"`). Empty string if the rail gives no title for it; then identify the source by `domain` / `url`. Entries that share a `citationPillId` each have their own per-source label.", "example": "Top Monitors of 2026 — The Verge" }, "citationPillId": { "type": "integer", "description": "One-based number common to every entry that comes from one chip. Grouping on `citationPillId` rebuilds the chip as displayed; each entry's `label` is specific to its source, so it varies inside a chip.", "example": 1 }, "url": { "type": "string", "description": "Link straight to the cited source.", "example": "https://example.com/best-laptops-2026" }, "domain": { "type": "string", "description": "Hostname taken from `url`, useful for grouping and display.", "example": "example.com" }, "description": { "type": "string", "description": "Source snippet shown in the sources rail, if Google supplies one; omitted when the source has no snippet.", "example": "An overview of this year's strongest monitors for coding work." }, "position": { "type": "integer", "description": "Index of this source within the sibling `result.sources` array, starting at 1.", "example": 1 }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } }, "example": [ { "label": "Top Monitors of 2026 — The Verge", "citationPillId": 1, "url": "https://example.com/best-laptops-2026", "domain": "example.com", "description": "An overview of this year's strongest monitors for coding work.", "position": 1 }, { "label": "iPad Air M3 First Impressions", "citationPillId": 1, "url": "https://example.com/macbook-pro-review", "domain": "example.com", "position": 3 } ] }, "markdown": { "type": "string", "description": "The AI Mode answer rendered as Markdown (present when include.markdown is true)", "example": "These are strong tablet picks for digital drawing and note-taking..." }, "places": { "type": "array", "description": "Place cards embedded inline in the response", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Place name", "example": "Gion District" }, "link": { "type": "string", "format": "uri", "description": "URL that opens the place in Google's viewer", "example": "https://www.google.com/viewer/place?mid=/g/11bw3yq9kp" }, "placeId": { "type": "string", "description": "ID of the place in Google Places", "example": "/g/11bw3yq9kp" }, "index": { "type": "integer", "description": "Index of the place's position in the results", "example": 0 }, "thumbnail": { "type": "string", "format": "uri", "description": "Thumbnail image URL for the place", "example": "https://lh5.googleusercontent.com/p/example" }, "rating": { "type": "number", "description": "Rating in stars (0-5)", "example": 4.5 }, "reviews": { "type": "integer", "description": "Review count", "example": 2900 }, "type": { "type": "string", "description": "Category or type of the place", "example": "Tourist attraction" }, "priceLevel": { "type": "string", "description": "Indicator of the price tier", "example": "$$" }, "address": { "type": "string", "description": "Full address", "example": "Nishiki Market, Nakagyo Ward, Kyoto" }, "status": { "type": "string", "description": "Operating status", "example": "Open now" } } } }, "shoppingCards": { "type": "array", "description": "Shopping-related product details parsed from the response", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Product title", "example": "Wireless Headphones" }, "price": { "type": "object", "description": "Price details in structured form", "properties": { "value": { "type": "number", "description": "Numeric price", "example": 99.99 }, "currency": { "type": "string", "description": "Currency symbol", "example": "$" }, "raw": { "type": "string", "description": "Price text exactly as the upstream provider returned it (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": "Link straight to the product", "example": "https://www.google.com/example" }, "oldPrice": { "type": "object", "description": "Pre-discount price", "properties": { "value": { "type": "number", "description": "Numeric price", "example": 129.99 }, "currency": { "type": "string", "description": "Currency symbol", "example": "$" }, "raw": { "type": "string", "description": "Price text exactly as the upstream provider returned it (e.g. \"$129.99\").", "example": "$129.99" } } }, "snippet": { "type": "string", "description": "Short product description", "example": "Waterproof Bluetooth speaker with 20-hour battery life" }, "snippet_links": { "type": "array", "description": "Links contained in 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" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "position": { "type": "integer", "description": "Index (0-indexed) of the product card inside the shopping carousel.", "example": 0 } } } }, "ads": { "type": "object", "description": "Section of sponsored ads parsed from the response", "properties": { "title": { "type": "string", "description": "Heading of the ads section", "example": "A few espresso machines worth a look" }, "ads": { "type": "array", "description": "List of sponsored ads", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the advertised product", "example": "Prusa Core One" }, "url": { "type": "string", "format": "uri", "description": "Click-through URL of the ad", "example": "https://www.google.com/aclk?sa=L&ai=abc" }, "position": { "type": "integer", "description": "Index of the ad's position", "example": 1 }, "price": { "type": "object", "description": "Price details in structured form", "properties": { "value": { "type": "number", "description": "Numeric price", "example": 899 }, "currency": { "type": "string", "description": "Currency symbol", "example": "$" } } }, "store": { "type": "string", "description": "Merchant/store name", "example": "Prusa Store" }, "rating": { "type": "number", "description": "Product rating", "example": 4.7 }, "reviews": { "type": "string", "description": "Review count", "example": "584" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } } } }, "inlineProducts": { "type": "array", "description": "Product cards that appear inside the AI answer text", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Product title", "example": "Sony WH-1000XM5" }, "position": { "type": "integer", "description": "Rank starting at 1 over the `inline_products` array, following the order on the page.", "example": 1 }, "price": { "type": "object", "description": "Price details in structured form", "properties": { "value": { "type": "number", "description": "Numeric price", "example": 298 }, "currency": { "type": "string", "description": "Currency symbol", "example": "$" } } }, "oldPrice": { "type": "object", "description": "Pre-discount price", "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": "URL of the product image", "example": "https://encrypted-tbn0.gstatic.com/images?q=example" }, "productLink": { "type": "string", "format": "uri", "description": "Link straight to the product", "example": "https://www.google.com/shopping/product/example" } } } }, "videos": { "type": "array", "description": "Video cards shown inline within the AI response (YouTube for now)", "items": { "type": "object", "required": [ "title", "link" ], "properties": { "title": { "type": "string", "description": "Video title", "example": "I Tested 5 Budget Drones So You Don't Have To" }, "link": { "type": "string", "format": "uri", "description": "Canonical watch URL with any timestamp parameters removed", "example": "https://www.youtube.com/watch?v=g0DZnQdI-xQ" }, "platform": { "type": "string", "description": "Hosting platform read from the byline on the card", "example": "YouTube" }, "channel": { "type": "string", "description": "Name of the channel or uploader", "example": "Layer Lines Workshop" }, "duration": { "type": "string", "description": "Duration text as shown (mm:ss or hh:mm:ss)", "example": "08:49" }, "thumbnail": { "type": "string", "format": "uri", "description": "Publicly accessible thumbnail URL", "example": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcS5Bntg3F0Y7P3YgTPgdyillyeCguV_YQJ99KFUmNYxmQtVt1f2" }, "redirectLink": { "type": "string", "description": "The `/goto` redirect Google used for this link, given in the absolute form that `POST /v1/monitor/google/goto` takes. Only set when Google delivered the link through a redirect; the neighbouring link field contains the destination Answerline reached by following it.", "example": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk" } } } }, "map": { "type": "array", "description": "Locations pulled from the response, enriched with GPS coordinates", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Place name", "example": "Riverside Bistro" }, "link": { "type": "string", "format": "uri", "description": "URL that opens the place in Google's viewer", "example": "https://www.google.com/viewer/place?mid=/g/11bw3yq9kp" }, "placeId": { "type": "string", "description": "ID of the place in Google Places", "example": "/g/11bw3yq9kp" }, "index": { "type": "integer", "description": "Index of the place's position in the results", "example": 0 }, "gps_coordinates": { "type": "object", "description": "The place's geographic coordinates", "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": "Thumbnail image URL for the place", "example": "https://lh5.googleusercontent.com/p/example" }, "rating": { "type": "number", "description": "Rating in stars (0-5)", "example": 4.5 }, "reviews": { "type": "integer", "description": "Review count", "example": 1234 }, "type": { "type": "string", "description": "Category or type of the place", "example": "Coffee shop" }, "address": { "type": "string", "description": "Full address", "example": "450 Lexington Ave, New York" }, "status": { "type": "string", "description": "Operating status", "example": "Open now" } } } } } } } }, "MediaItem": { "type": "object", "description": "A video or image that appears in the response", "properties": { "title": { "type": "string", "description": "Media title", "example": "Lisbon's top hotels, ranked | The Guardian" }, "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": "Width of the original image", "example": 5600 }, "image_height": { "type": "number", "description": "Height of the original image", "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 entry with full details", "properties": { "name": { "type": "string", "description": "Hotel name", "example": "Casa do Largo Porto Boutique Hotel" }, "url": { "type": "string", "description": "URL of the hotel's page", "example": "https://www.tripadvisor.com/Hotel_Review-g189158-d12659702-Reviews-Corpo_Santo_Lisbon_Historical_Hotel-Lisbon_District_Central_Portugal.html" }, "rating": { "type": "number", "description": "Rating of the hotel, from 0 to 5", "example": 4.9 }, "num_reviews": { "type": "number", "description": "Review count", "example": 4374 }, "address": { "type": "array", "description": "Address lines", "items": { "type": "string" }, "example": [ "Rua das Flores, 41, Porto 4050-265 Portugal" ] }, "phone": { "type": "string", "description": "Phone number", "example": "+351 21 340 5600" }, "description": { "type": "string", "description": "Hotel description", "example": "Set just steps from the old harbour, in one of the most sought-after quarters of central Porto..." }, "image_url": { "type": "string", "description": "URL of the hotel's primary image", "example": "https://media-cdn.tripadvisor.com/media/photo-o/30/28/6c/86/caption.jpg" }, "images": { "type": "array", "description": "URLs of further hotel photos", "items": { "type": "string" } }, "lat": { "type": "number", "description": "Latitude", "example": 38.707397 }, "lng": { "type": "number", "description": "Longitude", "example": -9.142318 }, "price_level": { "type": "string", "description": "Indicator of the price tier" }, "categories": { "type": "array", "description": "Hotel categories", "items": { "type": "string" }, "example": [ "Hotel" ] } } }, "PlaceItem": { "type": "object", "description": "Information about a place or location in general", "properties": { "name": { "type": "string", "description": "Place name", "example": "Jardim do Miradouro" }, "url": { "type": "string", "description": "URL of the place's page", "example": "https://www.tripadvisor.com/Restaurant_Review-g189158-d1520116-Reviews-Floresta_Das_Escadinhas-Lisbon_District_Central_Portugal.html" }, "rating": { "type": "number", "description": "Rating of the place (0-5)", "example": 4.8 }, "address": { "type": "array", "description": "Address lines", "items": { "type": "string" }, "example": [ "Carrer de Mallorca 401, Barcelona 08013 Spain" ] }, "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": "Image URLs for the place", "items": { "type": "string" } } } }, "ShoppingCard": { "type": "object", "description": "Product card for shopping, with full product details", "properties": { "products": { "type": "array", "description": "List of products", "items": { "$ref": "#/components/schemas/ShoppingProduct" } }, "tags": { "type": "array", "description": "Category tags", "items": { "type": "string" }, "example": [ "electronics", "gadgets" ] } } }, "ImagePosition": { "type": "object", "description": "Image offset within a slot, in pixels", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] }, "SlotPlacement": { "type": "object", "description": "Where a showcase slot sits inside its container, in percentages", "properties": { "leftPercent": { "type": "number" }, "topPercent": { "type": "number" }, "widthPercent": { "type": "number" }, "heightPercent": { "type": "number" } } }, "ShowcaseSlot": { "type": "object", "description": "One visual slot within 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": "Main image displayed at the top of a product showcase", "properties": { "url": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "url" ] }, "ShowcaseBackground": { "type": "object", "description": "Background style applied to a product showcase", "properties": { "type": { "type": "string" }, "primary": { "type": "string" }, "secondary": { "type": "string" } } }, "ShowcaseMetadata": { "type": "object", "description": "Metadata for the visual display of a shopping product: its image, background, and placement in each slot.", "properties": { "image": { "$ref": "#/components/schemas/ShowcaseImage" }, "background": { "$ref": "#/components/schemas/ShowcaseBackground" }, "slots": { "type": "object", "description": "Map of slots, keyed by slot ID", "additionalProperties": { "$ref": "#/components/schemas/ShowcaseSlot" } }, "debug": { "type": "object", "description": "Unstructured debug metadata; clients should not parse it", "additionalProperties": true } } }, "ShoppingProduct": { "type": "object", "description": "Details for a single product", "properties": { "title": { "type": "string", "description": "Product name", "example": "Adidas Grand Court 2.0 Shoes" }, "position": { "type": "integer", "description": "Rank starting at 1, counted over every product in every shopping card of the response (one continuous sequence that does not restart for each card).", "example": 1 }, "url": { "type": "string", "description": "URL of the product page", "example": "https://www.amazon.in/Nike-Court-Vision-Shoes/dp/B098F6QPLK?utm_source=chatgpt.com" }, "description": { "type": "string", "description": "Product description", "example": "Lightweight trainer with a cushioned everyday sole" }, "price": { "type": "string", "description": "Current price", "example": "$79.99" }, "featured_tag": { "type": "string", "description": "Style or category tag for the product", "example": "cushioned everyday road shoe" }, "rating": { "type": "number", "description": "Rating of the product (0-5)", "example": 4.5 }, "num_reviews": { "type": "integer", "description": "Review count", "example": 8703 }, "image_urls": { "type": "array", "description": "URLs of the product images", "items": { "type": "string" } }, "id": { "type": "string", "description": "Product identifier", "example": "prod_12345" }, "variants": { "description": "Variants of the product (e.g. size or color)" }, "offers": { "type": "array", "description": "Offers from several merchants, each with price details", "items": { "$ref": "#/components/schemas/ShoppingOffer" } }, "rating_grouped_citation": { "$ref": "#/components/schemas/RatingGroupedCitation" }, "provider": { "type": "string", "description": "Identifier of the data provider", "example": "deprecated" }, "providers": { "type": "array", "description": "Array of data providers", "items": { "type": "string" }, "example": [ "product_info" ] }, "product_lookup_key": { "type": "object", "description": "Lookup key for fetching product updates", "properties": { "data": { "type": "string", "description": "Product lookup data, encoded as JSON" } } }, "product_lookup_data": { "type": "object", "description": "Query data for a structured product lookup", "properties": { "request_query": { "type": "string", "description": "Query used to search 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": "Indicates if a price disclosure should be displayed", "example": false }, "analytics_meta": { "type": "object", "description": "Analytics metadata", "properties": { "product_event_uuid": { "type": "string", "description": "Product analytics event UUID" } } }, "metadata_sources": { "type": "array", "description": "Where the product metadata comes from", "items": { "type": "string" }, "example": [ "p2" ] }, "product_event_uuid": { "type": "string", "description": "UUID used to track product events" }, "generatedProductQuery": { "type": "string", "description": "General shopping query that ChatGPT created for this product (taken from product_lookup_key.data). Shows the search intent that led to the recommendation.", "example": "best cordless vacuum uk 2026 lightweight pet hair stick vacuum" } } }, "ShoppingOffer": { "type": "object", "description": "Offer from one specific merchant, with price details", "properties": { "merchant_name": { "type": "string", "description": "Merchant name", "example": "Amazon.in" }, "merchant_subtitle": { "type": "string", "description": "Subtitle or extra details for the merchant", "nullable": true }, "product_name": { "type": "string", "description": "Product title as the merchant lists it", "example": "Adidas Men's Grand Court 2.0 Shoes" }, "url": { "type": "string", "description": "Offer link carrying 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": "Availability and delivery details", "example": "Available for pickup, Free shipping" }, "original_price": { "type": "string", "description": "Pre-discount price", "nullable": true }, "available": { "type": "boolean", "description": "Product availability flag", "example": true }, "checkoutable": { "type": "boolean", "description": "True if the product supports direct checkout", "example": false }, "is_digital": { "type": "boolean", "description": "True for digital goods", "nullable": true }, "checkout_payload": { "type": "string", "description": "Data carried in the checkout payload", "nullable": true }, "checkout_image_urls": { "type": "array", "description": "URLs of images shown at checkout", "items": { "type": "string" }, "nullable": true }, "shop_id": { "type": "string", "description": "Shop identifier", "nullable": true }, "provider": { "type": "string", "description": "Identifier of the data provider", "example": "p2" }, "price_details": { "$ref": "#/components/schemas/PriceDetails" }, "tag": { "$ref": "#/components/schemas/OfferTag" } } }, "PriceDetails": { "type": "object", "description": "Itemized breakdown of an offer's price", "properties": { "display_price": { "type": "string", "description": "Price formatted for display", "nullable": true }, "base": { "type": "string", "description": "Base price of the product", "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": "Promotion label attached to an offer", "properties": { "text": { "type": "string", "description": "Tag text", "example": "Best price" }, "tooltip": { "type": "string", "description": "Text of the tag's tooltip" } }, "nullable": true }, "RatingGroupedCitation": { "type": "object", "description": "Details about where the rating comes from, including supporting websites", "properties": { "title": { "type": "string", "description": "Source title", "example": "Adidas Men's Grand Court 2.0 Shoes" }, "url": { "type": "string", "description": "Source URL", "example": "https://www.amazon.in/dp/B098F6QPLK" }, "supporting_websites": { "type": "array", "description": "Websites cited in support", "items": { "type": "object" } } } }, "InlineProduct": { "type": "object", "description": "Product mentioned inline in the response text, with prices and offers", "properties": { "product": { "$ref": "#/components/schemas/ShoppingProduct" }, "render_as": { "type": "string", "description": "Way the product is displayed in the response", "enum": [ "inline", "hero", "block" ], "example": "hero" }, "details": { "type": "object", "description": "Product reasoning and reviews loaded from the sidebar API", "properties": { "rationale": { "type": "object", "properties": { "rationale": { "type": "string", "description": "Explanation the AI gave for suggesting this product" }, "citations": { "type": "array", "description": "Sources cited in support of the rationale", "items": { "type": "object" } } } }, "reviews": { "type": "object", "properties": { "summary": { "type": "string", "description": "Overview of what product reviews say" }, "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/ProductReview" } } } } } } } }, "ProductReview": { "type": "object", "description": "A single product review taken from the sources", "properties": { "source": { "type": "string", "description": "Review source", "example": "Amazon" }, "theme": { "type": "string", "description": "Aspect or theme the review covers", "example": "Setup and handling" }, "summary": { "type": "string", "description": "Text summarizing the reviews" }, "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": "Review count reported by the source", "nullable": true }, "cite_url": { "type": "string", "description": "Citation URL", "nullable": true } } }, "StateParameter": { "description": "State code for targeting below the country level (e.g., \"CA\"; \"DC\" included). Allowed only when country is \"US\". Served for Gemini; on a model that cannot place a state yet, a request that includes it is rejected as a validation error and is not charged.", "type": "string", "example": "CA", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$" }, "GlParameter": { "description": "Google's own name for the result-geography parameter, usable in place of `country`. Takes ISO 3166-1 alpha-2 codes, as `country` does, in upper or lower case (`us` or `US`), and the country has to be one this endpoint supports (list them with `GET /v1/countries`). Send either `country` or `gl`; if both are sent with differing values, the request fails with `400`.", "type": "string", "example": "us" }, "HlParameter": { "description": "Interface language, in the format of Google's `hl` parameter (for example `en`, `de`, `pt-BR`). Case-insensitive free text; Google defines which codes exist. Takes precedence over the language Answerline infers from the country, which lets interface language and result geography differ.", "type": "string", "example": "en" }, "RateLimitError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "message": { "type": "string", "example": "Too many requests for this API key" }, "timestamp": { "type": "string", "format": "date-time", "example": "2025-01-15T12:00:00.000Z" } } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Answerline API key sent as a bearer token. A single key gives access to all endpoints in this spec; keys cannot be scoped, so clients have no way to ask for narrower permissions. Create, rotate, and revoke keys at https://dashboard.answerline.dev/keys. See https://answerline.dev/docs/authentication for more, which also covers the versioning and deprecation policy." } }, "headers": { "XRateLimitLimit": { "description": "Number of requests permitted in the current window.", "schema": { "type": "integer", "example": 1000 } }, "XRateLimitRemaining": { "description": "Number of requests remaining in the current window.", "schema": { "type": "integer", "example": 997 } } } } }