--- title: "Create a new turn in the chat" method: POST path: "/v2/chats/{chat_id}/turns" tags: ["Chats"] deprecated: true --- # Create a new turn in the chat `POST /v2/chats/{chat_id}/turns` > **Deprecated.** Creates a new turn in the chat. Each chat has a series of `turn` objects. Each turn is a message and response pair in the dialog. ## Path parameters - `chat_id` string, required ## Headers - `Request-Timeout` integer - `Request-Timeout-Millis` integer ## Request body - ChatRequest — Request to start or continue a chat conversation with a large language model. - `query` string, required — The chat message or question. - `search` SearchCorporaParameters, required — Search parameters to retrieve knowledge for the query. - `corpora` KeyedSearchCorpus[], required — The corpora that you want to search. - `custom_dimensions` CustomDimensions, nullable — The custom dimensions as additional weights. - `metadata_filter` string — The filter string that narrows the search based on metadata attributes. The query against this corpus returns only document parts that match the `metadata_filter`. You can filter only metadata fields set as `filter_attributes` on the corpus. Filter syntax is similar to a SQL WHERE clause. See [metadata filters documentation](https://docs.vectara.com/docs/learn/metadata-search-filtering/filter-overview) for more information. - `lexical_interpolation` number, float — The weight of lexical scores compared to the embedding score. A value of 0 disables lexical search. A value of 1 uses only lexical search. - `semantics` 'default' | 'query' | 'response' — Indicates whether to consider a query against this corpus as a query or a response. - `corpus_key` string, required — A user-provided key for a corpus. - `query` string — The query for a particular corpus. If present, it overrides the overall query. - `offset` integer — The number of results to skip. Use this for pagination. - `limit` integer — The maximum number of results returned. - `context_configuration` ContextConfiguration — Configuration for the presentation of each document part in the result set. Use either `characters_before`/`characters_after` or `sentences_before`/`sentences_after`; if both are set, `sentences_*` takes precedence. Setting `full_document_context: true` overrides both and returns the entire matching document as context. - `characters_before` integer — The number of characters to show before the matching document part. This shows the context of the part in the wider document. Ignored if `sentences_before` is set. The platform captures the full sentence that contains the captured characters, so a truncated word or sentence does not lose meaning. - `characters_after` integer — The number of characters to show after the matching document part. This shows the context of the part in the wider document. Ignored if `sentences_after` is set. The platform captures the full sentence that contains the captured characters, so a truncated word or sentence does not lose meaning. - `sentences_before` integer — The number of sentences to show before the matching document part. This shows the context of the part in the wider document. - `sentences_after` integer — The number of sentences to show after the matching document part. This shows the context of the part in the wider document. - `start_tag` string — The tag that wraps the start of the document part. Use an HTML/XML tag or another delimiter. Your application can use the tag to highlight the part in your UI. The tag also marks where the preceding context ends and the document part begins. - `end_tag` string — The tag that wraps the end of the document part. Use an HTML/XML tag or another delimiter. Your application can use the tag to highlight the part in your UI. The tag also marks where the document part ends and the following context begins. - `full_document_context` boolean — When true, the platform returns the entire document that contains the matching part as context. `characters_before`/`characters_after` and `sentences_before`/`sentences_after` are ignored. - `reranker` union — Reranks the results of the search. Rerankers improve the order of search results. By default, the search uses the most powerful reranker available to the customer's plan. To disable reranking, set the reranker `type` to `"none"`. - object — Reranker that is specific to the customer. - `type` string — When the type is `customer_reranker`, you can specify the `reranker_name` of a reranker. `reranker_id` is deprecated. The search then reranks results with that reranker. - `reranker_id` string — The ID of the reranker. The multilingual reranker that may be specified is rnk_272725719. Do not specify the MMR reranker ID here, and instead, use the MMR reranker object type. **Deprecated**: Use `reranker_name` instead. - `reranker_name` string — The name of the reranker. Do not specify the MMR reranker name here. Instead, use the MMR reranker object type. - `limit` integer — The maximum number of results to return after the reranking process. When you apply a reranker, it performs these steps: 1. Reranks all input results according to its algorithm. 2. Sorts the reranked results by their new scores. 3. Returns the top N results, where N is the value of this limit. Note: This limit applies per reranking stage. In a chain of rerankers, each reranker can have its own limit. This can reduce the number of results at each stage. - `cutoff` number, float — The minimum score threshold for results to be included after the reranking process. When you apply a reranker with a cutoff, it performs these steps: 1. Reranks all input results according to its algorithm. 2. Removes any results with scores below the cutoff. 3. Returns the remaining results, sorted by their new scores. Note: This cutoff applies per reranking stage. In a chain of rerankers, each reranker can have its own cutoff. This can further reduce the number of results at each stage. If you specify both `limit` and `cutoff`, the cutoff applies first, then the limit. - `include_context` boolean — If true, the reranker uses text with context (see `context_configuration`) for scoring. - `instructions` string — Instructions for instruction-following rerankers that guide relevance scoring behavior. Only applicable to rerankers that support custom instructions. - object — A reranker that uses user-defined functions to reorder search results. - `type` string — When the type is `userfn`, you can define custom reranking functions using document-level metadata, part-level metadata, or scores generated from the request-level metadata. - `user_function` string — The user defined function. - `limit` integer — The maximum number of results to return after the reranking process. When you apply a reranker, it performs these steps: 1. Reranks all input results according to its algorithm. 2. Sorts the reranked results by their new scores. 3. Returns the top N results, where N is the value of this limit. Note: This limit applies per reranking stage. In a chain of rerankers, each reranker can have its own limit. This can reduce the number of results at each stage. - `cutoff` number, float — The minimum score threshold for results to be included after the reranking process. When you apply a reranker with a cutoff, it performs these steps: 1. Reranks all input results according to its algorithm. 2. Removes any results with scores below the cutoff. 3. Returns the remaining results, sorted by their new scores. Note: This cutoff applies per reranking stage. In a chain of rerankers, each reranker can have its own cutoff. This can further reduce the number of results at each stage. If you specify both `limit` and `cutoff`, the cutoff applies first, then the limit. - object — A reranker that uses Maximal Marginal Relevance to balance relevance and diversity in search results. - `type` string — When the type is `mmr`, you can specify the `diversity_bias`. The search then uses the MMR reranker. - `diversity_bias` number, float — The diversity bias. Higher values indicate more diversity. - `limit` integer — The maximum number of results to return after the reranking process. When you apply a reranker, it performs these steps: 1. Reranks all input results according to its algorithm. 2. Sorts the reranked results by their new scores. 3. Returns the top N results, where N is the value of this limit. Note: This limit applies per reranking stage. In a chain of rerankers, each reranker can have its own limit. This can reduce the number of results at each stage. - `cutoff` number, float — The minimum score threshold for results to be included after the reranking process. When you apply a reranker with a cutoff, it performs these steps: 1. Reranks all input results according to its algorithm. 2. Removes any results with scores below the cutoff. 3. Returns the remaining results, sorted by their new scores. Note: This cutoff applies per reranking stage. In a chain of rerankers, each reranker can have its own cutoff. This can further reduce the number of results at each stage. If you specify both `limit` and `cutoff`, the cutoff applies first, then the limit. - object — A reranker that applies multiple rerankers in sequence to produce the final search results. - `type` string — When the type is `chain`, you can chain rerankers together. - `rerankers` SearchReranker[], required — An array of rerankers to apply to the search results in sequence. - object — A placeholder reranker that does not modify the original search results ordering. - `type` string — When the type is `none`, the search applies no reranking. - `limit` integer — The maximum number of results to return after the reranking process. When you apply a reranker, it performs these steps: 1. Reranks all input results according to its algorithm. 2. Sorts the reranked results by their new scores. 3. Returns the top N results, where N is the value of this limit. Note: This limit applies per reranking stage. In a chain of rerankers, each reranker can have its own limit. This can reduce the number of results at each stage. - `max_by` 'doc.id' — Collapses the result set to return at most one result per document. Keeps the highest-scoring part of each document. Applies to the retrieved results before reranking and pagination, so the number of results returned can be smaller than `limit`. - `generation` GenerationParameters — The parameters to control generation. - `enabled` boolean — Whether generation is enabled for this query. Chat requests ignore this field. - `generation_preset_name` string — The name of the generation preset that supplies default values for generation. A `generation_preset` is an object with a bundle of properties that specifies: * The `prompt_template` that is rendered and then sent to the LLM. * The LLM to use. * `model_parameter`s such as temperature. You can override any of these properties by setting them in this object. Set `model_parameters.llm_name` to override the model that `generation_preset_name` selects. If `generation_preset_name` is not set, the platform uses the default model and prompt. - `prompt_name` string — Use `generation_preset_name` instead of `prompt_name`. - `max_used_search_results` integer — The maximum number of search results available to the prompt. - `prompt_template` string — The template that renders the prompt sent to the generative LLM. By default, the platform manages the system and user roles and prompts for the generative LLM. Set this field to override the default prompts. The `prompt_template` is an Apache Velocity template. For details on how to configure the `prompt_template`, see the [long-form documentation](https://docs.vectara.com/docs/prompts/vectara-prompt-engine). - `prompt_text` string — Deprecated. Use `prompt_template` instead. If `prompt_template` is set, the platform ignores this property. - `max_response_characters` integer — Controls the length of the generated output. This is a rough estimate and not a hard limit: the end output can be longer or shorter than this value. The platform includes `max_response_characters` in the prompt, so the LLM's instruction-following capability dictates how closely the output stays within the limit. - `response_language` 'auto' | 'eng' | 'deu' | 'fra' | 'zho' | 'kor' | 'ara' | 'rus' | 'tha' | 'nld' | 'ita' | 'por' | 'spa' | 'jpn' | 'pol' | 'tur' | 'vie' | 'ind' | 'ces' | 'ukr' | 'ell' | 'heb' | 'fas' | 'hin' | 'urd' | 'swe' | 'ben' | 'msa' | 'ron' — Languages that the platform supports. - `model_parameters` object — The parameters for the model. WARNING: This is an experimental feature that can change at any point with virtually no notice. Use it to converge on optimal parameters, then set them in the prompt definitions. - `llm_name` string — The model (e.g., `gpt-4`) to use for summarization. If set, it overrides the model that `generation_preset_name` selects. - `max_tokens` integer — The maximum number of tokens that the model returns. - `temperature` number, float — The sampling temperature to use. Higher values make the output more random, while lower values make it more focused and deterministic. - `frequency_penalty` number, float — Higher values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. - `presence_penalty` number, float — Higher values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. - `citations` CitationParameters — Style the generator should use when making citations. - `style` 'none' | 'numeric' | 'html' | 'markdown' — The citation style that you want to use in the summary: * `numeric` - Citations formatted as simple numerals: \[1\], \[2\], etc. * `none` - Citations removed from text. * `html` - Citation formatted as a URL like `text_pattern`. * `markdown` - Formatted as `[text_pattern](url_pattern)`. - `url_pattern` string — The URL pattern if the citation_style is set to `html` or `markdown`. The pattern can access metadata attributes in the document or part. e.g. `https://my.doc/foo/{doc.id}/{part.id}` The default `url_pattern` is an empty string. - `text_pattern` string — The text pattern if the citation_style is set to `html` or `markdown`. For HTML, this pattern sets the href. For markdown, it sets the text within `[]`. If not set, the text defaults to `N`, the index of the result. The default citation style looks like `[N]()` for markdown. You can use metadata attributes in the `text_pattern`. For example, the pattern `{doc.title}` with citation style `markdown` produces citation output like `[Title]()` when the document's metadata includes `{"title":"Title"}`. - `enable_factual_consistency_score` boolean — Whether to return the factual consistency score with query results. - `chat` ChatParameters — Parameters to control chat behavior. - `store` boolean — Indicates whether to store chat messages and response messages. - `save_history` boolean — Indicates whether to save the chat in both the chat and query history. This overrides `chat.store`. - `intelligent_query_rewriting` boolean — [Tech Preview] Indicates whether to enable intelligent query rewriting. When enabled, the platform attempts to extract metadata filters and rewrite the query to improve search results. See [intelligent query rewriting](https://docs.vectara.com/docs/search-and-retrieval/intelligent-query-rewriting) for more details. - `stream_response` boolean — Indicates whether to stream the response. ## Response `200` A response to a chat request. - ChatFullResponse — Full response to a chat question when the result is not streamed. - `chat_id` string — If the chat response was stored, the ID of the chat. - `turn_id` string — If the chat response was stored, the ID of the turn. - `answer` string — The message from the chat model for the chat message. - `response_language` 'auto' | 'eng' | 'deu' | 'fra' | 'zho' | 'kor' | 'ara' | 'rus' | 'tha' | 'nld' | 'ita' | 'por' | 'spa' | 'jpn' | 'pol' | 'tur' | 'vie' | 'ind' | 'ces' | 'ukr' | 'ell' | 'heb' | 'fas' | 'hin' | 'urd' | 'swe' | 'ben' | 'msa' | 'ron' — Languages that the platform supports. - `search_results` IndividualSearchResult[] — The ranked search results that the chat model used. - union — A ranked search result from a query. Discriminated by result_type. - object — Common fields for all search result types. - `score` number, double — The score of the individual result. - `document_metadata` object — The metadata for the document that contains the document part. - `document_id` string — The ID of the document that contains the document part. - `request_corpora_index` integer — The index in the request's list of corpora that this search result originated from. A query request can search multiple corpora at a time. If the query request searches only one corpus, this property is 0. - `corpus_key` string — The corpus key that this search result originated from. For queries across multiple corpora, this identifies which corpus the result came from. - `part_metadata` object — The metadata for the document part as attached at indexing time. Filterable using `part.` in metadata filter expressions. - `text` string — The matched document part's text, expanded to the surrounding context window configured by `context_configuration`. For image parts, this is the text indexed alongside the image. - `result_type` string, required — The type of search result. Always `text` for this variant. - `table` Table — A table in a document. - `id` string — The unique ID of the table within the document. - `title` string — The title of the table. - `data` Data — The data of a table. - `headers` Header[] — The headers of the table. - … - `rows` Row[] — The rows in the data. - … - `description` string — The description of the table. - `image` ImageMetadata — An image element within a document. It contains identifying information and optional metadata. - `id` string, required — The unique identifier of the image within the document. Related content uses this identifier to reference the image. - `title` string — A short, human-readable title for the image. The title often appears above or alongside the image. - `caption` string — A brief caption that gives context or an explanation for the image. The caption typically appears below the image. - `description` string — A longer, detailed description of the image. On image-capable corpora, the platform indexes this field as the image's text body for keyword search. - `mime_type` string, required — The MIME type of the image, indicating the format of the binary data (e.g., image/jpeg for JPEG images). - object — Common fields for all search result types. - `score` number, double — The score of the individual result. - `document_metadata` object — The metadata for the document that contains the document part. - `document_id` string — The ID of the document that contains the document part. - `request_corpora_index` integer — The index in the request's list of corpora that this search result originated from. A query request can search multiple corpora at a time. If the query request searches only one corpus, this property is 0. - `corpus_key` string — The corpus key that this search result originated from. For queries across multiple corpora, this identifies which corpus the result came from. - `part_metadata` object — The metadata for the document part as attached at indexing time. Filterable using `part.` in metadata filter expressions. - `text` string — The matched document part's text, expanded to the surrounding context window configured by `context_configuration`. For image parts, this is the text indexed alongside the image. - `result_type` string, required — The type of search result. Always `image` for this variant. - `image` ImageMetadata — An image element within a document. It contains identifying information and optional metadata. - `id` string, required — The unique identifier of the image within the document. Related content uses this identifier to reference the image. - `title` string — A short, human-readable title for the image. The title often appears above or alongside the image. - `caption` string — A brief caption that gives context or an explanation for the image. The caption typically appears below the image. - `description` string — A longer, detailed description of the image. On image-capable corpora, the platform indexes this field as the image's text body for keyword search. - `mime_type` string, required — The MIME type of the image, indicating the format of the binary data (e.g., image/jpeg for JPEG images). - `factual_consistency_score` number, float — Indicates the probability that the summary is factually consistent with the results. The platform excludes this property if it encounters excessively large outputs or search results. - `rendered_prompt` string — The rendered prompt sent to the LLM. Useful when creating custom `prompt_template` templates. - `warnings` QueryWarning[] — Non-fatal warnings that occurred during request processing - `rephrased_query` string — The actual query made, after the LLM rephrased the input query. - `rewritten_queries` RewrittenQuery[] — The rewritten queries for the corpora that were searched. Only populated when intelligent_query_rewriting is enabled. - `corpus_key` string — The corpus key that the query was made on. - `filter_extraction` FilterExtraction — The result of query filter extraction. - `query` string — The rephrased form of the input query. The search executes this query. - `metadata_filter` string — The metadata filter extracted from the input query. ## Other responses - `400` — Turn creation request was malformed. - `403` — Permissions do not allow creating a turn in the chat. - `404` — Corpus or chat not found. --- [API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/versions/e85040b266cc/schema)