Sign in

v2

OpenAPI 3.0.02026-08-051996591.2 MB
Queries

Query multiple corpora

Queries one or more corpora and generates a response with Retrieval Augmented Generation (RAG). Similar to the advanced single corpus query.

  • Set the unique corpus_key for each corpus to query. You create the key in the Vectara Console or the Create Corpus API. You can assign a custom corpus_key that follows your preferred naming convention. Search requests reference the corpus by this key.
  • Customize the search with the query text (query), pagination (offset and limit), and metadata filters (metadata_filter).
  • Apply reranking (reranker) to improve the order of results. Opt in to generation by setting the generation property. If you exclude the property or set it to null, the response does not include generation. Learn more
  • Set generation_preset_name to Vectara's RAG-focused LLM (Mockingbird). Learn more
  • Control summarization with parameters such as max_response_characters, temperature, and frequency_penalty. Learn more
  • Customize citation formats in summaries with the citations object: numeric, HTML, or Markdown links. Learn more
post/v2/query

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 search query string, which is the question the user is asking.

stream_responseboolean

Indicates whether to stream the response.

save_historyboolean

Indicates whether to save the query to query history.

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.

Example request

{
  "query": "Summarize risk exposure and QA issues across divisions",
  "search": {
    "corpora": [
      {
        "corpus_key": "ops_manuals",
        "metadata_filter": "doc.topic = 'QA' AND doc.severity = 'high'",
        "lexical_interpolation": 0.005
      },
      {
        "corpus_key": "fin_docs",
        "metadata_filter": "doc.region = 'EMEA' AND doc.type = 'risk_report'",
        "lexical_interpolation": 0.005
      }
    ],
    "context_configuration": {
      "sentences_before": 2,
      "sentences_after": 2,
      "start_tag": "<em>",
      "end_tag": "</em>"
    },
    "reranker": {
      "type": "customer_reranker",
      "reranker_name": "Rerank_Multilingual_v1"
    }
  },
  "generation": {
    "generation_preset_name": "vectara-summary-ext-24-05-med-omni",
    "response_language": "eng",
    "enable_factual_consistency_score": true
  },
  "stream_response": false
}

Response

A response to a query.

summarystring

The summary of the search results.

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

Example response

{
  "summary": "The carbon reduction efforts by EU banks in 2023 show...",
  "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()}\"}]",
  "rewritten_queries": [
    {
      "corpus_key": "fin_docs",
      "filter_extraction": {
        "query": "ESG compliance trends in EU",
        "metadata_filter": "doc.industry = 'banking' AND doc.region = 'EU' AND doc.year = 2023"
      }
    }
  ]
}