Skip to main content
Version: 2.0

Create a new turn in the chat

POST 

https://api.vectara.io/v2/chats/:chat_id/turns

Create a new turn in the chat. Each conversation has a series of turn objects, which are the sequence of message and response pairs that make up the dialog.

Request

Path Parameters

    chat_id stringrequired

    Possible values: Value must match regular expression cht_.+$

    The ID of the chat.

Header Parameters

    Request-Timeout integer

    Possible values: >= 1

    The API will make a best effort to complete the request in the specified seconds or time out.

    Request-Timeout-Millis integer

    Possible values: >= 1

    The API will make a best effort to complete the request in the specified milliseconds or time out.

Body

    querystringrequired

    The chat message or question.

    Example: How can I use the Vectara platform?
    search object

    The parameters to search one or more corpora.

    corpora object[]required

    The corpora that you want to search.

    Possible values: >= 1

  • Array [
  • custom_dimensions object

    The custom dimensions as additional weights.

    property name*double
    metadata_filterstring

    The filter string used to narrow the search based on metadata attributes. The query against this corpus will be confined to document parts that match the metadata_filter. Only metadata fields set as filter_attributes on the corpus can be filtered. Filter syntax is similar to a SQL WHERE clause. See metadata filters documentation for more information.

    Example: doc.title = 'Charlotte''s Web'
    lexical_interpolationfloat

    How much to weigh lexical scores compared to the embedding score. 0 means lexical search is not used at all, and 1 means only lexical search is used.

    Possible values: >= 0 and <= 1

    Example: 0.025
    semanticsSearchSemantics (string)

    Indicates whether to consider a query against this corpus as a query or a response.

    Possible values: [default, query, response]

    Default value: default
    corpus_keyCorpusKey (string)required

    A user-provided key for a corpus.

    Possible values: <= 50 characters, Value must match regular expression [a-zA-Z0-9_\=\-]+$

    Example: my-corpus
    querystring

    Query for a particular corpus that will override the overall query if present.

  • ]
  • offsetint32

    Specifies how many results into the result to skip. This is useful for pagination.

    Possible values: >= 0

    Default value: 0
    limitint32

    The maximum number of results returned.

    Possible values: >= 1

    Default value: 10
    context_configuration object

    Configuration on the presentation of each document part in the result set.

    characters_beforeint32

    The number of characters that are shown before the matching document part. This is useful to show the context of the document part in the wider document. Ignored if sentences_before is set. Vectara will capture the full sentence that contains the captured characters, to not lose the meaning caused by a truncated word or sentence.

    Possible values: >= 0

    Default value: 0
    Example: 30
    characters_afterint32

    The number of characters that are shown after the matching document part. This is useful to show the context of the document part in the wider document. Ignored if sentences_after is set. Vectara will capture the full sentence that contains the captured characters, to not lose the meaning caused by a truncated word or sentence.

    Possible values: >= 0

    Default value: 0
    Example: 30
    sentences_beforeint32

    The number of sentences that are shown before the matching document part. This is useful to show the context of the document part in the wider document.

    Possible values: >= 0

    Default value: 0
    Example: 3
    sentences_afterint32

    The number of sentences that are shown after the matching document part. This is useful to show the context of the document part in the wider document.

    Possible values: >= 0

    Default value: 0
    Example: 3
    start_tagstring

    The tag that wraps the document part at the start. This is often used to provide a start HTML/XML tag or some other delimiter you can use in an application to understand where to provide highlighting in your UI and understand where the context before ends and the document part begins.

    Example: <em>
    end_tagstring

    The tag that wraps the document part at the end. This is often used to provide a start HTML/XML tag or some other delimiter you can use in an application to understand where to provide highlighting in your UI and understand where the context before ends and the document part begins.

    Example: </em>
    reranker object

    Rerank results of the search. Rerankers are very powerful tools to improve the order of search results. By default the search will use the most powerful reranker available to the customer's plan. To disable reranking, set the reranker type to "none".

    type

    Rerank results of the search. Rerankers are very powerful tools to improve the order of search results. By default the search will use the most powerful reranker available to the customer's plan. To disable reranking, set the reranker type to "none".

    Possible values: [customer_reranker, userfn, mmr, chain, none]

    reranker_idstringdeprecated

    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.

    Possible values: Value must match regular expression rnk_(?!272725718)\d+

    Example: rnk_272725719
    reranker_namestring

    The name of the reranker. Do not specify the MMR reranker name here. Instead, use the MMR reranker object type.

    Example: Rerank_Multilingual_v1
    limitint32

    Specifies the maximum number of results to be returned after the reranking process. When a reranker is applied, it performs the following steps:

    1. Reranks all input results according to its algorithm.
    2. Sorts the reranked results based on their new scores.
    3. Returns the top N results, where N is the value specified by this limit.

    Note: This limit is applied per reranking stage. In a chain of rerankers, each reranker can have its own limit, potentially reducing the number of results at each stage.

    Possible values: >= 1

    cutofffloat

    Specifies the minimum score threshold for results to be included after the reranking process. When a reranker is applied with a cutoff, it performs the following steps:

    1. Reranks all input results according to its algorithm.
    2. Applies the cutoff, removing any results with scores below the specified threshold.
    3. Returns the remaining results, sorted by their new scores.

    Note: This cutoff is applied per reranking stage. In a chain of rerankers, each reranker can have its own cutoff, potentially further reducing the number of results at each stage. If both 'limit' and 'cutoff' are specified, the cutoff is applied first, followed by the limit.

    generation object

    The parameters to control generation.

    generation_preset_namestring

    The preset values to use to feed the query results and other context to the model.

    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 used.
    • model_parameters such as temperature.

    All of these properties except the model can be overridden by setting them in this object. Even when a prompt_template is set, the generation_preset_name is used to set the model used. See model_parameters.model if you want to set the model explicitly.

    If generation_preset_name is not set, the Vectara platform will use the default model and prompt.

    Possible values: non-empty

    Example: vectara-summary-ext-v1.2.0
    prompt_namestringdeprecated

    Use generation_preset_name instead of prompt_name.

    Possible values: non-empty

    Example: vectara-summary-ext-v1.2.0
    max_used_search_resultsint32

    The maximum number of search results to be available to the prompt.

    Possible values: >= 0

    Default value: 5
    prompt_templatestring

    Vectara manages both system and user roles and prompts for the generative LLM out of the box by default. However, users can override the prompt_template via this variable. The prompt_template is in the form of an Apache Velocity template. For more details on how to configure the prompt_template, see the long-form documentation.

    Example: [ {"role": "system", "content": "You are a helpful search assistant."}, #foreach ($qResult in $vectaraQueryResults) {"role": "user", "content": "Given the $vectaraIdxWord[$foreach.index] search result."}, {"role": "assistant", "content": "${qResult.getText()}" }, #end {"role": "user", "content": "Generate a summary for the query '${vectaraQuery}' based on the above results."} ]
    prompt_textstringdeprecated

    This property is deprecated in favor of clearer naming. Use prompt_template. This property will be ignored if prompt_template is set.

    Example: [ {"role": "system", "content": "You are a helpful search assistant."}, #foreach ($qResult in $vectaraQueryResults) {"role": "user", "content": "Given the $vectaraIdxWord[$foreach.index] search result."}, {"role": "assistant", "content": "${qResult.getText()}" }, #end {"role": "user", "content": "Generate a summary for the query '${vectaraQuery}' based on the above results."} ]
    max_response_charactersint32

    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. This is generally implemented by including the max_response_characters in the prompt, and the LLM's instruction following capability dictates how closely the generated output is limited.

    Possible values: >= 0

    Example: 300
    response_languageLanguage (string)

    Languages that the Vectara platform supports.

    Possible values: [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]

    Default value: auto
    model_parameters object

    The parameters for the model. WARNING: This is an experimental feature, and breakable at any point with virtually no notice. It is meant for experimentation to converge on optimal parameters that can then be set in the prompt definitions.

    llm_namestring

    The model (e.g., gpt-4) to use for summarization. If specified, it will override the model behind generation_preset_name.

    Example: gpt4
    max_tokensint32

    The maximum number of tokens to be returned by the model.

    Possible values: >= 1

    temperaturefloat

    The sampling temperature to use. Higher values make the output more random, while lower values make it more focused and deterministic.

    frequency_penaltyfloat

    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_penaltyfloat

    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 object

    Style the generator should use when making citations.

    stylestring

    The citation style to be used in summary. Can be one of:

    • numeric - Citations formatted as simple numerals: [1], [2] ...
    • none - Citations removed from text.
    • html - Citation formatted as a URL like <a href="url_pattern">text_pattern</a>.
    • markdown - Formatted as [text_pattern](url_pattern).

    Possible values: [none, numeric, html, markdown]

    url_patternstring

    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.

    Example: https://vectara.com/documents/{doc.id}
    text_patternstring

    The text pattern if the citation_style is set to html or markdown. This pattern sets the href for HTML or the text within [] in markdown, and defaults to N being the index of result if it is not set.

    The default citation style looks like [N](<url_pattern>) for markdown.

    You can use metadata attributes in the text_pattern. For example, the pattern {doc.title} with citation style markdown would result in final citation output like [Title](<url_pattern>) when the document's metadata includes {"title":"Title"}.

    Example: {doc.title}
    enable_factual_consistency_scoreboolean

    Enable returning the factual consistency score with query results.

    Default value: true
    chat object

    Parameters to control chat behavior.

    storeboolean

    Indicates whether to store chat messages and response messages.

    Default value: true
    save_historyboolean

    Indicates whether to save the chat in both the chat and query history. This overrides chat.store.

    Default value: true
    intelligent_query_rewritingboolean

    Indicates whether to enable intelligent query rewriting. When enabled, the platform will attempt to extract metadata filter and rewrite the query to improve search results.

    Default value: false
    stream_responseboolean

    Indicates whether the response should be streamed or not.

    Default value: false

Responses

A response to a chat request.

Schema
    chat_idstring

    If the chat response was stored, the ID of the chat.

    turn_idstring

    If the chat response was stored, the ID of the turn.

    answerstring

    The message from the chat model for the chat message.

    response_languageLanguage (string)

    Languages that the Vectara platform supports.

    Possible values: [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]

    Default value: auto
    search_results object[]

    The ranked search results that the chat model used.

  • Array [
  • textstring

    The document part altered by the context configuration that matches the query.

    scoredouble

    The score of the individual result.

    part_metadata object

    The metadata for the document part.

    property name*any

    The metadata for the document part.

    document_metadata object

    The metadata for the document that contains the document part.

    property name*any

    The metadata for the document that contains the document part.

    document_idstring

    The ID of the document that contains the document part.

    table object

    The table that the document part is from.

    idstring

    The unique ID of the table within the document.

    Example: table_1
    titlestring

    The title of the table.

    data object

    The data of the table.

    headersarray[]

    The headers of the table.

    rowsarray[]

    The rows in the data.

    descriptionstring

    The description of the table.

    request_corpora_indexint32

    A query request can search over multiple corpora at a time. This property is set to the index in the list of corpora in the original search request that this search result originated from.

    If the query request is only over one corpus, this property is 0.

    Possible values: >= 0

    Example: 0
  • ]
  • factual_consistency_scorefloat

    Indicates the probability that the summary is factually consistent with the results. The system excludes this property if it encounters excessively large outputs or search results.

    rendered_promptstring

    The rendered prompt sent to the LLM. Useful when creating customer prompt_template templates.

    warningsQueryWarning (string)[]

    Non-fatal warnings that occurred during request processing

    Possible values: [exceeded_max_input_length_fcs, intelligent_query_rewriting_failed]

    rephrased_querystring

    View the actual query made to backend that was rephrased by the LLM from the input query.

    rewritten_queries object[]

    The rewritten queries for the corpora that were searched. Only populated when intelligent_query_rewriting is enabled.

  • Array [
  • corpus_keystring

    The corpus key that the query was made on.

    filter_extraction object

    The result of query filter extraction.

    querystring

    The query rephrased from the input query and executed.

    metadata_filterstring

    The metadata filter extracted from the input query.

  • ]

Authorization: x-api-key

name: x-api-keytype: apiKeyin: header
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.vectara.io/v2/chats/:chat_id/turns");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("x-api-key", "<x-api-key>");
var content = new StringContent("{\n \"query\": \"How can I use the Vectara platform?\",\n \"search\": {\n \"corpora\": [\n {\n \"custom_dimensions\": {},\n \"metadata_filter\": \"doc.title = 'Charlotte''s Web'\",\n \"lexical_interpolation\": 0.025,\n \"semantics\": \"default\",\n \"corpus_key\": \"my-corpus\",\n \"query\": \"string\"\n }\n ],\n \"offset\": 0,\n \"limit\": 10,\n \"context_configuration\": {\n \"characters_before\": 30,\n \"characters_after\": 30,\n \"sentences_before\": 3,\n \"sentences_after\": 3,\n \"start_tag\": \"<em>\",\n \"end_tag\": \"</em>\"\n },\n \"reranker\": {\n \"type\": \"customer_reranker\",\n \"reranker_name\": \"Rerank_Multilingual_v1\",\n \"limit\": 0,\n \"cutoff\": 0\n }\n },\n \"generation\": {\n \"generation_preset_name\": \"vectara-summary-ext-v1.2.0\",\n \"max_used_search_results\": 5,\n \"prompt_template\": \"[\\n {\\\"role\\\": \\\"system\\\", \\\"content\\\": \\\"You are a helpful search assistant.\\\"},\\n #foreach ($qResult in $vectaraQueryResults)\\n {\\\"role\\\": \\\"user\\\", \\\"content\\\": \\\"Given the $vectaraIdxWord[$foreach.index] search result.\\\"},\\n {\\\"role\\\": \\\"assistant\\\", \\\"content\\\": \\\"${qResult.getText()}\\\" },\\n #end\\n {\\\"role\\\": \\\"user\\\", \\\"content\\\": \\\"Generate a summary for the query '${vectaraQuery}' based on the above results.\\\"}\\n]\\n\",\n \"max_response_characters\": 300,\n \"response_language\": \"auto\",\n \"model_parameters\": {\n \"llm_name\": \"gpt4\",\n \"max_tokens\": 0,\n \"temperature\": 0,\n \"frequency_penalty\": 0,\n \"presence_penalty\": 0\n },\n \"citations\": {\n \"style\": \"none\",\n \"url_pattern\": \"https://vectara.com/documents/{doc.id}\",\n \"text_pattern\": \"{doc.title}\"\n },\n \"enable_factual_consistency_score\": true\n },\n \"chat\": {\n \"store\": true\n },\n \"save_history\": true,\n \"intelligent_query_rewriting\": false,\n \"stream_response\": false\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
Request Collapse all
Base URL
https://api.vectara.io
Auth
Parameters
— pathrequired
— header
— header
Body
{
  "query": "How can I use the Vectara platform?",
  "search": {
    "corpora": [
      {
        "custom_dimensions": {},
        "metadata_filter": "doc.title = 'Charlotte''s Web'",
        "lexical_interpolation": 0.025,
        "semantics": "default",
        "corpus_key": "my-corpus",
        "query": "string"
      }
    ],
    "offset": 0,
    "limit": 10,
    "context_configuration": {
      "characters_before": 30,
      "characters_after": 30,
      "sentences_before": 3,
      "sentences_after": 3,
      "start_tag": "<em>",
      "end_tag": "</em>"
    },
    "reranker": {
      "type": "customer_reranker",
      "reranker_name": "Rerank_Multilingual_v1",
      "limit": 0,
      "cutoff": 0
    }
  },
  "generation": {
    "generation_preset_name": "vectara-summary-ext-v1.2.0",
    "max_used_search_results": 5,
    "prompt_template": "[\n  {\"role\": \"system\", \"content\": \"You are a helpful search assistant.\"},\n  #foreach ($qResult in $vectaraQueryResults)\n     {\"role\": \"user\", \"content\": \"Given the $vectaraIdxWord[$foreach.index] search result.\"},\n     {\"role\": \"assistant\", \"content\": \"${qResult.getText()}\" },\n  #end\n  {\"role\": \"user\", \"content\": \"Generate a summary for the query '${vectaraQuery}' based on the above results.\"}\n]\n",
    "max_response_characters": 300,
    "response_language": "auto",
    "model_parameters": {
      "llm_name": "gpt4",
      "max_tokens": 0,
      "temperature": 0,
      "frequency_penalty": 0,
      "presence_penalty": 0
    },
    "citations": {
      "style": "none",
      "url_pattern": "https://vectara.com/documents/{doc.id}",
      "text_pattern": "{doc.title}"
    },
    "enable_factual_consistency_score": true
  },
  "chat": {
    "store": true
  },
  "save_history": true,
  "intelligent_query_rewriting": false,
  "stream_response": false
}
ResponseClear

Click the Send API Request button above and see the response here!