Sign in

v3

latestOpenAPI 3.0.02026-08-081996601.2 MB
Chats

Start a chat

Creates a chat. The request specifies the default retrieval parameters that the prompt uses.

post/v2/chats

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Request body

querystring required

The chat message or question.

save_historyboolean

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

intelligent_query_rewritingboolean

[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 for more details.

stream_responseboolean

Indicates whether to stream the response.

Example request

{
  "query": "What are the carbon reduction efforts by EU banks in 2023?",
  "search": {
    "limit": 50
  },
  "generation": {
    "generation_preset_name": "mockingbird-2.0",
    "prompt_name": "mockingbird-2.0",
    "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",
    "prompt_text": "[\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,
    "model_parameters": {
      "llm_name": "gpt4"
    },
    "citations": {
      "url_pattern": "https://vectara.com/documents/{doc.id}",
      "text_pattern": "{doc.title}"
    }
  }
}

Response

A response to a chat request.

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_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.

factual_consistency_scorenumber 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_promptstring

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

warningsQueryWarning[]

Non-fatal warnings that occurred during request processing

rephrased_querystring

The actual query made, after the LLM rephrased the input query.

Example response

{
  "chat_id": "cht_123456789",
  "turn_id": "trn_987654321",
  "answer": "EU banks in 2023 have increased carbon reduction initiatives by 20%, driven by new EU regulations mandating annual emissions reporting.",
  "search_results": [
    {
      "score": 0.92,
      "document_metadata": {
        "industry": "banking",
        "year": 2023,
        "doc_type": "annual_report"
      },
      "document_id": "financial-report-2023",
      "corpus_key": "fin_docs",
      "part_metadata": {
        "section": "executive_summary"
      },
      "text": "EU banks reported a 20% increase in carbon reduction initiatives in 2023, driven by regulatory pressure.",
      "table": {
        "id": "billing_table_111",
        "title": "Carbon Reduction Metrics",
        "data": {
          "headers": [
            [
              {
                "text_value": "Bank A",
                "colspan": 1,
                "rowspan": 1
              }
            ]
          ],
          "rows": [
            [
              {
                "text_value": "Bank A",
                "colspan": 1,
                "rowspan": 1
              }
            ]
          ]
        },
        "description": "Summary of carbon reduction efforts by EU banks in 2023."
      },
      "image": {
        "id": "chart_1",
        "title": "Quarterly Sales Performance",
        "caption": "Sales growth trends for Q1 to Q4 of 2024",
        "description": "A bar chart showing quarterly sales growth, with Q4 outperforming all previous quarters by 15%",
        "mime_type": "image/jpeg"
      }
    }
  ],
  "rendered_prompt": "[{\"role\": \"system\", \"content\": \"You are an ESG analyst.\"}, {\"role\": \"user\", \"content\": \"What are the carbon reduction initiatives by EU banks in 2023?\"}, {\"role\": \"assistant\", \"content\": \"${vectaraQueryResults[0].getText()}\"}]",
  "rephrased_query": "Carbon reduction efforts by EU banks in 2023?",
  "rewritten_queries": [
    {
      "corpus_key": "fin_docs",
      "filter_extraction": {
        "query": "ESG compliance trends in EU",
        "metadata_filter": "doc.industry = 'banking' AND doc.year = 2023"
      }
    },
    {
      "corpus_key": "legal_docs",
      "filter_extraction": {
        "query": "ESG regulations for EU banks 2023",
        "metadata_filter": "doc.jurisdiction = 'EU' AND doc.year = 2023"
      }
    }
  ]
}