Version: 1.0

Query

POST /v1/query

Search for relevant results, highlight relevant snippets, and do Retrieval Augmented Generation (RAG).

Some tips for this API:

This operation authenticates with either an API Key or OAuth 2.0 (in a JWT "Bearer Token"). You can find details of how to set up an API key or use OAuth 2.0 here.
By default, Vectara only uses its neural/semantic retrieval model, and does not attempt to use keyword matching. To enable hybrid search with a mix of both keyword and neural results, edit the lambda value. Additional documentation on hybrid search is here.
Vectara can automatically provide a generative summary with the query results for Retrieval Augmented Generation (RAG). Additional details on RAG in Vectara can be found here.
The Query API takes an array of queries, since you can have Vectara perform more than 1 query in a single API call. The results that are returned are thus in an array as well, with each element in the response array corresponding to the input query array.
Custom dimensions (the dim array) is a feature that is only available to Scale accounts.
Reranking enhances search accuracy and variety and more details can be found here.

Request

Header Parameters

customer-id integerrequired

Enter the Customer ID to use for the request.

timeout string

Default value: 30S

(Optional) Enter the timeout value of the request in seconds, such as 10S or 30S.

application/json

Body

required

query object[]required

Each request can have multiple queries that result in multiple search results. Each query can search multiple corpora.

