Generative response
You can use Yandex Search API text search together with YandexGPT generative AI to get a comprehensive and concise generative response to a user query. To generate such a response, the model analyzes the relevant text search results retrieved by Yandex Search API from your company's websites.
By default, you can send no more than one synchronous query per second to get a generative response. For more information about Yandex Search API limits, see Quotas and limits in Yandex Search API.
The generative response feature is only available in the API v2 interface. For more information on the pricing of generative responses to queries, see Yandex Search API pricing policy.
You need the search-api.webSearch.user
role to run queries.
Request body format
The names of the request body fields in the REST API and gRPC API are different: the former uses camelCase
Each query seeking a generative response must contain the following request body in JSON
{
"messages": [
{
"content": "<message_1_text>",
"role": "ROLE_USER"
},
{
"content": "<model_2_response>",
"role": "ROLE_ASSISTANT"
},
{
"content": "<message_3_text>",
"role": "ROLE_USER"
},
{
"content": "<model_4_response>",
"role": "ROLE_ASSISTANT"
},
...
{
"content": "<message_n_text>",
"role": "ROLE_USER"
}
],
"site": {
"site": [
"<website_1_address_for_search>",
"<website_2_address_for_search>",
...
"<website_5_address_for_search>"
]
},
"host": {
"host": [
"<host_1_for_search>",
"<host_2_for_search>",
...
"<host_5_for_search>"
]
},
"url": {
"url": [
"<page_1_for_search>",
"<page_2_for_search>",
...
"<page_10_for_search>"
]
},
"folderId": "<folder_ID>",
"fixMisspell": true|false,
"enableNrfmDocs": true|false,
"searchFilters": [
{
"date": "<document_update_date>",
"lang": "<document_language>",
"format": "<document_format>"
}
]
}
Where:
-
messages
: Single search query or a search query with context in the form of chat with the model. It is specified as an array of objects, each one containing two elements:content
: Text of a user message or model's response (depending on therole
value).role
: Message sender's role. The possible values are:ROLE_USER
: Means the message is sent by the user, and thecontent
field contains the user's query.ROLE_ASSISTANT
: Means the message is sent by the model, and thecontent
field contains the model's response.
For more information about the YandexGPT chat mode, see How to build a chat with YandexGPT Lite or YandexGPT Pro.
-
Set the search scope in the
site
,host
, andurl
fields. Note that thesite
,host
, andurl
fields are mutually exclusive; you can only set one of them. If neither of these fields is set, the search will be performed across the entire Yandex search index.-
site
: Restricts the search to a specific array of websites. Not more than 5 websites per search.For example, for the
yandex.cloud
website, the search will target all*.yandex.cloud/*
documents, i.e., the results will include pages with the following URLs:yandex.cloud/
subdomain.yandex.cloud/
yandex.cloud/path/
subdomain.yandex.cloud/path/
You can use the
site
field to specify the exact path to the search area, e.g.,https://yandex.cloud/en/docs
. -
host
: Restricts the search to a specific array of hosts. Not more than 5 hosts per search.For example, for the
yandex.cloud/
host, the search will target allyandex.cloud/*
documents, i.e., the results will include pages with the following URLs:yandex.cloud/
yandex.cloud/path/
Unlike
site
-based restrictions,host
-based restrictions do not apply to subdomains. You also cannot provide a specific path to the search area in thehost
field. -
url
: Restricts the search to a specific array of pages, e.g.,https://yandex.cloud/en/docs/serverless-containers/concepts/container
andhttps://yandex.cloud/en/docs/container-registry/concepts/docker-image
. Not more than 10 pages per search.
-
folderId
: Folder ID.fixMisspell
: This parameter enables checking the query text for typos. If the parameter is set, the query text is checked for typos before it is sent. If there are typos, thefixedMisspellQuery
field is added to the response, containing the fixed query text that was sent to the model. This is an optional parameter. The possible values rangetrue
orfalse
.enableNrfmDocs
: This parameter determines whether search results will include documents which are not directly accessible from the home page. It only applies if the search scope is set by thesite
parameter. For example, if you want the results to include a page that is not accessible through any of the links on the home page, setenableNrfmDocs
totrue
. This is an optional parameter. The possible values rangetrue
orfalse
.searchFilters
: Additional text to add to each query. It is used to provide thedate:
,mime:
, andlang:
search operators . For example, if you go"date": ">20250101"
, the response will return only documents updated after January 1, 2025. This is an optional parameter. Thedate
,lang
, andformat
fields are mutually exclusive: you can only provide one of them in the request body.
Request body example:
{
"messages": [
{
"content": "What is containerization and how is it implemented in Yandex Cloud?",
"role": "ROLE_USER"
}
],
"site": {
"site": [
"https://ru.wikipedia.org/wiki/Контейнеризация",
"https://yandex.cloud/ru/docs/serverless-containers/",
"https://yandex.cloud/ru/docs/container-registry/"
]
},
"folderId": "aoevhr118rhc********",
"fixMisspell": "true",
"enableNrfmDocs": "true",
"searchFilters": [
{
"date": ">20250101"
}
]
}
{
"messages": [
{
"content": "<message_1_text>",
"role": "ROLE_USER"
},
{
"content": "<model_1_response>",
"role": "ROLE_ASSISTANT"
},
{
"content": "<message_2_text>",
"role": "ROLE_USER"
},
{
"content": "<model_3_response>",
"role": "ROLE_ASSISTANT"
},
...
{
"content": "<message_n_text>",
"role": "ROLE_USER"
}
],
"site": {
"site": [
"<website_1_address_for_search>",
"<website_2_address_for_search>",
...
"<website_5_address_for_search>"
]
},
"host": {
"host": [
"<host_1_for_search>",
"<host_2_for_search>",
...
"<host_5_for_search>"
]
},
"url": {
"url": [
"<page_1_for_search>",
"<page_2_for_search>",
...
"<page_10_for_search>"
]
},
"folder_id": "<folder_ID>",
"fix_misspell": true|false,
"enable_nrfm_docs": true|false,
"search_filters": [
{
"date": "<document_update_date>",
"lang": "<document_language>",
"format": "<document_format>"
}
]
}
Where:
-
messages
: Single search query or a search query with context in the form of chat with the model. It is specified as an array of objects, each one containing two elements:content
: Text of a user message or model's response (depending on therole
value).role
: Message sender's role. The possible values are:ROLE_USER
: Means the message is sent by the user, and thecontent
field contains the user's query.ROLE_ASSISTANT
: Means the message is sent by the model, and thecontent
field contains the model's response.
For more information about the YandexGPT chat mode, see How to build a chat with YandexGPT Lite or YandexGPT Pro.
-
Set the search scope in the
site
,host
, andurl
fields. Note that thesite
,host
, andurl
fields are mutually exclusive; you can only set one of them. If neither of these fields is set, the search will be performed across the entire Yandex search index.-
site
: Restricts the search to a specific array of websites. Not more than 5 websites per search.For example, for the
yandex.cloud
website, the search will target all*.yandex.cloud/*
documents, i.e., the results will include pages with the following URLs:yandex.cloud/
subdomain.yandex.cloud/
yandex.cloud/path/
subdomain.yandex.cloud/path/
You can use the
site
field to specify the exact path to the search area, e.g.,https://yandex.cloud/en/docs
. -
host
: Restricts the search to a specific array of hosts. Not more than 5 hosts per search.For example, for the
yandex.cloud/
host, the search will target allyandex.cloud/*
documents, i.e., the results will include pages with the following URLs:yandex.cloud/
yandex.cloud/path/
Unlike
site
-based restrictions,host
-based restrictions do not apply to subdomains. You also cannot provide a specific path to the search area in thehost
field. -
url
: Restricts the search to a specific array of pages, e.g.,https://yandex.cloud/en/docs/serverless-containers/concepts/container
andhttps://yandex.cloud/en/docs/container-registry/concepts/docker-image
. Not more than 10 pages per search.
-
folder_id
: Folder ID.fix_misspell
: This parameter enables checking the query text for typos. If the parameter is set, the query text is checked for typos before it is sent. If there are typos, thefixed_misspell_query
field is added to the response, containing the fixed query text that was sent to the model. This is an optional parameter. The possible values rangetrue
orfalse
.enable_nrfm_docs
: This parameter determines whether search results will include documents which are not directly accessible from the home page. It only applies if the search scope is set by thesite
parameter. For example, if you want the results to include a page that is not accessible through any of the links on the home page, setenable_nrfm_docs
totrue
. This is an optional parameter. The possible values rangetrue
orfalse
.search_filters
: Additional text to add to each query. It is used to provide thedate:
,mime:
, andlang:
search operators . For example, if you go"date": ">20250101"
, the response will return only documents updated after January 1, 2025. This is an optional parameter. Thedate
,lang
, andformat
fields are mutually exclusive: you can only provide one of them in the request body.
Request body example:
{
"messages": [
{
"content": "What is containerization and how is it implemented in Yandex Cloud?",
"role": "ROLE_USER"
}
],
"site": {
"site": [
"https://ru.wikipedia.org/wiki/Контейнеризация",
"https://yandex.cloud/ru/docs/serverless-containers/",
"https://yandex.cloud/ru/docs/container-registry/"
]
},
"folder_id": "aoevhr118rhc********",
"fix_misspell": "true",
"enable_nrfm_docs": "true",
"search_filters": [
{
"date": ">20250101"
}
]
}
Submitting a query
To send a query, use the search method for GenSearch. Install cURL
curl \
--request POST \
--header "Authorization: Bearer <IAM_token>" \
--data "@<file_path>" \
"https://searchapi.api.cloud.yandex.net/v2/gen/search" \
| jq
Where:
<IAM_token>
: IAM token of a user or service account with thesearch-api.webSearch.user
role.<file_path>
: Path to the file with the request body.
To send a query, use the GenSearchService/Search call. Install gRPCurl
grpcurl \
-rpc-header "Authorization: Bearer <IAM_token>" \
-d @ < <file_path> \
searchapi.api.cloud.yandex.net:443 yandex.cloud.searchapi.v2.GenSearchService/Search \
| jq
Where:
<IAM_token>
: IAM token of a user or service account with thesearch-api.webSearch.user
role.<file_path>
: Path to the file with the request body.
Generative response
Yandex Search API returns a JSON format response with the following syntax:
Note
The response contains no required fields. It may not return a field if there is no relevant data.
{
"message": {
"content": "<response_text>",
"role": "ROLE_ASSISTANT"
},
"sources": [
{
"used": false|true,
"url": "<link_to_found_document_1>",
"title": "<title_of_found_document_1>"
},
{
"used": false|true,
"url": "<link_to_found_document_2>",
"title": "<title_of_found_document_2>"
},
...
{
"used": false|true,
"url": "<link_to_found_document_n>",
"title": "<title_of_found_document_n>"
}
],
"searchQueries": [
{
"text": "<query_1_text>",
"reqId": "<query_1_ID>"
},
{
"text": "<query_2_text>",
"reqId": "<query_2_ID>"
},
...
{
"text": "<query_n_text>",
"reqId": "<query_n_ID>"
},
],
"isAnswerRejected": false|true,
"isBulletAnswer": false|true,
"fixedMisspellQuery": "<fixed_query_text >"
}
Where:
-
message.content
: Text of the generative response. The footnotes within the text refer to sources, the list and order of which are given in thesources
field. -
sources
: Array of source documents that were found during the query, could be used by YandexGPT as data sources when forming the response, and can be footnoted in themessage.content
field. Each source document contains the following fields:used
: Indicates whether the document was used to generate the response. The possible values rangetrue
orfalse
.url
: Document URL.title
: Document title. It may be missing from the results if the website owner did not define the page header.
-
searchQueries
: List of additional search queries sent by the generative model to the search engine. Each query contains the following fields:text
: Search query text.reqId
: Yandex Search API unique query ID.
-
isAnswerRejected
: Indicates the model's refusal to provide a response for ethical reasons:false
: Model has returned a response.true
: Model has refused to return a response.
-
isBulletAnswer
: Indicates a bullet response where the model cannot give a proper response and suggests a set of bullets with various information:false
: Model gave a good answer.true
: Model suggested a set of bullets.
-
fixedMisspellQuery
: Fixed query text. This parameter is optional. It appears in the response only if you providefixMisspell
in the request body and typos were found in the query text.
Here is an example of a generative response with website limitation:
[
{
"message": {
"content": "**Containerization** (OS-level virtualization) is a **virtualization method**
in which the OS kernel manages several isolated user-space instances
instead of a single one. [1] These instances (containers or zones) are identical
to a separate OS instance in terms of the processes running inside them. [1] vCPU
provides complete container isolation, so applications from different containers
have no impact on one another. [1]\n\n**In Yandex Cloud, containerization is implemented with the help of
Yandex Serverless Containers**. [5][6] A container allows you to run an application
contained in a Docker image, in Yandex Cloud. [6] \n\n**Some aspects of containerization in
Yandex Cloud:**\n\n* **Creating a container revision**. [6] You can only create a container revision
from a Docker image uploaded to a registry in Yandex Container Registry. [6] Other registries are not
supported. [6] The revision contains all the information you need to run the container. [6]\n*
**Invoking a container**. [6] Once you have created a revision, you can invoke the container via HTTPS
using a trigger or the Yandex API Gateway extension. [6]\n* **Scaling a container**. [6] If
the container is invoked faster than the instance can process the request, the service scales the container
by running additional instances of it. [6] This enables concurrent request
processing. [6]\n* **Provisioned instances**. [6] A provisioned instance
is a container instance that is guaranteed not to have a cold start when you run it. [6]",
"role": "ROLE_ASSISTANT"
},
"sources": [
{
"used": false,
"url": "https://ru.wikipedia.org/wiki/%D0%9A%D0%BE%D0%BD%D1%82%D0%B5%D0%B9%D0%BD%D0%B5%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F",
"title": "Containerization (Wikipedia)"
},
{
"used": true,
"url": "https://yandex.cloud/ru/docs/serverless-containers/tutorials/functions-framework-to-container",
"title": "Developing functions in Functions Framework and deploying them to Yandex Serverless Containers | Yandex Cloud documentation"
},
{
"used": false,
"url": "https://yandex.cloud/ru/docs/container-registry/",
"title": "Yandex Container Registry | Yandex Cloud documentation"
},
{
"used": false,
"url": "https://yandex.cloud/ru/docs/container-registry/concepts/docker-image",
"title": "Docker image. What is it and how does it work? | Yandex Cloud documentation"
},
{
"used": false,
"url": "https://yandex.cloud/ru/docs/serverless-containers/operations/",
"title": "How to work with Yandex Serverless Containers | Yandex Cloud documentation"
},
{
"used": true,
"url": "https://yandex.cloud/ru/docs/serverless-containers/concepts/container",
"title": "Container in Yandex Serverless Containers | Yandex Cloud documentation"
},
{
"used": true,
"url": "https://yandex.cloud/ru/docs/container-registry/operations/docker-image/docker-image-push",
"title": "Pushing a Docker image to a registry in Container Registry | Yandex Cloud documentation"
},
{
"used": false,
"url": "https://yandex.cloud/ru/docs/serverless-containers/tutorials/deploy-app-container",
"title": "Running a containerized app in Yandex Serverless Containers | Yandex Cloud documentation"
},
{
"used": false,
"url": "https://yandex.cloud/ru/docs/container-registry/tutorials/fault-tolerance",
"title": "Configuring a fault-tolerant architecture in Yandex Cloud | Yandex Cloud documentation"
},
{
"used": false,
"url": "https://yandex.cloud/ru/docs/serverless-containers/tf-ref",
"title": "Terraform reference for Yandex Serverless Containers | Yandex Cloud documentation"
}
],
"searchQueries": [
{
"text": "what is containerization and how is it implemented in yandex cloud date 2025 01 01 date 2025 01 01 date 2025 01 01",
"reqId": "1742492744075717-6834712924673670818-e23cqdex********-BAL"
},
{
"text": "how containerization is implemented in yandex cloud date 2025 01 01 date 2025 01 01 date 2025 01 01",
"reqId": "1742492744352285-5531077099747983300-hhsihxn5********-BAL"
},
{
"text": "what is containerization date 2025 01 01 date 2025 01 01 date 2025 01 01",
"reqId": "1742492744351443-10540017330195862709-gai4ndrg********-BAL"
}
],
"isAnswerRejected": false,
"isBulletAnswer": false,
"fixedMisspellQuery": "What is containerization and how is it implemented in Yandex Cloud?"
}
]
{
"message": {
"content": "<response_text>",
"role": "ROLE_ASSISTANT"
},
"sources": [
{
"url": "<link_to_found_document_1>",
"title": "<title_of_found_document_1>",
"used": false|true
},
{
"url": "<link_to_found_document_2>",
"title": "<title_of_found_document_2>",
"used": false|true
},
...
{
"url": "<link_to_found_document_n>",
"title": "<title_of_found_document_n>",
"used": false|true
}
],
"search_queries": [
{
"text": "<query_1_text>",
"req_id": "<query_1_ID>"
},
{
"text": "<query_2_text>",
"req_id": "<query_2_ID>"
},
...
{
"text": "<query_n_text>",
"req_id": "<query_n_ID>"
},
],
"is_answer_rejected": false|true,
"is_bullet_answer": false|true,
"fixed_misspell_query": "<fixed_query_text >"
}
Where:
-
message.content
: Text of the generative response. The footnotes within the text refer to sources, the list and order of which are given in thesources
field. -
sources
: Array of source documents that were found during the query, could be used by YandexGPT as data sources when forming the response, and can be footnoted in themessage.content
field. Each source document contains the following fields:url
: Document URL.title
: Document title.used
: Indicates whether the document was used to generate the response. The possible values rangetrue
orfalse
.
-
search_queries
: List of additional search queries sent by the generative model to the search engine. Each query contains the following fields:text
: Search query text.req_id
: Yandex Search API unique query ID.
-
is_answer_rejected
: Indicates the model's refusal to provide a response for ethical reasons:false
: Model has returned a response.true
: Model has refused to return a response.
-
is_bullet_answer
: Indicates a bullet response where the model cannot give a proper response and suggests a set of bullets with various information:false
: Model gave a good answer.true
: Model suggested a set of bullets.
-
fixed_misspell_query
: Fixed query text. This parameter is optional. It appears in the response only if you providefix_misspell
in the request body and typos were found in the query text.
Here is an example of a generative response with website limitation:
{
"message": {
"content": "**Containerization** (OS-level virtualization) is a **virtualization method**
in which the OS kernel manages several isolated user-space instances
instead of a single one. [1] These instances (containers or zones) are identical
to a separate OS instance in terms of the processes running inside them. [1] vCPU provides
complete container isolation, so applications from different containers have no impact
on one another. [1]\n\n**In Yandex Cloud, containerization is implemented with the help of
Yandex Serverless Containers**. [7] It allows you to run an application
contained in a Docker image, in Yandex Cloud. [7] \n\n**Some aspects of containerization in
Yandex Cloud:**\n\n* **Creating a container revision**. [7] You can only create a revision
from a Docker image uploaded to a registry in Yandex Container Registry. [7] Other registries are not supported.
supported. [7] The revision contains all the information you need to run the container. [7]\n* **Invoking
a container**. [7] Once you have created a revision, you can invoke the container via HTTPS using a trigger
or the Yandex API Gateway extension. [7]\n* **Scaling a container**. [7] If the container is invoked
faster than the instance can process the request, the service scales the container by running
its additional instances. [7] This ensures parallel processing of queries. [7]\n*
**Provisioned instances**. [7] This is a container instance that is guaranteed not to have
a cold start when you run it. [7] In a provisioned instance, before the container is invoked,
the Serverless Containers runtime components are initialized, and the user application is loaded and initialized. [7]",
"role": "ROLE_ASSISTANT"
},
"sources": [
{
"url": "https://ru.wikipedia.org/wiki/%D0%9A%D0%BE%D0%BD%D1%82%D0%B5%D0%B9%D0%BD%D0%B5%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F",
"title": "Containerization (Wikipedia)",
"used": false
},
{
"url": "https://yandex.cloud/ru/docs/serverless-containers/tutorials/functions-framework-to-container",
"title": "Developing functions in Functions Framework and deploying them to Yandex Serverless Containers | Yandex Cloud documentation",
"used": true
},
{
"url": "https://yandex.cloud/ru/docs/container-registry/",
"title": "Yandex Container Registry | Yandex Cloud documentation",
"used": false
},
{
"url": "https://yandex.cloud/ru/docs/container-registry/concepts/docker-image",
"title": "Docker image. What is it and how does it work? | Yandex Cloud documentation",
"used": false
},
{
"url": "https://yandex.cloud/ru/docs/container-registry/operations/docker-image/docker-image-push",
"title": "Pushing a Docker image to a registry in Container Registry | Yandex Cloud documentation",
"used": false
},
{
"url": "https://yandex.cloud/ru/docs/serverless-containers/tutorials/deploy-app-container",
"title": "Running a containerized app in Yandex Serverless Containers | Yandex Cloud documentation",
"used": false
},
{
"url": "https://yandex.cloud/ru/docs/serverless-containers/concepts/container",
"title": "Container in Yandex Serverless Containers | Yandex Cloud documentation",
"used": false
},
{
"url": "https://yandex.cloud/ru/docs/serverless-containers/tf-ref",
"title": "Terraform reference for Yandex Serverless Containers | Yandex Cloud documentation",
"used": true
},
{
"url": "https://yandex.cloud/ru/docs/serverless-containers/operations/",
"title": "How to work with Yandex Serverless Containers | Yandex Cloud documentation",
"used": false
},
{
"url": "https://yandex.cloud/ru/docs/container-registry/tutorials/fault-tolerance",
"title": "Configuring a fault-tolerant architecture in Yandex Cloud | Yandex Cloud documentation",
"used": false
}
],
"search_queries": [
{
"text": "what is containerization and how is it implemented in yandex cloud date 2025 01 01 date 2025 01 01 date 2025 01 01",
"req_id": "1742493532407414-13584885235180537459-jjleoq7t********-BAL"
},
{
"text": "how containerization is implemented in yandex cloud date 2025 01 01 date 2025 01 01 date 2025 01 01",
"req_id": "1742493532717030-17218638161437229208-rs6g5w5h********-BAL"
},
{
"text": "what is containerization date 2025 01 01 date 2025 01 01 date 2025 01 01",
"req_id": "1742493532716328-3123354248981714225-rs6g5w5h********-BAL"
}
],
"is_answer_rejected": false,
"is_bullet_answer": false,
"fixed_misspell_query": "What is containerization and how is it implemented in Yandex Cloud?"
}
Response features
Based on the query and search results, Yandex Search API may include the following warnings in a generative response:
-
If no relevant documents were found:
No results found.
Rephrase your query or ask something else. -
If Yandex Search API has found the relevant source documents but was unable to extract information:
Failed to extract the requested information from the documents. You can try opening them yourself or view the search results.
-
If Yandex Search API has found the source documents and succeeded extracting the information but is doubtful about response quality, it will preface its response with:
There is various information on this topic online. You can find its overview below.