{ "openapi": "3.1.0", "info": { "title": "Massive", "description": "The missing services for agent-first development.", "version": "1.0.0" }, "servers": [{ "url": "https://render.joinmassive.com" }], "security": [{ "bearerAuth": [] }], "paths": { "/search": { "get": { "summary": "Results", "description": "Retrieve search results or queue a search for later retrieval.", "parameters": [ { "name": "id", "description": "The identifier returned by this endpoint of the queued search to retrieve; if given, all other params are ignored; either an ID or terms are required.", "schema": { "type": "string", "format": "uuid", "example": "078fd246-f0f7-44a0-aabb-cadd7b12454f" }, "in": "query" }, { "name": "terms", "description": "The broad or exact word or phrase to query (e.g., `foo bar baz` or `\"foo bar baz\"`); the terms require [form or URL encoding](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding) (with any space character being replaced by a `+` character or `%20` sequence); either terms or an ID are required.", "schema": { "type": "string", "maxLength": 255, "example": "foo bar baz" }, "in": "query" }, { "name": "engine", "description": "The search engine to use.", "schema": { "type": "string", "enum": ["google", "bing (coming soon)"], "default": "google", "example": "google" }, "in": "query" }, { "name": "serps", "description": "The number of results pages to fetch.", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "example": 1 }, "in": "query" }, { "name": "size", "description": "The number of results per page to fetch; page size is unset by default.", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "example": null }, "in": "query" }, { "name": "offset", "description": "The number of initial results to skip; results aren’t offset by default.", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "example": null }, "in": "query" }, { "name": "device", "description": "The name as returned by the [devices resource](search/devices) of the device to emulate searching on (these names are case insensitive but must include form- or URL-encoded spaces and punctuation marks); device emulation is unused by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "country", "description": "The [two-letter ISO code](https://www.iso.org/obp/ui/#search/code) of the country to search from (these codes are case insensitive); a random country is used by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "subdivision", "description": "The alphanumeric second part (proceeding the separator) of a [first-level subdivision code](https://www.iso.org/obp/ui/#search/code) in the (prerequisite) country to search from (these codes are case insensitive); a random subdivision is used by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "city", "description": "The [commonly spelled name](https://www.geonames.org/) of the city in the (prerequisite) country to search from (these names are temporarily case sensitive and required to include form- or URL-encoded spaces and punctuation marks); a random city is used by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "uule", "description": "The [proprietary encoded string](https://moz.com/blog/geolocation-the-ultimate-tip-to-emulate-local-search) for emulating the location to search from; if possible, the actual location is searched from not emulated; location emulation is unused by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "language", "description": "The commonly spelled name, [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php), or [Google code](https://www.google.com/advanced_search) of the language to search in (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the language is unset by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "display", "description": "The commonly spelled name, [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php), or [Google code](https://www.google.com/advanced_search) of the search interface’s display language (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the display language is unset by default or set to the language if given.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "url", "description": "The encoded URL of the results page to retrieve; if given, the URL overrides any of the above params.", "schema": { "type": "string", "format": "uri", "maxLength": 2047, "example": "https%3A%2F%2Fwww.google.com%2Fsearch%3Fq%3Dfoo%2Bbar%2Bbaz%26hl%3Dfr%26gl%3Dfr%26ie%3DUTF-8" }, "in": "query" }, { "name": "awaiting", "description": "The lazy result features to wait to load; any AI overview, which can take significant time to generate, is awaited for a maximum of **1 minute**; multiple features can be provided by repeating the key; lazy results aren’t awaited by default.", "schema": { "type": "string", "enum": ["ai", "answers", "ads"], "example": "ai" }, "in": "query" }, { "name": "expiration", "description": "The age in days of when to consider cached results expired, where `0` disables caching.", "schema": { "type": "integer", "minimum": 0, "maximum": 1, "default": 1, "example": 0 }, "in": "query" }, { "name": "mode", "description": "The synchronous or asynchronous mode of results retrieval (retrieve async results by providing the returned ID).", "schema": { "$ref": "#/components/schemas/Mode" }, "in": "query" }, { "name": "callback", "description": "The encoded HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN to notify when the (prerequisite) async results have been retrieved; any SQS queue must grant `sqs:SendMessage` permission to the `arn:aws:iam::180363035301:role/api-instance` AWS principal.", "schema": { "type": "string", "maxLength": 2047, "example": "https%3A%2F%2Fwebhook.site%2F02e249f8-1faf-4fab-bcf5-78ce683e85a8" }, "in": "query" } ], "responses": { "200": { "description": "The search results.", "content": { "text/html": { "schema": { "type": "string" } } } }, "202": { "description": "A job identifier or the search status.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "description": "The identifier to retrieve the queued search with.", "type": "string", "format": "uuid", "example": "078fd246-f0f7-44a0-aabb-cadd7b12454f" } }, "required": ["id"] }, { "type": "object", "properties": { "status": { "description": "The status of the queued search.", "allOf": [{ "$ref": "#/components/schemas/Status" }] } }, "required": ["status"] } ] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "402": { "$ref": "#/components/responses/creditsError" }, "422": { "$ref": "#/components/responses/paramsError" }, "504": { "$ref": "#/components/responses/timeoutError" }, "403": { "$ref": "#/components/responses/captchaError" }, "503": { "$ref": "#/components/responses/unavailableError" }, "500": { "$ref": "#/components/responses/unknownError" } } } }, "/search/results": { "get": { "summary": "Async results", "description": "Retrieve the results or status of a queued search – use `GET /search?id=...`.", "parameters": [ { "name": "id", "description": "The identifier returned by the [search endpoint](../search) of the queued search to retrieve.", "schema": { "type": "string", "format": "uuid", "example": "078fd246-f0f7-44a0-aabb-cadd7b12454f" }, "in": "query", "required": true } ], "responses": { "200": { "description": "The search results or status.", "content": { "text/html": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "The status of the queued search.", "allOf": [{ "$ref": "#/components/schemas/Status" }] } }, "required": ["status"] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "402": { "$ref": "#/components/responses/creditsError" }, "422": { "$ref": "#/components/responses/paramsError" }, "500": { "$ref": "#/components/responses/unknownError" } }, "deprecated": true } }, "/search/batches": { "post": { "summary": "Batch results", "description": "Queue multiple searches for later retrieval.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "terms": { "description": "The broad or exact words or phrases to query (e.g., `foo bar baz` or `\"foo bar baz\"`).", "type": "array", "items": { "type": "string", "maxLength": 255 }, "minItems": 1, "maxItems": 1000, "example": ["foo bar baz"] }, "engine": { "description": "The search engine to use.", "type": "string", "enum": ["google", "bing (coming soon)"], "default": "google", "example": "google" }, "serps": { "description": "The number of results pages to fetch.", "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "example": 1 }, "size": { "description": "The number of results per page to fetch; page size is unset by default.", "type": "integer", "minimum": 0, "maximum": 100, "example": null }, "offset": { "description": "The number of initial results to skip; results aren’t offset by default.", "type": "integer", "minimum": 0, "maximum": 100, "example": null }, "device": { "description": "The name as returned by the [devices resource](devices) of the device to emulate searching on (these names are case insensitive); device emulation is unused by default.", "type": "string", "example": null }, "country": { "description": "The [two-letter ISO code](https://www.iso.org/obp/ui/#search/code) of the country to search from (these codes are case insensitive); a random country is used by default.", "type": "string", "example": null }, "subdivision": { "description": "The alphanumeric second part (proceeding the separator) of a [first-level subdivision code](https://www.iso.org/obp/ui/#search/code) in the (prerequisite) country to search from (these codes are case insensitive); a random subdivision is used by default.", "type": "string", "example": null }, "city": { "description": "The [commonly spelled name](https://www.geonames.org/) of the city in the (prerequisite) country to search from (these names are temporarily case sensitive); a random city is used by default.", "type": "string", "example": null }, "uule": { "description": "The [proprietary encoded string](https://moz.com/blog/geolocation-the-ultimate-tip-to-emulate-local-search) for emulating the location to search from; if possible, the actual location is searched from not emulated; location emulation is unused by default.", "type": "string", "example": null }, "language": { "description": "The commonly spelled name, [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php), or [Google code](https://www.google.com/advanced_search) of the language to search in (these names and codes are case insensitive); the language is unset by default.", "type": "string", "example": null }, "display": { "description": "The commonly spelled name, [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php), or [Google code](https://www.google.com/advanced_search) of the search interface’s display language (these names and codes are case insensitive); the display language is unset by default or set to the language if given.", "type": "string", "example": null }, "urls": { "description": "The URLs of the results pages to retrieve; if given, the URLs override any of the above params.", "type": "array", "items": { "type": "string", "format": "uri", "maxLength": 2047 }, "minItems": 1, "maxItems": 1000, "example": ["https://www.google.com/search?q=foo+bar+baz&hl=fr&gl=fr&ie=UTF-8"] }, "awaiting": { "description": "The lazy result features to wait to load; any AI overview, which can take significant time to generate, is awaited for a maximum of **1 minute**; multiple features can be provided by repeating the key; lazy results aren’t awaited by default.", "type": "string", "enum": ["ai", "answers", "ads"], "example": "ai" }, "expiration": { "description": "The age in days of when to consider cached results expired, where `0` disables caching.", "type": "integer", "minimum": 0, "maximum": 1, "default": 1, "example": 0 }, "callback": { "description": "The HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN to notify when the batch results have been retrieved; any SQS queue must grant `sqs:SendMessage` permission to the `arn:aws:iam::180363035301:role/api-instance` AWS principal.", "type": "string", "maxLength": 2047, "example": "https://webhook.site/02e249f8-1faf-4fab-bcf5-78ce683e85a8" } }, "anyOf": [{ "required": ["terms"] }, { "required": ["urls"] }] } } }, "required": true }, "responses": { "202": { "description": "A job identifier and confirmation count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The identifier to retrieve the batch searches with.", "type": "string", "format": "uuid", "example": "a0482596-c2ad-445a-a435-727002156a20" }, "count": { "description": "The number of queries in the batch as confirmed by the API.", "type": "integer", "minimum": 1, "maximum": 1000, "example": 1 } }, "required": ["id", "count"] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "402": { "$ref": "#/components/responses/creditsError" }, "422": { "$ref": "#/components/responses/paramsError" }, "500": { "$ref": "#/components/responses/unknownError" } } }, "get": { "summary": "Batch results", "description": "Retrieve the status of batch searches.", "parameters": [ { "name": "id", "description": "The identifier returned by the [batch search endpoint](../batching) of the bulk searches to retrieve.", "schema": { "type": "string", "format": "uuid", "example": "a0482596-c2ad-445a-a435-727002156a20" }, "in": "query", "required": true } ], "responses": { "200": { "description": "The batch status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchStatus" } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "402": { "$ref": "#/components/responses/creditsError" }, "422": { "$ref": "#/components/responses/paramsError" }, "500": { "$ref": "#/components/responses/unknownError" } } } }, "/search/devices": { "get": { "summary": "Devices", "description": "Retrieve supported device names.", "responses": { "200": { "description": "The device names.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" }, "example": [ "Blackberry PlayBook", "Blackberry PlayBook landscape", "BlackBerry Z30", "" ] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "402": { "$ref": "#/components/responses/creditsError" } } } }, "/ai": { "get": { "summary": "Completion", "description": "Retrieve an LLM completion or queue a conversation for later retrieval.", "parameters": [ { "name": "id", "description": "The identifier returned by this endpoint of the queued conversation to retrieve; if given, all other params are ignored; either an ID or prompt is required.", "schema": { "type": "string", "format": "uuid", "example": "1851dab8-4619-409f-893f-47dd3a180bc3" }, "in": "query" }, { "name": "prompt", "description": "The question or instruction to use as a chat prompt; the prompt requires [form or URL encoding](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding) (with any space character being replaced by a `+` character or `%20` sequence); either a prompt or ID is required.", "schema": { "type": "string", "maxLength": 2047, "example": "best basketball shoes for 2026" }, "in": "query" }, { "name": "model", "description": "The AI model to chat with.", "schema": { "type": "string", "enum": ["chatgpt", "gemini", "perplexity"], "default": "chatgpt", "example": "gemini" }, "in": "query" }, { "name": "device", "description": "The name as returned by the [devices resource](ai/devices) of the device to emulate chatting on (these names are case insensitive but must include form- or URL-encoded spaces and punctuation marks); device emulation is unused by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "country", "description": "The [two-letter ISO code](https://www.iso.org/obp/ui/#search/code) of the country to chat from (these codes are case insensitive); a random country is used by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "subdivision", "description": "The alphanumeric second part (proceeding the separator) of a [first-level subdivision code](https://www.iso.org/obp/ui/#search/code) in the (prerequisite) country to chat from (these codes are case insensitive); a random subdivision is used by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "city", "description": "The [commonly spelled name](https://www.geonames.org/) of the city in the (prerequisite) country to chat from (these names are temporarily case sensitive and required to include form- or URL-encoded spaces and punctuation marks); a random city is used by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "language", "description": "[Planned] The commonly spelled name or [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php) of the language to chat in (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the language is unset by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "display", "description": "[Planned] The commonly spelled name or [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php) of the chat interface’s display language (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the display language is unset by default or set to the language if given.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "format", "description": "The format to output to.", "schema": { "type": "string", "enum": ["json", "rendered", "raw (planned)"], "default": "json", "example": "rendered" }, "in": "query" }, { "name": "expiration", "description": "The age in days of when to consider a cached completion expired, where `0` disables caching.", "schema": { "type": "integer", "minimum": 0, "maximum": 1, "default": 1, "example": 0 }, "in": "query" }, { "name": "mode", "description": "The synchronous or asynchronous mode of completion retrieval (retrieve an async completion by providing the returned ID).", "schema": { "$ref": "#/components/schemas/Mode" }, "in": "query" }, { "name": "callback", "description": "The encoded HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN to notify when the (prerequisite) async completion has been retrieved; any SQS queue must grant `sqs:SendMessage` permission to the `arn:aws:iam::180363035301:role/api-instance` AWS principal.", "schema": { "type": "string", "maxLength": 2047, "example": "https%3A%2F%2Fwebhook.site%2F02e249f8-1faf-4fab-bcf5-78ce683e85a8" }, "in": "query" } ], "responses": { "200": { "description": "The AI completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Completion" } }, "text/html": { "schema": { "type": "string" } } } }, "202": { "description": "A job identifier or the conversation status.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "description": "The identifier to retrieve the queued conversation with.", "type": "string", "format": "uuid", "example": "1851dab8-4619-409f-893f-47dd3a180bc3" } }, "required": ["id"] }, { "type": "object", "properties": { "status": { "description": "The status of the queued conversation.", "allOf": [{ "$ref": "#/components/schemas/Status" }] } }, "required": ["status"] } ] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "402": { "$ref": "#/components/responses/creditsError" }, "422": { "$ref": "#/components/responses/paramsError" }, "504": { "$ref": "#/components/responses/timeoutError" }, "403": { "$ref": "#/components/responses/captchaError" }, "503": { "$ref": "#/components/responses/unavailableError" }, "500": { "$ref": "#/components/responses/unknownError" } } } }, "/ai/completions": { "get": { "summary": "Async completion", "description": "Retrieve the completion or status of a queued conversation – use `GET /ai?id=...`.", "parameters": [ { "name": "id", "description": "The identifier returned by the [AI endpoint](../ai) of the queued conversation to retrieve.", "schema": { "type": "string", "format": "uuid", "example": "1851dab8-4619-409f-893f-47dd3a180bc3" }, "in": "query", "required": true } ], "responses": { "200": { "description": "The AI completion or status.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Completion" }, { "type": "object", "properties": { "status": { "description": "The status of the queued conversation.", "allOf": [{ "$ref": "#/components/schemas/Status" }] } }, "required": ["status"] } ] } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "402": { "$ref": "#/components/responses/creditsError" }, "422": { "$ref": "#/components/responses/paramsError" }, "500": { "$ref": "#/components/responses/unknownError" } }, "deprecated": true } }, "/ai/batches": { "post": { "summary": "Batch completions", "description": "Queue multiple LLM conversations for later retrieval.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "prompts": { "description": "The questions or instructions to use as chat prompts.", "type": "array", "items": { "type": "string", "maxLength": 2047 }, "minItems": 1, "maxItems": 1000, "example": [ "Where can I buy a vintage guitar?", "Help me find guitar repair shops nearby.", "Do any local stores sell vinyl records?", "[Additional prompts here]" ] }, "model": { "description": "The AI model to chat with.", "type": "string", "enum": ["chatgpt", "gemini", "perplexity"], "default": "chatgpt", "example": "gemini" }, "device": { "description": "The name as returned by the [devices resource](devices) of the device to emulate chatting on (these names are case insensitive but must include form- or URL-encoded spaces and punctuation marks); device emulation is unused by default.", "type": "string", "example": null }, "country": { "description": "The [two-letter ISO code](https://www.iso.org/obp/ui/#search/code) of the country to chat from (these codes are case insensitive); a random country is used by default.", "type": "string", "example": null }, "subdivision": { "description": "The alphanumeric second part (proceeding the separator) of a [first-level subdivision code](https://www.iso.org/obp/ui/#search/code) in the (prerequisite) country to chat from (these codes are case insensitive); a random subdivision is used by default.", "type": "string", "example": null }, "city": { "description": "The [commonly spelled name](https://www.geonames.org/) of the city in the (prerequisite) country to chat from (these names are temporarily case sensitive and required to include form- or URL-encoded spaces and punctuation marks); a random city is used by default.", "type": "string", "example": null }, "language": { "description": "[Planned] The commonly spelled name or [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php) of the language to chat in (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the language is unset by default.", "type": "string", "example": null }, "display": { "description": "[Planned] The commonly spelled name or [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php) of the chat interface’s display language (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the display language is unset by default or set to the language if given.", "type": "string", "example": null }, "format": { "description": "The format to output to.", "type": "string", "enum": ["json", "rendered", "raw (planned)"], "default": "json", "example": "rendered" }, "expiration": { "description": "The age in days of when to consider a cached completion expired, where `0` disables caching.", "type": "integer", "minimum": 0, "maximum": 1, "default": 1, "example": 0 }, "callback": { "description": "The HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN to notify when the batch completions have been retrieved; any SQS queue must grant `sqs:SendMessage` permission to the `arn:aws:iam::180363035301:role/api-instance` AWS principal.", "type": "string", "maxLength": 2047, "example": "https://webhook.site/02e249f8-1faf-4fab-bcf5-78ce683e85a8" } }, "required": ["prompts"] } } }, "required": true }, "responses": { "202": { "description": "A job identifier and confirmation count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The identifier to retrieve the batch conversations with.", "type": "string", "format": "uuid", "example": "a0482596-c2ad-445a-a435-727002156a20" }, "count": { "description": "The number of prompts in the batch as confirmed by the API.", "type": "integer", "minimum": 1, "maximum": 1000, "example": 37 } }, "required": ["id", "count"] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "402": { "$ref": "#/components/responses/creditsError" }, "422": { "$ref": "#/components/responses/paramsError" }, "500": { "$ref": "#/components/responses/unknownError" } } }, "get": { "summary": "Batch completions", "description": "Retrieve the status of batch conversations.", "parameters": [ { "name": "id", "description": "The identifier returned by the [batch AI endpoint](../batching) of the bulk conversations to retrieve.", "schema": { "type": "string", "format": "uuid", "example": "a0482596-c2ad-445a-a435-727002156a20" }, "in": "query", "required": true } ], "responses": { "200": { "description": "The batch status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchStatus" } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "402": { "$ref": "#/components/responses/creditsError" }, "422": { "$ref": "#/components/responses/paramsError" }, "500": { "$ref": "#/components/responses/unknownError" } } } }, "/ai/devices": { "get": { "summary": "Devices", "description": "Retrieve supported device names.", "responses": { "200": { "description": "The device names.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" }, "example": [ "Blackberry PlayBook", "Blackberry PlayBook landscape", "BlackBerry Z30", "" ] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "402": { "$ref": "#/components/responses/creditsError" } } } }, "/browser": { "get": { "summary": "Content", "description": "Retrieve web content or queue a request for later retrieval; connect to `wss://render.joinmassive.com/browser` for CDP interaction.", "x-websocket": { "url": "wss://render.joinmassive.com/browser", "protocol": "Chrome DevTools Protocol", "description": "Interact with webpages by connecting Puppeteer, Playwright, or another CDP-compatible automation framework." }, "parameters": [ { "name": "id", "description": "The identifier returned by this endpoint of the queued request to retrieve; if given, all other params are ignored; either an ID or URL is required.", "schema": { "type": "string", "format": "uuid", "example": "21cb972e-0e0f-47bb-9ce9-65b99e9cee77" }, "in": "query" }, { "name": "url", "description": "The URL of the page to browse; any unsafe characters require [URL encoding](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding); either a URL or ID is required.", "schema": { "type": "string", "format": "uri", "maxLength": 2047, "example": "https://example.com/" }, "in": "query" }, { "name": "difficulty", "description": "The difficulty pool to attempt to access the URL from.", "schema": { "type": "string", "enum": ["low", "medium", "high"], "default": "low", "example": "low" }, "in": "query" }, { "name": "speed", "description": "The speed to attempt to access the URL at, where `ridiculous` is 30 percent faster on average than `light` speed.", "schema": { "type": "string", "enum": ["light", "ridiculous", "ludicrous (planned)"], "default": "light", "example": "light" }, "in": "query" }, { "name": "device", "description": "The name as returned by the [devices resource](browser/devices) of the device to emulate browsing on (these names are case insensitive but must include form- or URL-encoded spaces and punctuation marks); device emulation is unused by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "country", "description": "The [two-letter ISO code](https://www.iso.org/obp/ui/#search/code) of the country to browse from (these codes are case insensitive); a random country is used by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "subdivision", "description": "The alphanumeric second part (proceeding the separator) of a [first-level subdivision code](https://www.iso.org/obp/ui/#search/code) in the (prerequisite) country to browse from (these codes are case insensitive); a random subdivision is used by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "city", "description": "The [commonly spelled name](https://www.geonames.org/) of the city in the (prerequisite) country to browse from (these names are temporarily case sensitive and required to include form- or URL-encoded spaces and punctuation marks); a random city is used by default.", "schema": { "type": "string", "example": null }, "in": "query" }, { "name": "captcha", "description": "The intended resolution of any detected captcha, where `rejected` results in a `403` response.", "schema": { "type": "string", "enum": ["solved", "ignored", "rejected"], "default": "solved", "example": "rejected" }, "in": "query" }, { "name": "readiness", "description": "The standard ready event to await before snapshotting browsed content.", "schema": { "type": "string", "enum": ["load", "domcontentloaded"], "default": "load", "example": "load" }, "in": "query" }, { "name": "delay", "description": "The number of supplemental seconds to delay before snapshotting browsed content; no delay is used by default.", "schema": { "type": "number", "minimum": 0.1, "maximum": 10, "example": null }, "in": "query" }, { "name": "format", "description": "The format to output to.", "schema": { "type": "string", "enum": ["rendered", "raw", "markdown"], "default": "rendered", "example": "markdown" }, "in": "query" }, { "name": "expiration", "description": "The age in days of when to consider cached content expired, where `0` disables caching.", "schema": { "type": "integer", "minimum": 0, "maximum": 1, "default": 1, "example": 0 }, "in": "query" }, { "name": "mode", "description": "The synchronous or asynchronous mode of content retrieval (retrieve async content by providing the returned ID).", "schema": { "$ref": "#/components/schemas/Mode" }, "in": "query" }, { "name": "callback", "description": "The encoded HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN to notify when the (prerequisite) async content has been retrieved; any SQS queue must grant `sqs:SendMessage` permission to the `arn:aws:iam::180363035301:role/api-instance` AWS principal.", "schema": { "type": "string", "maxLength": 2047, "example": "https%3A%2F%2Fwebhook.site%2F02e249f8-1faf-4fab-bcf5-78ce683e85a8" }, "in": "query" } ], "responses": { "200": { "description": "The page content.", "content": { "text/html": { "schema": { "type": "string" } } } }, "202": { "description": "A job identifier or the request status.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "description": "The identifier to retrieve the queued request with.", "type": "string", "format": "uuid", "example": "21cb972e-0e0f-47bb-9ce9-65b99e9cee77" } }, "required": ["id"] }, { "type": "object", "properties": { "status": { "description": "The status of the queued request.", "allOf": [{ "$ref": "#/components/schemas/Status" }] } }, "required": ["status"] } ] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "402": { "$ref": "#/components/responses/creditsError" }, "422": { "$ref": "#/components/responses/paramsError" }, "429": { "$ref": "#/components/responses/throttlingError" }, "504": { "$ref": "#/components/responses/timeoutError" }, "403": { "$ref": "#/components/responses/captchaError" }, "404": { "$ref": "#/components/responses/unsupportedError" }, "503": { "$ref": "#/components/responses/unavailableError" }, "500": { "$ref": "#/components/responses/unknownError" } } } }, "/browser/content": { "get": { "summary": "Async content", "description": "Retrieve the content or status of a queued request – use `GET /browser?id=...`.", "parameters": [ { "name": "id", "description": "The identifier returned by the [browser endpoint](../browser) of the queued request to retrieve.", "schema": { "type": "string", "format": "uuid", "example": "21cb972e-0e0f-47bb-9ce9-65b99e9cee77" }, "in": "query", "required": true } ], "responses": { "200": { "description": "The request content or status.", "content": { "text/html": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "The status of the queued request.", "allOf": [{ "$ref": "#/components/schemas/Status" }] } }, "required": ["status"] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "402": { "$ref": "#/components/responses/creditsError" }, "422": { "$ref": "#/components/responses/paramsError" }, "500": { "$ref": "#/components/responses/unknownError" } }, "deprecated": true } }, "/browser/batches": { "post": { "summary": "Batch content", "description": "Queue multiple web requests for later retrieval.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "urls": { "description": "The URLs of the pages to browse.", "type": "array", "items": { "type": "string", "format": "uri", "maxLength": 2047 }, "minItems": 1, "maxItems": 1000, "example": [ "https://guitars.com/", "https://cartervintage.com/", "https://musiccityvintageguitars.com/", "[Additional URLs here]" ] }, "difficulty": { "description": "The difficulty pool to attempt to access the URLs from.", "type": "string", "enum": ["low", "medium", "high"], "default": "low", "example": "low" }, "speed": { "description": "The speed to attempt to access the URLs at, where `ridiculous` is 30 percent faster on average than `light` speed.", "type": "string", "enum": ["light", "ridiculous", "ludicrous (planned)"], "default": "light", "example": "light" }, "device": { "description": "The name as returned by the [devices resource](devices) of the device to emulate browsing on (these names are case insensitive); device emulation is unused by default.", "type": "string", "example": null }, "country": { "description": "The [two-letter ISO code](https://www.iso.org/obp/ui/#search/code) of the country to browse from (these codes are case insensitive); a random country is used by default.", "type": "string", "example": null }, "subdivision": { "description": "The alphanumeric second part (proceeding the separator) of a [first-level subdivision code](https://www.iso.org/obp/ui/#search/code) in the (prerequisite) country to browse from (these codes are case insensitive); a random subdivision is used by default.", "type": "string", "example": null }, "city": { "description": "The [commonly spelled name](https://www.geonames.org/) of the city in the (prerequisite) country to browse from (these names are temporarily case sensitive); a random city is used by default.", "type": "string", "example": null }, "captcha": { "description": "The intended resolution of any detected captcha, where `rejected` results in a `403` response.", "type": "string", "enum": ["solved", "ignored", "rejected"], "default": "solved", "example": "rejected" }, "readiness": { "description": "The standard ready event to await before snapshotting browsed content.", "type": "string", "enum": ["load", "domcontentloaded"], "default": "load", "example": "load" }, "delay": { "description": "The number of supplemental seconds to delay before snapshotting browsed content; no delay is used by default.", "type": "number", "minimum": 0.1, "maximum": 10, "example": null }, "format": { "description": "The format to output to.", "type": "string", "enum": ["rendered", "raw", "markdown"], "default": "rendered", "example": "markdown" }, "expiration": { "description": "The age in days of when to consider cached content expired, where `0` disables caching.", "type": "integer", "minimum": 0, "maximum": 1, "default": 1, "example": 0 }, "callback": { "description": "The HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN to notify when the batch content has been retrieved; any SQS queue must grant `sqs:SendMessage` permission to the `arn:aws:iam::180363035301:role/api-instance` AWS principal.", "type": "string", "maxLength": 2047, "example": "https://webhook.site/02e249f8-1faf-4fab-bcf5-78ce683e85a8" } }, "required": ["urls"] } } }, "required": true }, "responses": { "202": { "description": "A job identifier and confirmation count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The identifier to retrieve the batch content with.", "type": "string", "format": "uuid", "example": "a0482596-c2ad-445a-a435-727002156a20" }, "count": { "description": "The number of requests in the batch as confirmed by the API.", "type": "integer", "minimum": 1, "maximum": 1000, "example": 37 } }, "required": ["id", "count"] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "402": { "$ref": "#/components/responses/creditsError" }, "422": { "$ref": "#/components/responses/paramsError" }, "500": { "$ref": "#/components/responses/unknownError" } } }, "get": { "summary": "Batch content", "description": "Retrieve the status of batch requests.", "parameters": [ { "name": "id", "description": "The identifier returned by the [batch browser endpoint](../batching) of the bulk requests to retrieve.", "schema": { "type": "string", "format": "uuid", "example": "a0482596-c2ad-445a-a435-727002156a20" }, "in": "query", "required": true } ], "responses": { "200": { "description": "The batch status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchStatus" } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "402": { "$ref": "#/components/responses/creditsError" }, "422": { "$ref": "#/components/responses/paramsError" }, "500": { "$ref": "#/components/responses/unknownError" } } } }, "/browser/devices": { "get": { "summary": "Devices", "description": "Retrieve supported device names.", "responses": { "200": { "description": "The device names.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" }, "example": [ "Blackberry PlayBook", "Blackberry PlayBook landscape", "BlackBerry Z30", "" ] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "402": { "$ref": "#/components/responses/creditsError" } } } }, "/users": { "post": { "summary": "New user", "description": "Create a whitelabel account.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "description": "The email address of the user to create an account for; the address is case insensitive and can be in any character encoding.", "type": "string", "format": "email", "maxLength": 255, "example": "user@example.com" }, "credits": { "description": "The number of API credits to preload the account with.", "type": "integer", "example": 1000 } }, "required": ["email"] } } }, "required": true }, "responses": { "201": { "description": "The new account metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "description": "The email address of the new account as recorded by the API.", "type": "string", "format": "email", "example": "user@example.com" }, "token": { "description": "The bearer token issued to the account for authentication.", "type": "string", "example": "a1-0dF6qKHYD7SNU5kAtjOmwHpH3iFgpylA" }, "credits": { "description": "The number of initial credits granted to the account.", "type": "integer", "example": 1000 } }, "required": ["email", "token", "credits"] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "400": { "$ref": "#/components/responses/malformedError" }, "422": { "$ref": "#/components/responses/paramsError" }, "409": { "$ref": "#/components/responses/conflictError" }, "429": { "$ref": "#/components/responses/throttlingError" }, "500": { "$ref": "#/components/responses/unknownError" } } }, "get": { "summary": "Credit balances", "description": "Retrieve the settings and credits of one or more accounts.", "parameters": [ { "name": "email", "description": "The (case-insensitive) email address of the user whose profile to fetch; multiple addresses can be provided by repeating the key; profiles for all addresses are fetched by default.", "schema": { "type": "array", "items": { "type": "string", "format": "email", "example": "user@example.com" } }, "in": "query" } ], "responses": { "200": { "description": "The account settings and credits.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "email": { "description": "The account email address.", "type": "string", "format": "email", "example": "user@example.com" }, "credits": { "description": "The number of remaining API credits allocated to the account.", "type": "integer", "example": 1000 } }, "required": ["email", "credits"] } } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "429": { "$ref": "#/components/responses/throttlingError" }, "500": { "$ref": "#/components/responses/unknownError" } } }, "patch": { "summary": "Credit grant", "description": "Allocate credits to an account.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "description": "The (case-insensitive) email address of the user whose account to grant credits.", "type": "string", "format": "email", "example": "user@example.com" }, "amount": { "description": "The number of additional API credits to grant the account.", "type": "integer", "example": 1000 } }, "required": ["email", "amount"] } } }, "required": true }, "responses": { "200": { "description": "The updated account credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "description": "The account email address.", "type": "string", "format": "email", "example": "user@example.com" }, "credits": { "description": "The number of updated API credits allocated to the account.", "type": "integer", "example": 1000 } }, "required": ["email", "credits"] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "400": { "$ref": "#/components/responses/malformedError" }, "422": { "$ref": "#/components/responses/paramsError" }, "429": { "$ref": "#/components/responses/throttlingError" }, "404": { "$ref": "#/components/responses/unsupportedError" }, "500": { "$ref": "#/components/responses/unknownError" } } }, "delete": { "summary": "User deactivation", "description": "Disable an account.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "description": "The (case-insensitive) email address of the user whose account to deactivate.", "type": "string", "format": "email", "example": "user@example.com" } }, "required": ["email"] } } }, "required": true }, "responses": { "200": { "description": "The confirmed account credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "description": "The account email address.", "type": "string", "format": "email", "example": "user@example.com" }, "credits": { "description": "The zeroed-out credits as confirmed by the API.", "type": "integer", "example": 0 } }, "required": ["email", "credits"] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "400": { "$ref": "#/components/responses/malformedError" }, "422": { "$ref": "#/components/responses/paramsError" }, "429": { "$ref": "#/components/responses/throttlingError" }, "404": { "$ref": "#/components/responses/unsupportedError" }, "500": { "$ref": "#/components/responses/unknownError" } } } }, "/user": { "get": { "summary": "Credit balance", "description": "Retrieve the settings and remaining credits of an account.", "responses": { "200": { "description": "The account settings and credits.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "email": { "description": "The account email address.", "type": "string", "format": "email", "example": "user@example.com" }, "credits": { "description": "The number of remaining credits allocated to the account.", "type": "integer", "example": 1000 } }, "required": ["email", "credits"] } } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "429": { "$ref": "#/components/responses/throttlingError" }, "500": { "$ref": "#/components/responses/unknownError" } } } }, "/usage": { "get": { "summary": "Usage data", "description": "Generate an hourly consumption report.", "parameters": [ { "name": "from", "description": "The [ISO datetime](https://www.w3.org/TR/NOTE-datetime) to select data starting from, inclusively.", "schema": { "type": "string", "format": "date-time", "example": "2025-12-24T18:00:00-06:00" }, "in": "query", "required": true }, { "name": "to", "description": "The [ISO datetime](https://www.w3.org/TR/NOTE-datetime) to select data up to, inclusively.", "schema": { "type": "string", "format": "date-time", "example": "2025-12-25T9:00:00-06:00" }, "in": "query", "required": true }, { "name": "email", "description": "**[Whitelabelers only]** The (case-insensitive) email address of the user whose data to select; multiple addresses can be provided by repeating the key; data for all addresses is selected by default.", "schema": { "type": "array", "items": { "type": "string", "format": "email", "example": "user@example.com" } }, "in": "query" }, { "name": "service", "description": "The service to select data for; multiple services can be provided by repeating the key; data for all services is selected by default.", "schema": { "$ref": "#/components/schemas/Services" }, "in": "query" }, { "name": "by", "description": "The time unit to group the data by.", "schema": { "type": "string", "enum": ["hour", "day (planned)", "total"], "default": "total", "example": "total" }, "in": "query" } ], "responses": { "200": { "description": "The hourly report.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "email": { "description": "The email address of the user whose data is selected.", "type": "string", "format": "email", "example": "user@example.com" }, "from": { "description": "The ISO datetime of the first datapoint.", "type": "string", "format": "date-time", "example": "2025-12-25T00:00:00+00:00" }, "to": { "description": "The ISO datetime of the last datapoint.", "type": "string", "format": "date-time", "example": "2025-12-25T15:00:00+00:00" }, "service": { "description": "The service included in the data.", "allOf": [{ "$ref": "#/components/schemas/Service" }] }, "result": { "description": "The type of result included in the data.", "type": "string", "enum": ["success", "failure"], "example": "success" }, "calls": { "description": "The number of API calls of the service and result type.", "type": "integer", "minimum": 1, "example": 17208 }, "credits": { "description": "The number of credits consumed by the API calls.", "type": "integer", "minimum": 0, "example": 17208 }, "meanSecs": { "description": "The average number of elapsed seconds of the API calls.", "type": "number", "minimum": 0, "example": 6.78 } }, "required": [ "email", "from", "to", "service", "result", "calls", "credits", "meanSecs" ] } } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, "422": { "$ref": "#/components/responses/paramsError" }, "429": { "$ref": "#/components/responses/throttlingError" }, "500": { "$ref": "#/components/responses/unknownError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Mode": { "summary": "Retrieval mode", "type": "string", "enum": ["sync", "async"], "default": "sync", "example": "sync" }, "Services": { "summary": "API services", "type": "array", "items": { "$ref": "#/components/schemas/Service" }, "minItems": 1, "example": ["search", "browser"] }, "Service": { "summary": "API service", "type": "string", "enum": ["search", "browser"], "example": "browser" }, "Results": { "summary": "Search results", "type": "object", "properties": { "engine": { "description": "The queried search engine.", "type": "string", "enum": ["google", "bing (coming soon)"], "example": "google" }, "terms": { "description": "The broad or exact query terms.", "type": "string", "example": "foo" }, "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Organic" }, { "$ref": "#/components/schemas/OrganicWithSitelinks" } ], "discriminator": { "propertyName": "type" } } }, "resultsCount": { "description": "The number of parsed results.", "type": "integer", "minimum": 0, "example": 43 }, "pageCount": { "description": "The number of retrieved results pages.", "type": "integer", "minimum": 1, "maximum": 10, "example": 1 }, "pageSize": { "description": "The number of retrieved results per page.", "type": "integer", "minimum": 0, "maximum": 100, "example": null }, "approxResultsCount": { "description": "The approximate number of indexed results.", "type": "integer", "minimum": 0, "example": 255000000 }, "resultsOffset": { "description": "The number of skipped initial results.", "type": "integer", "minimum": 0, "maximum": 100, "example": null }, "country": { "description": "The ISO code of the targeted country.", "type": "string", "example": null }, "subdivision": { "description": "The partial ISO code of the targeted subdivision in the country.", "type": "string", "example": null }, "city": { "description": "The common name of the targeted city in the country.", "type": "string", "example": null }, "uule": { "description": "The encoded string of the emulated location.", "type": "string", "example": null }, "language": { "description": "The common name, ISO code, or Google code of the targeted language.", "type": "string", "example": null }, "display": { "description": "The common name, ISO code, or Google code of the targeted display language.", "type": "string", "example": null } }, "required": ["engine", "terms", "results", "resultsCount", "pageCount"] }, "Organic": { "summary": "Organic result", "type": "object", "properties": { "type": { "type": "string", "enum": ["organic"], "example": "organic" }, "page": { "type": "integer", "minimum": 1, "maximum": 10, "example": 1 }, "section": { "$ref": "#/components/schemas/Section" }, "feature": { "type": "integer", "minimum": 1, "example": 1 }, "position": { "type": "integer", "minimum": 1, "example": 1 }, "url": { "type": "string", "format": "uri", "example": "https://foofighters.com/" }, "title": { "type": "string", "example": "Foo Fighters" }, "site": { "type": "string", "example": "Foo Fighters" }, "visibleUrl": { "type": "string", "format": "uri", "example": "https://foofighters.com" }, "date": { "type": "string", "nullable": true, "example": null }, "snippet": { "type": "string", "example": "Official website of Foo Fighters." }, "rating": { "type": "number", "minimum": 0, "maximum": 5, "nullable": true, "example": null }, "votes": { "type": "integer", "minimum": 0, "nullable": true, "example": null }, "sitelinks": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } } }, "required": [ "type", "page", "section", "feature", "position", "url", "title", "site", "visibleUrl", "date", "snippet", "rating", "votes", "sitelinks", "images" ] }, "OrganicWithSitelinks": { "summary": "Organic result with sitelinks", "type": "object", "properties": { "type": { "type": "string", "enum": ["organic-with-sitelinks"] }, "page": { "type": "integer", "minimum": 1, "maximum": 10 }, "section": { "$ref": "#/components/schemas/Section" }, "feature": { "type": "integer", "minimum": 1 }, "position": { "type": "integer", "minimum": 1 }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "site": { "type": "string" }, "visibleUrl": { "type": "string", "format": "uri" }, "snippet": { "type": "string" }, "sitelinks": { "type": "array", "items": { "$ref": "#/components/schemas/Sitelink" } } }, "required": [ "type", "page", "section", "feature", "position", "url", "title", "site", "visibleUrl", "snippet", "sitelinks" ] }, "Section": { "summary": "Result section", "type": "string", "enum": ["top", "left", "main", "bottom", "right"], "example": "main" }, "Link": { "summary": "Link element", "type": "object", "properties": { "position": { "type": "integer", "minimum": 1, "example": 1 }, "url": { "type": "string", "format": "uri", "example": "https://foofighters.com/tour-dates/" }, "title": { "type": "string", "example": "Tour Dates" } }, "required": ["position", "url", "title"] }, "Image": { "summary": "Image element", "type": "object", "properties": { "position": { "type": "integer", "minimum": 1, "example": 1 }, "source": { "type": "string", "example": "[Image data]" }, "altText": { "type": "string", "example": "foo from en.wikipedia.org" } }, "required": ["position", "source", "altText"] }, "Sitelink": { "summary": "Sitelink element", "type": "object", "properties": { "position": { "type": "integer", "minimum": 1 }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "snippet": { "type": "string" } }, "required": ["position", "url", "title", "snippet"] }, "Completion": { "summary": "AI completion", "type": "object", "properties": { "model": { "description": "The AI model that generated the completion.", "type": "string", "enum": ["chatgpt", "gemini", "perplexity"], "example": "chatgpt" }, "query": { "description": "The user prompt that the completion was generated for.", "type": "string", "example": "best basketball shoes for 2026" }, "html": { "description": "The rendered HTML of the entire conversation.", "type": "string", "example": "You said: ..." }, "completion": { "description": "The rendered HTML of just the completion portion of the conversation.", "type": "string", "example": "

ChatGPT said: ..." }, "sources": { "description": "The rendered HTML of just the sources portion of the conversation.", "type": "string", "example": "