Array [

query string

The query text to use from the end user.

start int64

The starting point for the query.

numResults int64required

Possible values: >= 1

The number of results to return. Possible values: >= 1

contextConfig object

Allows processing a matched document part text before being returned as a search result.

charsBefore integer

chars_before is used for showing the end user the characters leading up to the result snippet. Ignored if sentences_before is set.

charsAfter integer

chars_after is used for showing the end user the characters after the result snippet. Ignored if sentences_before is set.

sentencesBefore integerrequired

sentences_before is used for showing the end user the sentences leading up to the result snippet.

sentencesAfter integerrequired

sentences_after is used for showing the end user the sentences leading up to the result snippet.

startTag stringrequired

The tag that wraps the snippet at the start.

endTag stringrequired

The tag that wraps the snippet at the end.

corpusKey object[]required

The query is run on all these corpora, and the results are merged together in the response, ranked by score.

Array [

customerId int64

The Customer ID.

corpusId int64required

The Corpus ID.

semantics CorpusKeySemantics

Possible values: [DEFAULT, QUERY, RESPONSE]

Default value: DEFAULT

Semantics controls the interpretation of the query string by the server, and can be used to override the default semantics assigned in the corpus definition.

DEFAULT: Use corpus-assigned semantics. This is the most common setting.
QUERY: Use query semantics. This is also common.
RESPONSE: Use response semantics. Usage of this is rare.

metadataFilter string

Filter the documents and document parts based on their metadata. See https://docs.vectara.com/docs/learn/metadata-search-filtering/filter-overview for a detailed explanation on how to create a metadata filter.

lexicalInterpolationConfig object

Configuration for a linear interpolation.

lambda float

]

summary object[]

Optionally, one or more requests to summarize the results.

Array [

summarizerPromptName string

The name of the summarizer+prompt combination to use for summarization.

maxSummarizedResults integerrequired

Maximum number of results to summarize.

responseLang stringrequired

ISO 639-1 or ISO 639-3 language code for the response.

promptText string

The prompt_text is in the form of an Apache Velocity template.

debug boolean

Debugging the generative prompt.

responseChars integer

Controls the length of the summary.

modelParams object

Parameters for the summarizer model.

maxTokens integer

Maximum tokens for the summarizer model.

temperature number

The sampling temperature to use.

frequencyPenalty number

Higher values penalize new tokens based on their existing frequency in the text so far.

presencePenalty number

Higher values penalize new tokens based on whether they appear in the text so far.

citationParams object

Citation parameters for the summary.

style string

Possible values: [NUMERIC, NONE, HTML, MARKDOWN]

Default value: NUMERIC

The citation style to be used in summary.

urlPattern string

The URL pattern if the citation_style is set to HTML or MARKDOWN.

textPattern string

The text pattern if the citation_style is set to HTML or MARKDOWN.

chat object

The chat request.

store boolean

Whether to store the query/answer pair.

conversationId string

The conversation ID of the chat. If empty, a new conversation will be started.

factualConsistencyScore boolean

If unset or true, the response will include the factual consistency score.

]

Responses

200
default

A successful response.

application/json

Schema
Example (from schema)

Schema

responseSet object[]

The response sets for queries within the batch. If using synchronous APIs for querying, the response set will be included directly in the response. However, if using the streaming APIs for query, the response set messages only set the future_id field. Later, as response sets are computed and returned over the stream, the future_id within the summary can be used for correlation.

Array [

response object[]

Search results for the query.

Array [

text string

The text of the document part after being modified by the context config.

score float

The score used for ranking results. The higher the score, the better the match.

metadata object[]

Document part level metadata.

Array [

name string

value string

]

documentIndex int64

Use this ID to find the document in the ResponseSet.

corpusKey object

Object to specify how each corpus in a query is searched.

customerId int64

The Customer ID.

corpusId int64required

The Corpus ID.

semantics CorpusKeySemantics

Possible values: [DEFAULT, QUERY, RESPONSE]

Default value: DEFAULT

Semantics controls the interpretation of the query string by the server, and can be used to override the default semantics assigned in the corpus definition.

DEFAULT: Use corpus-assigned semantics. This is the most common setting.
QUERY: Use query semantics. This is also common.
RESPONSE: Use response semantics. Usage of this is rare.

metadataFilter string

lexicalInterpolationConfig object

Configuration for a linear interpolation.

lambda float

]

status object[]

Potentially multiple warnings.

Array [

code vectaraStatusCode

Possible values: [OK, FAILURE, UNKNOWN, INVALID_ARGUMENT, DEADLINE_EXCEEDED, ALREADY_EXISTS, PERMISSION_DENIED, RESOURCE_EXHAUSTED, FAILED_PRECONDITION, ABORTED, OUT_OF_RANGE, UNIMPLEMENTED, INTERNAL, UNAVAILABLE, DATA_LOSS, UNAUTHENTICATED, BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, METHOD_NOT_ALLOWED, CONFLICT, UNSUPPORTED_MEDIA_TYPE, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, NOT_IMPLEMENTED, SERVICE_UNAVAILABLE, INSUFFICIENT_STORAGE, UNPARSEABLE_RESPONSE, DISABLED_CUSTOMER, INVALID_CUSTOMER_ID, DISABLED_CORPUS, INVALID_CORPUS_ID, DISABLED_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, CMK_INACCESSIBLE, QRY__DISABLED_CORPUS, QRY__DOCUMENT_DB_FAILURE, QRY__ENCODER_FAILURE, QRY__INTERRUPTED, QRY__INVALID_CORPUS, QRY__INVALID_START, QRY__INVALID_NUM_RESULTS, QRY__INVALID_CONTEXT, QRY__MISSING_QUERY, QRY__MISSING_CORPUS, QRY__TIMEOUT, QRY__TOO_MANY_CORPORA, QRY__TOO_MANY_QUERIES, QRY__VECTOR_INDEX_FAILURE, QRY__INVALID_DIMENSION, QRY__INVALID_CLIENTKEY, QRY__DECRYPTION_FAILURE, QRY__INVALID_RERANKER, QRY__PARTIAL_RERANK, QRY__RERANK_FAILURE, QRY__TOO_MANY_RESULT_ROWS, QRY__PARTIAL_RETRIEVAL, QRY__SMRY__INVALID_SUMMARIZER_PROMPT, QRY__SMRY__INVALID_SUMMARY_LANG, QRY__SMRY__UNSUPPORTED_SUMMARY_LANG, QRY__SMRY__PARTIAL_SUMMARY, QRY__SMRY__NO_QUERY_RESULTS, QRY__SMRY__EVAL_UNSUPPORTED_LANG, QRY__SMRY__EVAL_FAILURE, QRY__GEN__NO_QUERY_RESULTS, QRY__GEN__UNPARSEABLE_MODEL_PARAMS, CX_SPECS__INVALID_JSON, CX_SPECS__UNREGISTERED_TYPE, CX_SPECS__MISSING_SPEC, CX_SPECS__MISSING_TYPE, CX_SPECS__UNPARSEABLE_SPEC, ADM__INVALID_CUSTOMER_ID, ADM__INVALID_CORPUS_ID, ADM__INVALID_ENCODER_ID, ADM__INVALID_ROLE_ID, ADM__ROLE_ALREADY_EXISTS, ADM__ONLY_ONE_OWNER_SUPPORTED, ADM__INVALID_PERMISSION, ADM__ROLECREATION_FAILURE, ADM__USER_EMAIL_NOT_AVAIALBLE, ADM__USERNAME_NOT_AVAILABLE, ADM__SIGNUP_MISSING_NAME, ADM__SIGNUP_MISSING_ORG, ADM__SIGNUP_MISSING_EMAIL, ADM__SIGNUP_MISSING_PAYMENT, ADM__SIGNUP_MISSING_PLAN, ADM__SIGNUP_MISSING_PASSWORD, ADM__SIGNUP_INVALID_NAME, ADM__SIGNUP_INVALID_ORG, ADM__SIGNUP_INVALID_EMAIL, ADM__SIGNUP_INVALID_PAYMENT, ADM__SIGNUP_INVALID_PLAN, ADM__SIGNUP_INVALID_PASSWORD, ADM__SIGNUP_INVALID_ACCOUNT_ALIAS, ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE, ADM__SIGNUP_MISSING_COUNTRY_CODE, ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE, ADM__CUST_MARK_DELETE_FAILED, ADM__CUST_FAISS_DEALLOC_FAILED, ADM__CUST_ALREADY_ACTIVE, ADM__CUST_REACTIVATE_FAILED, ADM__CUST_ENABLEMENT_FAILED, ADM__CORPUS_LIMIT_REACHED, ADM__STRIPE_CARD_DECLINED, ADM__STRIPE_PROCESSING_ERROR, ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND, ADM__EMAIL_NOT_VALIDATED, ADM__CHANGE_PLAN__NO_CURRENT_PLAN, ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE, ADM__CHANGE_PLAN__INVALID_PLAN_ID, ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE, ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE, ADM__CHANGE_PLAN__CONFLICTING_CHANGE, SCM__MISCONFIGURED_CONNECTION, STATS_DB_READ_FAILURE, VDB__TEXT_READ_FAILURE, REBUILD__LOW_RECALL, REBUILD__INDEX_UPLOAD_FAILURE, REBUILD__UPDATE_JOURNAL_FAILURE, REBUILD__UPDATE_FAISSPARAMS_FAILURE, REBUILD__NO_DATA, REBUILD__EVALUATION, IDX__TRANSIENT_PARTIAL_DELETION_FAILURE, IDX__PERMANENT_PARTIAL_DELETION_FAILURE, CALB__INVALID_JSON, CALB__INVALID_SPEC, CALB__UNREGISTERED_TYPE, CALB__MISSING_SPEC, CALB__MISSING_TYPE, CALB__UNPARSABLE_SPEC]

Default value: OK

statusDetail string

]

document object[]

Document level metadata for document parts that are in the response.

Array [

id string

The document id.

metadata object[]

Document level metadata.

Array [

name string

value string

]

summary object[]

A summary. If using synchronous APIs for querying, the summary will be included directly in this response. However, if using the streaming APIs for query, the summary messages only set the future_id field. Later, as summary results are computed and returned over the stream, the future_id within the summary can be used for correlation.

Array [

text string

The summary text.

lang string

ISO 639 language code of the summary. If the requested language was set to "AUTO", the summary language is the same as the auto-detected language of the query.

chat object

Values needed to refer to the chat later.

conversationId string

The conversation id of the chat.

turnId string

The id assigned to this query and answer.

status object

code vectaraStatusCode

Default value: OK

statusDetail string

factualConsistency object

score float

The probability that the summary is factually consistent with the results in the ResponseSet.

status object

code vectaraStatusCode

Default value: OK

statusDetail string

done boolean

Determines if the summary is done. false if the summary is in-progress for streaming requests, otherwise true. this only refers to summary text generation, Factual Consistency will come later if requested.

status object[]

Statuses are marked “repeated” for consistency and flexibility. A failed summary should bubble up into the status code of the entire ResponseSet.

Array [

code vectaraStatusCode

Default value: OK

statusDetail string

]

futureId int32

Populated for streaming requests only.

]

futureId int32

Populated for streaming requests only. This id should matched against the query response in order to know which query generated this object.

]

status object[]

Array [

code vectaraStatusCode

Default value: OK

statusDetail string

]

metrics object

Basic performance metrics that can be attached to a server response.

queryEncodeMs int64

How long it took to encode the query.

retrievalMs int64

How long it took to retrieve relevant results.

userdataRetrievalMs int64

How long it took to retrieve user data.

rerankMs int64

How long it took to rerank the results.

{
  "responseSet": [
    {
      "response": [
        {
          "text": "string",
          "score": 0,
          "metadata": [
            {
              "name": "string",
              "value": "string"
            }
          ],
          "documentIndex": 0,
          "corpusKey": {
            "corpus_id": 12
          }
        }
      ],
      "status": [
        {
          "code": "OK",
          "statusDetail": "string"
        }
      ],
      "document": [
        {
          "id": "string",
          "metadata": [
            {
              "name": "string",
              "value": "string"
            }
          ]
        }
      ],
      "summary": [
        {
          "text": "string",
          "lang": "string",
          "chat": {
            "conversationId": "string",
            "turnId": "string",
            "status": {
              "code": "OK",
              "statusDetail": "string"
            }
          },
          "factualConsistency": {
            "score": 0,
            "status": {
              "code": "OK",
              "statusDetail": "string"
            }
          },
          "done": true,
          "status": [
            {
              "code": "OK",
              "statusDetail": "string"
            }
          ],
          "futureId": 0
        }
      ],
      "futureId": 0
    }
  ],
  "status": [
    {
      "code": "OK",
      "statusDetail": "string"
    }
  ],
  "metrics": {
    "queryEncodeMs": 0,
    "retrievalMs": 0,
    "userdataRetrievalMs": 0,
    "rerankMs": 0
  }
}

An unexpected error response.

application/json

Schema
Example (from schema)

Schema

code int32

message string

details object[]

Array [

@type string

A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration). The name should be in a canonical form (e.g., leading "." is not accepted).

In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http, https, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:

If no scheme is provided, https is assumed.
An HTTP GET on the URL must yield a [google.protobuf.Type][]

value in binary format, or produce an error.
Applications are allowed to cache lookup results based on the

URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)

Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.

Schemes other than http, https (or the empty scheme) might be used with implementation specific semantics.

]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Query

/v1/query

Request​

Header Parameters

Body

Responses​

Request

Responses