diff --git a/fern/apis/v1/generators.yml b/fern/apis/v1/generators.yml new file mode 100644 index 000000000..b0c210019 --- /dev/null +++ b/fern/apis/v1/generators.yml @@ -0,0 +1,3 @@ +api: + specs: + - openapi: ../vectara-oas.yml \ No newline at end of file diff --git a/fern/apis/v2/generators.yml b/fern/apis/v2/generators.yml new file mode 100644 index 000000000..f0e83651e --- /dev/null +++ b/fern/apis/v2/generators.yml @@ -0,0 +1,3 @@ +api: + specs: + - openapi: ../vectara-oas-v2.yml \ No newline at end of file diff --git a/fern/apis/vectara-oas-v2.yml b/fern/apis/vectara-oas-v2.yml new file mode 100644 index 000000000..ac7b6f67e --- /dev/null +++ b/fern/apis/vectara-oas-v2.yml @@ -0,0 +1,6477 @@ +openapi: 3.0.0 +info: + title: Vectara REST API v2 + description: 'Vectara provides an end-to-end platform for creating GenAI products + using a simple to use API. + + You can [sign up for an account](https://console.vectara.com/signup) and then + view several [API Recipes](https://docs.vectara.com/docs/api-recipes) with example + queries and parameter values. + + The Vectara API Playground lets you experiment with REST endpoints from your browser. + Select an endpoint to view its definition, including the required or optional + headers, body, responses, and sample commands. On the right side of each endpoint + page, like [Get Corpus](/docs/rest-api/get-corpus), you manually enter your API + Key or OAuth Bearer Token, `customer_id`, and then any required body parameters + like the `corpusID` before sending the API request. + + :::note + + Vectara supports two primary methods of authentication: API keys and OAuth 2.0, + which are applicable to all endpoints. Query API Keys are used for read-only querying + operations, while Index API Keys provide read and write access. The OAuth 2.0 + operations authenticate with a Bearer Token via the OAuth 2.0 client credentials + grant. Review the [**OAuth 2.0 section**](https://docs.vectara.com/docs/learn/authentication/oauth-2) + about how to generate the token.' + version: 2.0.0 + termsOfService: https://vectara.com/legal/terms-of-service/ + x-logo: + url: https://docs.vectara.com/img/vectara_wordmark.png + altText: Vectara + x-dark-logo: + url: https://docs.vectara.com/img/vectara_wordmark_light.png + altText: Vectara + contact: + email: feedback@vectara.com +tags: +- name: Authentication + description: Authenticate with the API using OAuth 2.0 or API keys +- name: Queries + description: Perform search and Retrieval Augmented Generation (RAG) operations + on one or more corpora +- name: Upload + description: Upload files to a corpus for automatic parsing, text extraction, chunking, + and indexing +- name: Index + description: Index and manage both core and structured documents to enable efficient + search and retrieval +- name: Corpora + description: Create, manage, and update corpora and their associated settings +- name: Documents + description: Retrieve and manage documents stored in a corpus for administrative + tasks +- name: Chats + description: Create, manage, and interact with chat sessions for conversational + AI +- name: Generation Presets + description: Manage generation presets for controlling the behavior of generative + AI responses +- name: Query History + description: Retrieve and manage the history of previous queries for analytics and + auditing +- name: API Keys + description: Create, manage, and revoke API keys for secure access to the platform +- name: Application Clients + description: Configure and manage application clients for OAuth authentication +- name: Large Language Models + description: List LLMs for text summarization, chat, and other generation tasks +- name: Encoders + description: List available encoders (such as Boomerang) that turn text into vectors +- name: Rerankers + description: List rerankers for reranking search results +- name: Jobs + description: Monitor background jobs such as rebuilding indexes or updating corpus + settings +- name: Users + description: Create, manage, and authenticate users within the platform for user + administration +- name: Table Extractors + description: List available extractors for tabular data from documents +- name: Hallucination Correctors + description: API for managing hallucination correction, including listing available + models and correcting hallucinated content in generated text +- name: LLM Chat Completions + description: Create model responses for chat conversations using OpenAI-compatible + endpoints +- name: Factual Consistency Evaluation + description: Evaluate text quality metrics like factual consistency and hallucination + detection +servers: +- url: https://api.vectara.io +paths: + /v2/corpora: + post: + summary: Create a corpus + description: Create a corpus, which is a container to store documents and associated + metadata. Here, you define the unique `corpus_key` that identifies the corpus. + The `corpus_key` can be custom-defined following your preferred naming convention, + allowing you to easily manage the corpus's data and reference it in queries. + For more information, see [Corpus Key Definition](https://docs.vectara.com/docs/api-reference/search-apis/search#corpus-key-definition). + operationId: createCorpus + tags: + - Corpora + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateCorpusRequest' + responses: + '201': + description: The corpus has been created. + content: + application/json: + schema: + $ref: '#/components/schemas/Corpus' + '400': + description: Invalid request body in the create corpus request. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow creating a corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '409': + description: The corpus already exists + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: corpora + x-fern-sdk-method-name: create + get: + summary: List corpora + description: List corpora in the account. The returned corpus objects contain + less detail compared to those retrieved the direct corpus retrieval operation. + operationId: listCorpora + tags: + - Corpora + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: limit + in: query + description: The maximum number of corpora to return at one time. + required: false + schema: + type: integer + format: int32 + minimum: 1 + maximum: 100 + default: 10 + - name: filter + in: query + description: A regular expression to filter the corpora by their name or summary. + required: false + schema: + type: string + - name: corpus_id + in: query + description: Filter corpora to only include corpora with these IDs. + required: false + schema: + type: array + items: + type: string + pattern: crp_[0-9]+$ + - name: page_key + in: query + description: Used to retrieve the next page of corpora after the limit has + been reached. + required: false + schema: + type: string + responses: + '200': + description: List of corpora. + content: + application/json: + schema: + $ref: '#/components/schemas/ListCorporaResponse' + '403': + description: Permissions do not allow listing corpora. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: corpora + x-fern-sdk-method-name: list + x-fern-pagination: + cursor: $request.page_key + next_cursor: $response.metadata.page_key + results: $response.corpora + /v2/corpora/{corpus_key}: + get: + tags: + - Corpora + summary: Retrieve metadata about a corpus + description: Get metadata about a corpus. This operation does not search the + corpus contents. Specify the `corpus_key` to identify the corpus whose metadata + you want to retrieve. The `corpus_key` is created when the corpus is set up, + either through the Vectara Console UI or the Create Corpus API. For more information, + see [Corpus Key Definition](https://docs.vectara.com/docs/api-reference/search-apis/search#corpus-key-definition). + operationId: getCorpus + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the corpus to retrieve. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + responses: + '200': + description: A corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Corpus' + '403': + description: Permissions do not allow retrieving the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: corpora + x-fern-sdk-method-name: get + delete: + tags: + - Corpora + summary: Delete a corpus and all its data + description: Permanently delete a corpus and all its associated data. The `corpus_key` + uniquely identifies the corpus. For more information, see [Corpus Key Definition](https://docs.vectara.com/docs/api-reference/search-apis/search#corpus-key-definition). + operationId: deleteCorpus + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the corpus to delete. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + responses: + '204': + description: Successfully deleted a corpus. + '403': + description: Permissions do not allow deleting the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: corpora + x-fern-sdk-method-name: delete + patch: + tags: + - Corpora + summary: Update a corpus + description: Enable, disable, or update the name and description of a corpus. + This lets you manage data availability without deleting the corpus, which + is useful for maintenance and security purposes. The `corpus_key` uniquely + identifies the corpus. For more information, see [Corpus Key Definition](https://docs.vectara.com/docs/api-reference/search-apis/search#corpus-key-definition). + Consider updating the name and description of a corpus dynamically to help + keep your data aligned with changing business needs. + operationId: updateCorpus + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the corpus to update. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateCorpusRequest' + responses: + '200': + description: Successfully modified the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Corpus' + '403': + description: Permissions do not allow updating the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: corpora + x-fern-sdk-method-name: update + /v2/corpora/{corpus_key}/reset: + post: + tags: + - Corpora + summary: Remove all documents and data in a corpus + description: Resets a corpus, which removes all documents and data from the + specified corpus, while keeping the corpus itself. The `corpus_key` uniquely + identifies the corpus. For more information, see [Corpus Key Definition](https://docs.vectara.com/docs/api-reference/search-apis/search#corpus-key-definition). + operationId: resetCorpus + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the corpus to reset. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + responses: + '204': + description: Successfully reset a corpus. + '403': + description: Permissions do not allow resetting the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: corpora + x-fern-sdk-method-name: reset + /v2/corpora/{corpus_key}/replace_filter_attributes: + post: + tags: + - Corpora + summary: Replace the filter attributes of a corpus + operationId: replaceFilterAttributes + description: 'Replace the filter attributes of a corpus. This does not happen + immediately, as this operation creates a job that completes asynchronously. + These new filter attributes will not work until the job completes. + + You can monitor the status of the filter change using the returned job ID. + The `corpus_key` uniquely identifies the corpus. For more information, see + [Corpus Key Definition](https://docs.vectara.com/docs/api-reference/search-apis/search#corpus-key-definition).' + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the corpus having its filters replaced. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ReplaceFilterAttributesRequest' + responses: + '200': + description: Successfully created a job that will replace the filter attributes. + content: + application/json: + schema: + $ref: '#/components/schemas/ReplaceFilterAttributesResponse' + '403': + description: Permissions do not allow replacing filter attributes. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: corpora + x-fern-sdk-method-name: replaceFilterAttributes + /v2/corpora/{corpus_key}/compute_size: + post: + tags: + - Corpora + summary: Compute the current size of a corpus + description: Compute the current size of a corpus, including number of documents, + parts, and characters. The `corpus_key` uniquely identifies the corpus. For + more information, see [Corpus Key Definition](https://docs.vectara.com/docs/api-reference/search-apis/search#corpus-key-definition). + operationId: computeCorpusSize + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the corpus to compute size for. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + responses: + '200': + description: Successfully computed the corpus size. + content: + application/json: + schema: + $ref: '#/components/schemas/ComputeCorpusSizeResponse' + '403': + description: Permissions do not allow computing size for this corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: corpora + x-fern-sdk-method-name: compute_size + /v2/corpora/{corpus_key}/query: + get: + tags: + - Queries + summary: Simple Single Corpus Query + description: 'Search a single corpus with a straightforward query request, specifying + the corpus key and query parameters. * Specify the unique `corpus_key` identifying + the corpus to query. The `corpus_key` is [created in the Vectara Console UI](https://docs.vectara.com/docs/console-ui/creating-a-corpus) + or the [Create Corpus API definition](https://docs.vectara.com/docs/api-reference/admin-apis/create-corpus). + When creating a new corpus, you have the option to assign a custom `corpus_key` + following your preferred naming convention. This key serves as a unique identifier + for the corpus, allowing it to be referenced in search requests. For more + information, see [Corpus Key Definition](https://docs.vectara.com/docs/api-reference/search-apis/search#corpus-key-definition). + * Enter the search `query` string for the corpus, which is the question you + want to ask. * Set the maximum number of results (`limit`) to return. **Default**: + 10, **minimum**: 1 * Define the `offset` position from which to start in the + result set. + + For more detailed information, see this [Query API guide](https://docs.vectara.com/docs/api-reference/search-apis/search).' + operationId: searchCorpus + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the corpus to query. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + - in: query + name: query + description: The search query string for the corpus, which is the question + the user is asking. + required: true + schema: + type: string + - in: query + name: limit + description: The maximum number of top retrieval results to rerank and return. + required: false + schema: + type: integer + default: 10 + minimum: 1 + - in: query + name: offset + description: The position from which to start in the result set. + required: false + schema: + type: integer + default: 0 + minimum: 0 + - in: query + name: save_history + description: Indicates whether to save the query in the query history. + schema: + type: boolean + - in: query + name: intelligent_query_rewriting + description: '[Tech Preview] 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. Read [here](https://docs.vectara.com/docs/search-and-retrieval/intelligent-query-rewriting) + for more details.' + schema: + type: boolean + default: false + responses: + '200': + description: A response to a query. + content: + application/json: + schema: + $ref: '#/components/schemas/QueryFullResponse' + '400': + description: Query request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow querying the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: corpora + x-fern-sdk-method-name: search + post: + tags: + - Queries + summary: Advanced Single Corpus Query + description: 'Perform an advanced query on a specific corpus to find relevant + results, highlight relevant snippets, and use Retrieval Augmented Generation: + + * Specify the unique `corpus_key` identifying the corpus to query. The `corpus_key` + is [created in the Vectara Console UI](https://docs.vectara.com/docs/console-ui/creating-a-corpus) + or the [Create Corpus API definition](https://docs.vectara.com/docs/api-reference/admin-apis/create-corpus). + When creating a new corpus, you have the option to assign a custom `corpus_key` + following your preferred naming convention. This key serves as a unique identifier + for the corpus, allowing it to be referenced in search requests. For more + information, see [Corpus Key Definition](https://docs.vectara.com/docs/api-reference/search-apis/search#corpus-key-definition). + * Customize your search by specifying the query text (`query`), pagination + details (`offset` and `limit`), and metadata filters (`metadata_filter`) to + tailor your search results. [Learn more](https://docs.vectara.com/docs/api-reference/search-apis/search#query-definition) + * Leverage advanced search capabilities like reranking (`reranker`) and Retrieval + Augmented Generation (RAG) (`generation`) for enhanced query performance. + Generation is opt in by setting the `generation` property. By excluding the + property or by setting it to null, the response will not include generation. + [Learn more](https://docs.vectara.com/docs/learn/grounded-generation/configure-query-summarization). + * Use hybrid search to achieve optimal results by setting different values + for `lexical_interpolation` (e.g., `0.025`). [Learn more](https://docs.vectara.com/docs/learn/hybrid-search) + * Specify Vectara''s RAG-focused LLM (Mockingbird) for the `generation_preset_name`. + [Learn more](https://docs.vectara.com/docs/learn/mockingbird-llm) * Use advanced + summarization options that utilize detailed summarization parameters such + as `max_response_characters`, `temperature`, and `frequency_penalty` for generating + precise and relevant summaries. [Learn more](https://docs.vectara.com/docs/api-reference/search-apis/search#advanced-summarization-options) + + For more detailed information, see [Query API guide](https://docs.vectara.com/docs/api-reference/search-apis/search).' + operationId: queryCorpus + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the corpus to query. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/QueryCorpusRequest' + x-stream-based-on-body: streamResponse() + responses: + '200': + description: A response to a query. + content: + application/json: + schema: + $ref: '#/components/schemas/QueryFullResponse' + text/event-stream: + schema: + $ref: '#/components/schemas/QueryStreamedResponse' + '400': + description: Query request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow querying the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-streaming: + format: sse + stream-condition: $request.stream_response + response: + $ref: '#/components/schemas/QueryFullResponse' + response-stream: + $ref: '#/components/schemas/QueryStreamedResponse' + x-fern-sdk-group-name: corpora + x-fern-sdk-method-name: query + /v2/query: + post: + tags: + - Queries + summary: Multiple Corpora Query + description: 'Perform a multipurpose query across to retrieve relevant information + from one or more corpora and generate a response using Retrieval Augmented + Generation (RAG). + + * Specify the unique `corpus_key` identifying the corpus to query. The `corpus_key` + is [created in the Vectara Console UI](https://docs.vectara.com/docs/console-ui/creating-a-corpus) + or the [Create Corpus API definition](https://docs.vectara.com/docs/api-reference/admin-apis/create-corpus). + When creating a new corpus, you have the option to assign a custom `corpus_key` + following your preferred naming convention. This key serves as a unique identifier + for the corpus, allowing it to be referenced in search requests. For more + information, see [Corpus Key Definition](https://docs.vectara.com/docs/api-reference/search-apis/search#corpus-key-definition). + * Customize your search by specifying the query text (`query`), pagination + details (`offset` and `limit`), and metadata filters (`metadata_filter`) to + tailor your search results. [Learn more](https://docs.vectara.com/docs/api-reference/search-apis/search#query-definition) + * Leverage advanced search capabilities like reranking (`reranker`) and opt-in + Retrieval Augmented Generation (RAG) (`generation`) for enhanced query performance. + Generation is opt in by setting the `generation` property. By excluding the + property or by setting it to null, the response will not include generation. + [Learn more](https://docs.vectara.com/docs/learn/grounded-generation/configure-query-summarization) + * Specify Vectara''s RAG-focused LLM (Mockingbird) for the `generation_preset_name`. + [Learn more](https://docs.vectara.com/docs/learn/mockingbird-llm) * Use advanced + summarization options that utilize detailed summarization parameters such + as `max_response_characters`, `temperature`, and `frequency_penalty` for generating + precise and relevant summaries. [Learn more](https://docs.vectara.com/docs/api-reference/search-apis/search#advanced-summarization-customization-options) + * Customize citation formats in summaries using the `citations` object to + include numeric, HTML, or Markdown links. [Learn more](https://docs.vectara.com/docs/api-reference/search-apis/search#citation-format-in-summary) + + For more detailed information, see this [Query API guide](https://docs.vectara.com/docs/api-reference/search-apis/search).' + operationId: query + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/QueryRequest' + x-stream-based-on-body: streamResponse() + responses: + '200': + description: A response to a query. + content: + application/json: + schema: + $ref: '#/components/schemas/QueryFullResponse' + text/event-stream: + schema: + $ref: '#/components/schemas/QueryStreamedResponse' + '400': + description: Query request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow querying one or more corpora in the + request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: One or more of the corpora were not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-streaming: + stream-condition: $request.stream_response + format: sse + response: + $ref: '#/components/schemas/QueryFullResponse' + response-stream: + $ref: '#/components/schemas/QueryStreamedResponse' + x-fern-sdk-method-name: query + x-fern-examples: + - name: Batch + request: + stream_response: false + query: What is a hallucination? + search: + corpora: + - corpus_key: corpus_key + metadata_filter: '' + lexical_interpolation: 0.005 + context_configuration: + sentences_before: 2 + sentences_after: 2 + reranker: + type: customer_reranker + reranker_id: rnk_272725719 + generation: + response_language: eng + enable_factual_consistency_score: true + response: + body: {} + - name: Stream + request: + stream_response: true + query: What is a hallucination? + search: + corpora: + - corpus_key: corpus_key + metadata_filter: '' + lexical_interpolation: 0.005 + context_configuration: + sentences_before: 2 + sentences_after: 2 + reranker: + type: customer_reranker + reranker_id: rnk_272725719 + generation: + response_language: eng + enable_factual_consistency_score: true + response: + stream: [] + x-fern-sdk-group-name: queries + /v2/corpora/{corpus_key}/upload_file: + post: + tags: + - Upload + summary: Upload a file to the corpus + description: 'Upload files such as PDFs and Word Documents for automatic text + extraction and metadata parsing. + + The request expects a `multipart/form-data` format containing the following + parts: + + * `metadata` - Optionally specifies a JSON object representing any additional + metadata to be associated with the extracted document. For example, `''metadata={"key": + "value"};type=application/json''` * `chunking_strategy` - If provided, specifies + the chunking strategy for the platform to use. If you do not set this option, + the platform uses the default strategy, which creates one chunk per sentence. + You can explicitly set sentence chunking with `''chunking_strategy={"type":"sentence_chunking_strategy"};type=application/json''` + or use max chars chunking with `''chunking_strategy={"type":"max_chars_chunking_strategy","max_chars_per_chunk":200};type=application/json''` + * `table_extraction_config` - You can optionally specify whether to extract + table data from the uploaded file. If you do not set this option, the platform + does not extract tables from PDF files. Example config, `''table_extraction_config={"extract_tables":true};type=application/json''` + * `file` - Specifies the file that you want to upload. * `filename` - Specified + as part of the file field with the file name that you want to associate with + the uploaded file. For a curl example, use the following syntax: `''file=@/path/to/file/file.pdf;filename=desired_filename.pdf''` + + For more detailed information, see this [File Upload API guide.](https://docs.vectara.com/docs/api-reference/indexing-apis/file-upload/file-upload)' + operationId: uploadFile + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the corpus of which to upload the + file. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + requestBody: + description: Upload a file for the Vectara platform to attempt to parse and + turn into a document within the corpus. The first part of the multipart + request can contain any document metadata to attach to the parsed document. + Only one document may be uploaded at a time. + content: + multipart/form-data: + schema: + $ref: '#/components/schemas/UploadFileRequest' + encoding: + metadata: + contentType: application/json + chunking_strategy: + contentType: application/json + table_extraction_config: + contentType: application/json + file: + contentType: application/octet-stream, application/pdf, application/msword, + application/vnd.openxmlformats-officedocument.wordprocessingml.document, + application/vnd.oasis.opendocument.text, application/epub+zip, application/rtf, + text/html, text/plain, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation, + text/markdown + filename: + contentType: text/plain + responses: + '201': + description: The extracted document has been parsed and added to the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Document' + '400': + description: Upload file request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow uploading a file to the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + '415': + description: The media type of the uploaded file is not supported. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-examples: + - code-samples: + - language: python + code: "from vectara import Vectara\n\nclient = Vectara(\n api_key=\"\ + YOUR_API_KEY\",\n # or\n client_id=\"YOUR_CLIENT_ID\",\n client_secret=\"\ + YOUR_CLIENT_SECRET\",\n)\nclient.upload.file(\n corpus_key=corpus_key,\n\ + \ file=content,\n filename=slugify(url),\n)\n" + x-fern-sdk-group-name: upload + x-fern-sdk-method-name: file + /v2/corpora/{corpus_key}/documents: + post: + tags: + - Index + summary: Add a document to a corpus + description: 'Add a document to a corpus. This endpoint supports two document + formats, structured and core. + + * **Structured** documents have a more conventional structure that provide + document sections and parts in a format created by Vectara''s proprietary + strategy automatically. You provide a logical document structure, and Vectara + handles the partitioning. * **Core** documents differ in that they follow + an advanced, granular structure that explicitly defines each document part + in an array. Each part becomes a distinct, searchable item in query results. + You have precise control over the document structure and content. + + For more details, see [Indexing](https://docs.vectara.com/docs/learn/select-ideal-indexing-api).' + operationId: createCorpusDocument + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the queried corpus. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateDocumentRequest' + responses: + '201': + description: Document added to the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Document' + '400': + description: Document creation request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow adding a document to the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + '409': + description: The document already exists + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: documents + x-fern-sdk-method-name: create + x-fern-examples: + - path-parameters: + corpus_key: my-corpus-key + request: + id: my-doc-id + type: structured + sections: + - id: 1 + title: A nice title. + text: I'm a nice document section. + metadata: + section: '1.1' + - id: 2 + title: Another nice title. + text: I'm another document section on something else. + metadata: + section: '1.2' + metadata: + url: https://example.com + response: + body: {} + get: + tags: + - Documents + summary: List the documents in the corpus + description: Retrieve a list of documents stored in a specific corpus. This + endpoint provides an overview of document metadata without returning the full + content of each document. + operationId: listCorpusDocuments + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the queried corpus. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + - name: limit + in: query + description: The maximum number of documents to return at one time. + required: false + schema: + type: integer + format: int32 + minimum: 1 + maximum: 100 + default: 10 + - name: metadata_filter + in: query + description: Filter documents by metadata. Uses the same expression as a query + metadata filter, but only allows filtering on document metadata. + required: false + schema: + type: string + - name: page_key + in: query + description: Used to retrieve the next page of documents after the limit has + been reached. + required: false + schema: + type: string + responses: + '200': + description: List of documents. + content: + application/json: + schema: + $ref: '#/components/schemas/ListDocumentsResponse' + '403': + description: Permissions do not allow listing documents in the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: documents + x-fern-sdk-method-name: list + x-fern-pagination: + cursor: $request.page_key + next_cursor: $response.metadata.page_key + results: $response.documents + /v2/corpora/{corpus_key}/documents/{document_id}: + delete: + tags: + - Documents + summary: Delete a document + description: Permanently delete a document identified by its unique `document_id` + from a specific corpus. This operation cannot be undone, so use it with caution. + operationId: deleteCorpusDocument + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the corpus with the document to delete. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + - in: path + name: document_id + description: The document ID of the document to delete. This `document_id` + must be percent encoded. + required: true + schema: + type: string + responses: + '204': + description: Successfully deleted the document. + '403': + description: Permissions do not allow deleting a document in the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus or document not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: documents + x-fern-sdk-method-name: delete + get: + tags: + - Documents + summary: Retrieve a document + description: Retrieve the content and metadata of a specific document, identified + by its unique `document_id` from a specific corpus. + operationId: getCorpusDocument + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the corpus containing the document + to retrieve. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + - in: path + name: document_id + description: The document ID of the document to retrieve. This `document_id` + must be percent encoded. + required: true + schema: + type: string + responses: + '200': + description: Successfully retrieved the document. + content: + application/json: + schema: + $ref: '#/components/schemas/Document' + '403': + description: Permissions do not allow retrieving a document from the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus or document not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: documents + x-fern-sdk-method-name: get + patch: + tags: + - Index + summary: Update document, merging the metadata. + description: Updates document identified by its unique `document_id` from a + specific corpus. The request body metadata is merged with the existing metadata, + adding or modifying only the specified fields. + operationId: updateCorpusDocument + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the corpus with the document to update. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + - in: path + name: document_id + description: The document ID of the document to update. This `document_id` + must be percent encoded. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateDocumentRequest' + responses: + '200': + description: Successfully updated the document. + content: + application/json: + schema: + $ref: '#/components/schemas/Document' + '403': + description: Permissions do not allow updating a document in the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus or document not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + '429': + description: Too many concurrent requests. Please retry. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: documents + x-fern-sdk-method-name: update + /v2/corpora/{corpus_key}/documents/{document_id}/metadata: + put: + tags: + - Index + summary: Replace the document metadata. + description: Replaces metadata of a document identified by its unique `document_id` + from a specific corpus. + operationId: replaceCorpusDocumentMetadata + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the corpus with the document to update. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + - in: path + name: document_id + description: The document ID of the document to update. This `document_id` + must be percent encoded. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateDocumentRequest' + responses: + '200': + description: Successfully updated the document. + content: + application/json: + schema: + $ref: '#/components/schemas/Document' + '403': + description: Permissions do not allow updating a document in the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus or document not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + '429': + description: Too many concurrent requests. Please retry. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: documents + x-fern-sdk-method-name: update_metadata + /v2/corpora/{corpus_key}/documents/{document_id}/summarize: + post: + tags: + - Documents + summary: Summarize a document + description: Summarize a document identified by its unique `document_id` from + a specific corpus. + operationId: summarizeCorpusDocument + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: corpus_key + description: The unique key identifying the corpus containing the document + to retrieve. + required: true + schema: + $ref: '#/components/schemas/CorpusKey' + - in: path + name: document_id + description: The document ID of the document to retrieve. This `document_id` + must be percent encoded. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SummarizeDocumentRequest' + x-stream-based-on-body: streamResponse() + responses: + '200': + description: Document summarization response on success. + content: + application/json: + schema: + $ref: '#/components/schemas/SummarizeDocumentResponse' + text/event-stream: + schema: + $ref: '#/components/schemas/SummarizeDocumentStreamedResponse' + '403': + description: Permissions do not allow summarizing a document in the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus or document not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: documents + x-fern-sdk-method-name: summarize + /v2/chats: + post: + tags: + - Chats + summary: Start a chat + description: Create a chat while specifying the default retrieval parameters + used by the prompt. + operationId: createChat + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ChatRequest' + x-stream-based-on-body: streamResponse() + responses: + '200': + description: A response to a chat request. + content: + application/json: + schema: + $ref: '#/components/schemas/ChatFullResponse' + text/event-stream: + schema: + $ref: '#/components/schemas/ChatStreamedResponse' + '400': + description: Chat creation request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow creating a chat in the corpus. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-streaming: + format: sse + stream-condition: $request.stream_response + response: + $ref: '#/components/schemas/ChatFullResponse' + response-stream: + $ref: '#/components/schemas/ChatStreamedResponse' + x-fern-sdk-method-name: create + x-fern-examples: + - name: Batch + request: + stream_response: false + query: What is a hallucination? + search: + corpora: + - corpus_key: corpus_key + metadata_filter: '' + lexical_interpolation: 0.005 + context_configuration: + sentences_before: 2 + sentences_after: 2 + reranker: + type: customer_reranker + reranker_id: rnk_272725719 + generation: + response_language: eng + enable_factual_consistency_score: true + citations: + style: none + chat: + store: true + response: + body: {} + - name: Stream + request: + stream_response: true + query: What is a hallucination? + search: + corpora: + - corpus_key: corpus_key + metadata_filter: '' + lexical_interpolation: 0.005 + context_configuration: + sentences_before: 2 + sentences_after: 2 + reranker: + type: customer_reranker + reranker_id: rnk_272725719 + generation: + response_language: eng + citations: + style: none + enable_factual_consistency_score: true + chat: + store: true + response: + stream: [] + x-fern-sdk-group-name: chats + get: + tags: + - Chats + summary: List chats + description: Retrieve a list of previous chats in the Vectara account. + operationId: listChats + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: query + name: limit + description: The maximum number of results to return in the list. + schema: + type: integer + format: int32 + minimum: 1 + maximum: 10000 + default: 1000 + - in: query + name: page_key + description: Used to retrieve the next page of chats after the limit has been + reached. + required: false + schema: + type: string + responses: + '200': + description: List of chats. + content: + application/json: + schema: + $ref: '#/components/schemas/ListChatsResponse' + '403': + description: Permissions do not allow listing chats. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: chats + x-fern-sdk-method-name: list + x-fern-pagination: + cursor: $request.page_key + next_cursor: $response.metadata.page_key + results: $response.chats + /v2/llms: + post: + tags: + - Large Language Models + summary: Create an LLM + description: Create a new LLM for use with query and chat endpoints + operationId: createLLM + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateLLMRequest' + responses: + '201': + description: The LLM has been created + content: + application/json: + schema: + $ref: '#/components/schemas/LLM' + '400': + description: Invalid request body + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow creating an LLM + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: llms + x-fern-sdk-method-name: create + get: + tags: + - Large Language Models + summary: List LLMs + description: List LLMs that can be used with query and chat endpoints. The LLM + is not directly specified in a query, but instead a `generation_preset_name` + is used. The `generation_preset_name` property in generation parameters can + be found as the `name` property on the Generations Presets retrieved from + `/v2/generation_presets`. + operationId: listLLMs + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: filter + in: query + description: A regular expression to match names and descriptions of the LLMs. + required: false + schema: + type: string + - name: limit + in: query + description: The maximum number of results to return in the list. + required: false + schema: + type: integer + format: int32 + minimum: 1 + maximum: 100 + default: 10 + - name: page_key + in: query + description: Used to retrieve the next page of LLMs after the limit has been + reached. This parameter is not needed for the first page of results. + required: false + schema: + type: string + responses: + '200': + description: List of LLMs. + content: + application/json: + schema: + $ref: '#/components/schemas/ListLLMsResponse' + '403': + description: Permissions do not allow listing summarizers. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: llms + x-fern-sdk-method-name: list + x-fern-pagination: + cursor: $request.page_key + next_cursor: $response.metadata.page_key + results: $response.llms + /v2/llms/{llm_id}: + get: + tags: + - Large Language Models + summary: Get an LLM + description: Get details about a specific LLM. + operationId: getLLM + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: llm_id + in: path + description: The name of the LLM to retrieve. + required: true + schema: + type: string + responses: + '200': + description: The LLM details. + content: + application/json: + schema: + $ref: '#/components/schemas/LLM' + '403': + description: Permissions do not allow retrieving this LLM. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: LLM not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: llms + x-fern-sdk-method-name: get + delete: + tags: + - Large Language Models + summary: Delete an LLM + description: Delete a custom LLM connection. Built-in LLMs cannot be deleted. + operationId: deleteLLM + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: llm_id + in: path + description: The name of the LLM to delete. + required: true + schema: + type: string + responses: + '204': + description: The LLM was successfully deleted. + '403': + description: Permissions do not allow deleting this LLM. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: LLM not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: llms + x-fern-sdk-method-name: delete + /v2/generation_presets: + get: + tags: + - Generation Presets + summary: List generation presets + description: List generation presets used for query or chat requests. Generation + presets are the build of properties used to configure generation for a request. + This includes the template that renders the prompt, and various generation + settings like `temperature`. + operationId: listGenerationPresets + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: llm_name + in: query + description: Filter presets by the LLM name. + required: false + schema: + type: string + - name: limit + in: query + description: The maximum number of results to return in the list. + required: false + schema: + type: integer + format: int32 + minimum: 1 + maximum: 100 + default: 10 + - name: page_key + in: query + description: Used to retrieve the next page of generation presets after the + limit has been reached. This parameter is not needed for the first page + of results. + required: false + schema: + type: string + responses: + '200': + description: List of Generation Presets. + content: + application/json: + schema: + $ref: '#/components/schemas/ListGenerationPresetsResponse' + '403': + description: Permissions do not allow listing generation presets. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: generation_presets + x-fern-sdk-method-name: list + x-fern-pagination: + cursor: $request.page_key + next_cursor: $response.metadata.page_key + results: $response.generation_presets + /v2/chats/{chat_id}: + get: + tags: + - Chats + summary: Get a chat + description: Get a chat summary to view what started the chat, but not subsequent + turns. + operationId: getChat + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: chat_id + description: The ID of the chat. + required: true + schema: + type: string + pattern: cht_.+$ + responses: + '200': + description: A chat. + content: + application/json: + schema: + $ref: '#/components/schemas/Chat' + '403': + description: Permissions do not allow retrieving the chat. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus or chat not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: chats + x-fern-sdk-method-name: get + delete: + tags: + - Chats + summary: Delete a chat + description: Delete a chat and any turns it contains permanently. + operationId: deleteChat + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: chat_id + description: The ID of the chat. + required: true + schema: + type: string + pattern: cht_.+$ + responses: + '204': + description: Successfully deleted the chat. + '403': + description: Permissions do not allow deleting the chat. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus or chat not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: chats + x-fern-sdk-method-name: delete + /v2/chats/{chat_id}/turns: + post: + tags: + - Chats + summary: Create a new turn in the chat + description: 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. + operationId: createChatTurn + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: chat_id + description: The ID of the chat. + required: true + schema: + type: string + pattern: cht_.+$ + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ChatRequest' + x-stream-based-on-body: streamResponse() + responses: + '200': + description: A response to a chat request. + content: + application/json: + schema: + $ref: '#/components/schemas/ChatFullResponse' + text/event-stream: + schema: + $ref: '#/components/schemas/ChatStreamedResponse' + '400': + description: Turn creation request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow creating a turn in the chat. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus or chat not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-streaming: + format: sse + stream-condition: $request.stream_response + response: + $ref: '#/components/schemas/ChatFullResponse' + response-stream: + $ref: '#/components/schemas/ChatStreamedResponse' + x-fern-sdk-group-name: chats + x-fern-sdk-method-name: createTurns + get: + tags: + - Chats + summary: List turns in a chat + description: List all turns in a chat to see all message and response pairs + that make up the dialog. + operationId: listChatTurns + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: chat_id + description: The ID of the chat. + required: true + schema: + type: string + pattern: cht_.+$ + responses: + '200': + description: List of turns. + content: + application/json: + schema: + $ref: '#/components/schemas/ListChatTurnsResponse' + '403': + description: Permissions do not allow listing turns in the chat. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus or chat not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: chats + x-fern-sdk-method-name: listTurns + /v2/chats/{chat_id}/turns/{turn_id}: + get: + tags: + - Chats + summary: Get a turn + description: Get a specific turn from a chat, which is a message and response + pair from the conversation. + operationId: getChatTurn + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: chat_id + description: The ID of the chat. + required: true + schema: + type: string + pattern: cht_.+$ + - in: path + name: turn_id + description: The ID of the turn. + required: true + schema: + type: string + pattern: trn_.+$ + responses: + '200': + description: The turn. + content: + application/json: + schema: + $ref: '#/components/schemas/Turn' + '403': + description: Permissions do not allow getting the turn. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus, chat, or turn not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: chats + x-fern-sdk-method-name: getTurn + delete: + tags: + - Chats + summary: Delete a turn + description: Delete a turn from a chat. This will delete all subsequent turns + in the chat. + operationId: deleteChatTurn + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: chat_id + description: The ID of the chat. + required: true + schema: + type: string + pattern: cht_.+$ + - in: path + name: turn_id + description: The ID of the turn. + required: true + schema: + type: string + pattern: trn_.+$ + responses: + '204': + description: Successfully deleted a turn. + '403': + description: Permissions do not allow deleting the turn. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus, chat, or turn not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: chats + x-fern-sdk-method-name: deleteTurn + patch: + tags: + - Chats + summary: Update a turn + description: Update a turn; used to disable or enable a chat. + operationId: updateChatTurn + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: path + name: chat_id + description: The ID of the chat. + required: true + schema: + type: string + pattern: cht_.+$ + - in: path + name: turn_id + description: The ID of the turn. + required: true + schema: + type: string + pattern: trn_.+$ + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateTurnRequest' + responses: + '200': + description: Successfully modified the turn. + content: + application/json: + schema: + $ref: '#/components/schemas/Turn' + '403': + description: Permissions do not allow updating the turn. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Corpus, chat, or turn not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: chats + x-fern-sdk-method-name: updateTurn + /v2/evaluate_factual_consistency: + post: + tags: + - Factual Consistency Evaluation + summary: Evaluate factual consistency + description: Evaluate the factual consistency of a generated text (like a summary) + against source documents. This determines how accurately the generated text + reflects the information in the source documents, helping identify potential + hallucinations or misrepresentations. + operationId: evaluateFactualConsistency + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluateFactualConsistencyRequest' + responses: + '200': + description: The factual consistency evaluation results. + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluateFactualConsistencyResponse' + '400': + description: Invalid request body. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow factual consistency evaluation. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '422': + description: Language not supported by the factual consistency service. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: factual-consistency + x-fern-sdk-method-name: evaluate + /v2/encoders: + post: + tags: + - Encoders + summary: Create an encoder + description: Create a new encoder. + operationId: createEncoder + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateEncoderRequest' + responses: + '201': + description: The encoder has been created + content: + application/json: + schema: + $ref: '#/components/schemas/Encoder' + '400': + description: Encoder creation request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow creating an encoder + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: encoders + x-fern-sdk-method-name: create + get: + tags: + - Encoders + summary: List encoders + description: Encoders are used to store and retrieve from a corpus. + operationId: listEncoders + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: query + name: filter + description: A regular expression against encoder names and descriptions. + required: false + schema: + type: string + example: vectara.* + - in: query + name: limit + description: The maximum number of results to return in the list. + required: false + schema: + type: integer + format: int32 + minimum: 1 + maximum: 100 + default: 10 + - name: page_key + in: query + description: Used to retrieve the next page of encoders after the limit has + been reached. + required: false + schema: + type: string + responses: + '200': + description: List of encoders. + content: + application/json: + schema: + $ref: '#/components/schemas/ListEncodersResponse' + '403': + description: Permissions do not allow listing encoders. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: encoders + x-fern-sdk-method-name: list + x-fern-pagination: + cursor: $request.page_key + next_cursor: $response.metadata.page_key + results: $response.encoders + /v2/rerankers: + get: + tags: + - Rerankers + summary: List rerankers + description: Rerankers are used to improve the ranking (ordering) of search + results. + operationId: listRerankers + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: query + name: filter + description: A regular expression against reranker names and descriptions. + required: false + schema: + type: string + example: vectara.* + - in: query + name: limit + description: The maximum number of rerankers to return in the list. + required: false + schema: + type: integer + format: int32 + minimum: 1 + maximum: 100 + default: 10 + - name: page_key + in: query + description: Used to retrieve the next page of rerankers after the limit has + been reached. + required: false + schema: + type: string + responses: + '200': + description: List of rerankers. + content: + application/json: + schema: + $ref: '#/components/schemas/ListRerankersResponse' + '403': + description: Permissions do not allow listing rerankers. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: rerankers + x-fern-sdk-method-name: list + x-fern-pagination: + cursor: $request.page_key + next_cursor: $response.metadata.page_key + results: $response.rerankers + /v2/table_extractors: + get: + tags: + - Table Extractors + summary: List supported table extractors + description: Table extractors are used to extract tabular data from documents + during indexing. + operationId: listTableExtractors + x-fern-sdk-group-name: table_extractors + x-fern-sdk-method-name: list + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + responses: + '200': + description: List of supported table extractors. + content: + application/json: + schema: + $ref: '#/components/schemas/ListTableExtractorsResponse' + '403': + description: Permissions do not allow listing table extractors. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /v2/hallucination_correctors: + get: + tags: + - Hallucination Correctors + summary: List hallucination correctors + description: Retrieves a list of available hallucination correctors used for + detecting and correcting hallucinations in AI-generated content. This endpoint + supports filtering by name or description, pagination, and metadata for navigating + large result sets. + operationId: listHallucinationCorrectors + x-fern-sdk-group-name: hallucination_correctors + x-fern-sdk-method-name: list + x-fern-pagination: + cursor: $request.page_key + next_cursor: $response.metadata.page_key + results: $response.hallucinationCorrectionModels + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - in: query + name: filter + description: A regular expression applied to the name and description fields. + Use this to return only hallucination correctors that match specific keywords + or naming conventions. + required: false + schema: + type: string + - in: query + name: limit + description: The maximum number of hallucination correctors to return in the + list. Defaults to 10. Range is between 1 and 100. + required: false + schema: + type: integer + format: int32 + minimum: 1 + maximum: 100 + default: 10 + - name: page_key + in: query + description: Retrieves the next page of hallucination correctors after reaching + the limit. + required: false + schema: + type: string + responses: + '200': + description: List of hallucination correctors. + content: + application/json: + schema: + $ref: '#/components/schemas/ListHallucinationCorrectorsResponse' + '403': + description: Permissions do not allow listing hallucination correctors. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /v2/hallucination_correctors/correct_hallucinations: + post: + tags: + - Hallucination Correctors + summary: Corrects hallucinations in generated text based on source documents + description: This endpoint identifies information in generated text that is + not supported by the provided source documents and offers corrections with + minimal changes. This can be used standalone or as part of a RAG workflow + where the HHEM score indicates potential hallucinations. + operationId: correctHallucinations + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/HallucinationCorrectionRequest' + responses: + '200': + description: Successfully analyzed the text for hallucinations + content: + application/json: + schema: + $ref: '#/components/schemas/HallucinationCorrectionResponse' + '400': + description: Request was malformed + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow hallucination correction + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: hallucination_correctors + x-fern-sdk-method-name: hallucinationCorrection + /v2/jobs: + get: + tags: + - Jobs + summary: List jobs + description: List jobs for the account. Jobs are background processes like replacing + the filterable metadata attributes. + operationId: listJobs + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: corpus_key + in: query + description: The unique key identifying the corpus with the job. + required: false + schema: + type: array + items: + $ref: '#/components/schemas/CorpusKey' + - name: after + in: query + description: Filter by jobs created after a particular date-time. + required: false + schema: + type: string + format: date-time + - name: state + in: query + description: Filter by jobs in particular states. + required: false + schema: + type: array + items: + $ref: '#/components/schemas/JobState' + - name: limit + in: query + description: The maximum number of jobs to return at one time. + required: false + schema: + type: integer + format: int32 + minimum: 1 + maximum: 100 + default: 10 + - name: page_key + in: query + description: Used to retrieve the next page of jobs after the limit has been + reached. + required: false + schema: + type: string + responses: + '200': + description: List of jobs. + content: + application/json: + schema: + $ref: '#/components/schemas/ListJobsResponse' + '403': + description: Permissions do not allow listing jobs. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: jobs + x-fern-sdk-method-name: list + x-fern-pagination: + cursor: $request.page_key + next_cursor: $response.metadata.page_key + results: $response.jobs + /v2/jobs/{job_id}: + get: + tags: + - Jobs + summary: Get a job by ID + description: Get a job by a specific ID. Jobs are background processes like + replacing the filterable metadata attributes. + operationId: getJob + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: job_id + in: path + description: The ID of the job to get. + required: true + schema: + type: string + pattern: job_.+$ + responses: + '200': + description: A job. + content: + application/json: + schema: + $ref: '#/components/schemas/Job' + '403': + description: Permissions do not allow retrieving a job. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Job not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: jobs + x-fern-sdk-method-name: get + /v2/users: + post: + tags: + - Users + summary: Create a user in the current customer account + description: Create a user for the current customer account. + operationId: createUser + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateUserRequest' + responses: + '201': + description: The created user. + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/User' + - properties: + one_time_code: + type: string + description: A one time code for the newly created user to create + a password. This is optional, and is only populated for some + Vectara deployments. + one_time_code_link: + type: string + description: The link where to enter the `one_time_code`. This + is optional, and is only populated for some Vectara deployments. + '400': + description: User creation request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow retrieving a user. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: users + x-fern-sdk-method-name: create + get: + tags: + - Users + summary: List users in the account + description: Lists all users in the account. + operationId: listUsers + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: limit + in: query + description: The maximum number of users to return at one time. + required: false + schema: + type: integer + format: int32 + minimum: 1 + maximum: 100 + default: 10 + - name: page_key + in: query + description: Used to retrieve the next page of users after the limit has been + reached. + required: false + schema: + type: string + - name: corpus_key + in: query + description: Filter users by access to this corpus. + required: false + schema: + $ref: '#/components/schemas/CorpusKey' + responses: + '200': + description: List of users. + content: + application/json: + schema: + $ref: '#/components/schemas/ListUsersResponse' + '403': + description: Permissions do not allow listing users. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: users + x-fern-sdk-method-name: list + x-fern-pagination: + cursor: $request.page_key + next_cursor: $response.metadata.page_key + results: $response.users + /v2/users/{username}: + get: + tags: + - Users + summary: Get a user + description: Get a user and view details like the email, username, and associated + roles. + operationId: getUser + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: username + in: path + description: Specifies the user ID that to retrieve. Note that the username + must be percent encoded. + required: true + schema: + type: string + responses: + '200': + description: A user. + content: + application/json: + schema: + $ref: '#/components/schemas/User' + '403': + description: Permissions do not allow retrieving the user. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: User not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: users + x-fern-sdk-method-name: get + patch: + tags: + - Users + summary: Update a user + description: Update details about a user such as role names. + operationId: updateUser + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: username + in: path + description: Specifies the user ID to update. Note that the username must + be percent encoded. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateUserRequest' + responses: + '200': + description: New user after modification. + content: + application/json: + schema: + $ref: '#/components/schemas/User' + '403': + description: Permissions do not allow updating the user. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: User not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: users + x-fern-sdk-method-name: update + delete: + tags: + - Users + summary: Delete a user + description: Delete a user from the account. + operationId: deleteUser + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: username + in: path + description: Specifies the user ID to delete. Note that the username must + be percent encoded. + required: true + schema: + type: string + responses: + '204': + description: User was successfully deleted. + '403': + description: Permissions do not allow deleting the user. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: User not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: users + x-fern-sdk-method-name: delete + /v2/users/{username}/reset_password: + post: + tags: + - Users + summary: Reset the password for a user + description: Reset the password for a user. + operationId: resetUserPassword + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: username + in: path + description: Specifies the user ID to update. Note that the username must + be percent encoded and URI safe. + required: true + schema: + type: string + responses: + '200': + description: User was sent the password reset email. + content: + application/json: + schema: + type: object + properties: + one_time_code: + type: string + description: A one time code that can be used to reset the password. + This is optional, and is only populated for some Vectara deployments. + one_time_code_link: + type: string + description: The link where to enter the `one_time_code`. This + is optional, and is only populated for some Vectara deployments. + '403': + description: Permissions do not allow resetting the user password. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: User not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: users + x-fern-sdk-method-name: resetPassword + /v2/api_keys: + post: + tags: + - API Keys + summary: Create an API key + description: An API key is to authenticate when calling Vectara APIs. + operationId: createApiKey + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateApiKeyRequest' + responses: + '201': + description: An API key object, used to query the Vectara API with the assigned + roles. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiKey' + '400': + description: API key creation request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow creating the API key. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: apiKeys + x-fern-sdk-method-name: create + get: + tags: + - API Keys + summary: List API keys + description: Retrieve a list of API keys for the customer account with optional + filtering. + operationId: listApiKeys + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: limit + in: query + description: Max number of API keys to return at one time. + required: false + schema: + type: integer + format: int32 + minimum: 1 + maximum: 100 + default: 10 + - name: page_key + in: query + description: Used to retrieve the next page of API keys after the limit has + been reached. + required: false + schema: + type: string + - name: corpus_key + in: query + description: Filters the API keys to only those with permissions on the specified + corpus key. + required: false + schema: + $ref: '#/components/schemas/CorpusKey' + - name: api_key_role + in: query + description: Filter API keys by their role. + required: false + schema: + $ref: '#/components/schemas/ApiKeyRole' + responses: + '200': + description: An array of API keys. + content: + application/json: + schema: + $ref: '#/components/schemas/ListApiKeysResponse' + '400': + description: API key list request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow listing API keys. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: apiKeys + x-fern-sdk-method-name: list + x-fern-pagination: + cursor: $request.page_key + next_cursor: $response.metadata.page_key + results: $response.api_keys + /v2/api_keys/{api_key_id}: + get: + tags: + - API Keys + summary: Get an API key + description: Retrieve details of a specific API key by its ID. + operationId: getApiKey + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: api_key_id + in: path + description: The ID of the API key. + required: true + schema: + type: string + responses: + '200': + description: The API key. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiKey' + '403': + description: Permissions do not allow getting this API key. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: apiKeys + x-fern-sdk-method-name: get + patch: + tags: + - API Keys + summary: Update an API key + description: Update an API key such as the roles attached to the key. + operationId: updateApiKey + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: api_key_id + in: path + description: The ID of the API key. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateApiKeyRequest' + responses: + '200': + description: The API key. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiKey' + '403': + description: Permissions do not allow getting this API key. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: apiKeys + x-fern-sdk-method-name: update + delete: + tags: + - API Keys + summary: Delete an API key + description: Delete API keys to help you manage the security and lifecycle of + API keys in your application. + operationId: deleteApiKey + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: api_key_id + in: path + description: The ID of the API key. + required: true + schema: + type: string + responses: + '204': + description: The API key was deleted. + '403': + description: Permissions do not allow deleting this API key. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: apiKeys + x-fern-sdk-method-name: delete + /v2/app_clients: + post: + tags: + - Application Clients + summary: Create an App Client + description: An App Client is used for OAuth 2.0 authentication when calling + Vectara APIs. + operationId: createAppClient + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAppClientRequest' + responses: + '201': + description: An App Client object, used to query the Vectara API with the + assigned roles. + content: + application/json: + schema: + $ref: '#/components/schemas/AppClient' + '400': + description: App Client creation request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow creating the App Client. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: appClients + x-fern-sdk-method-name: create + get: + tags: + - Application Clients + summary: List App Clients + description: Retrieve a list of application clients configured for the customer + account. + operationId: listAppClient + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: limit + in: query + description: The maximum number of App Clients to return at one time. + required: false + schema: + type: integer + format: int32 + minimum: 1 + maximum: 100 + default: 10 + - name: filter + in: query + description: Regular expression to filter the names of the App Clients. + required: false + schema: + type: string + - name: page_key + in: query + description: Used to retrieve the next page of App Clients after the limit + has been reached. + required: false + schema: + type: string + responses: + '200': + description: An array of App Clients. + content: + application/json: + schema: + $ref: '#/components/schemas/ListAppClientsResponse' + '400': + description: App Clients list request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow listing App Clients. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: appClients + x-fern-sdk-method-name: list + x-fern-pagination: + cursor: $request.page_key + next_cursor: $response.metadata.page_key + results: $response.app_clients + /v2/app_clients/{app_client_id}: + get: + tags: + - Application Clients + summary: Get an App Client + description: Retrieve details of a specific application client by its ID. + operationId: getAppClient + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: app_client_id + in: path + description: The ID of the App Client. + required: true + schema: + type: string + responses: + '200': + description: The App Client. + content: + application/json: + schema: + $ref: '#/components/schemas/AppClient' + '403': + description: Permissions do not allow getting this App Client. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: appClients + x-fern-sdk-method-name: get + patch: + tags: + - Application Clients + summary: Update an App Client + description: Update the configuration or settings of an existing application + client. + operationId: updateAppClient + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: app_client_id + in: path + description: The name of App Client. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAppClientRequest' + responses: + '200': + description: The App Client. + content: + application/json: + schema: + $ref: '#/components/schemas/AppClient' + '403': + description: Permissions do not allow updating this App Client. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: appClients + x-fern-sdk-method-name: update + delete: + tags: + - Application Clients + summary: Delete an App Client + description: Remove an application client configuration from the customer account. + operationId: deleteAppClient + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: app_client_id + in: path + description: The ID of App Client. + required: true + schema: + type: string + responses: + '204': + description: The App Client was deleted. + '403': + description: Permissions do not allow deleting this App Client. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: appClients + x-fern-sdk-method-name: delete + /v2/queries/{query_id}: + get: + tags: + - Query History + summary: Get a query history + description: Retrieve a detailed history of previously executed query. + operationId: getQueryHistory + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: query_id + in: path + description: The ID of the query history + required: true + schema: + type: string + responses: + '200': + description: The query history. + content: + application/json: + schema: + $ref: '#/components/schemas/QueryHistory' + '403': + description: Permissions do not allow retrieving the query history. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Query history not found. + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundError' + x-fern-sdk-group-name: query_history + x-fern-sdk-method-name: get + /v2/queries: + get: + tags: + - Query History + summary: List the history of previous queries + description: Retrieve query histories. + operationId: getQueryHistories + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + - name: corpus_key + in: query + description: Specifies the `corpus_key` used in the query. + required: false + schema: + type: string + - name: started_after + in: query + description: Queries that started after a particular date-time. + required: false + schema: + type: string + format: date-time + - name: started_before + in: query + description: Queries that started before a particular date-time. + required: false + schema: + type: string + format: date-time + - name: chat_id + in: query + description: Specifies the chat_id of the query, this will return all queries + in the specified chat. + required: false + schema: + type: string + - name: limit + in: query + description: Specifies the maximum number of query history listed. + schema: + type: integer + minimum: 1 + maximum: 100 + default: 10 + - name: page_key + in: query + description: Used to retrieve the next page of query histories after the limit + has been reached. + required: false + schema: + type: string + responses: + '200': + description: An array of Query Histories. + content: + application/json: + schema: + $ref: '#/components/schemas/ListQueryHistoriesResponse' + '400': + description: Query history list request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow listing query histories. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: query_history + x-fern-sdk-method-name: list + x-fern-pagination: + cursor: $request.page_key + next_cursor: $response.metadata.page_key + results: $response.queries + /oauth/token: + post: + security: [] + summary: Request an access token + description: Obtain an OAuth2 access token using client credentials + x-fern-sdk-group-name: + - auth + x-fern-sdk-method-name: getToken + x-fern-server-name: Auth + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + client_id: + type: string + description: The client ID of the application + client_secret: + type: string + description: The client secret of the application + grant_type: + x-fern-type: literal<"client_credentials"> + required: + - client_id + - client_secret + - grant_type + responses: + '200': + description: Successful response + content: + application/json: + schema: + x-fern-type-name: GetTokenResponse + type: object + properties: + access_token: + type: string + token_type: + type: string + expires_in: + type: integer + required: + - access_token + - token_type + - expires_in + operationId: getOAuthToken + tags: + - Authentication + /v2/llms/chat/completions: + post: + tags: + - LLM Chat Completions + summary: Creates a model response for the given chat conversation + description: OpenAI-compatible endpoint for chat completions. Creates a response + for the given chat conversation. The chat completion API allows you to chat + with Vectara's language models in a way that's compatible with OpenAI's specification. + This makes it easy to integrate with applications already designed for OpenAI's + API. + operationId: createChatCompletion + parameters: + - $ref: '#/components/parameters/RequestTimeout' + - $ref: '#/components/parameters/RequestTimeoutMillis' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateChatCompletionRequest' + x-stream-based-on-body: stream() + responses: + '200': + description: A chat completion + content: + application/json: + schema: + $ref: '#/components/schemas/CreateChatCompletionResponse' + text/event-stream: + schema: + $ref: '#/components/schemas/CreateChatCompletionStreamResponse' + '400': + description: Chat completion request was malformed. + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestError' + '403': + description: Permissions do not allow creating a chat completion. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + x-fern-sdk-group-name: llm + x-fern-sdk-method-name: chatCompletion +components: + schemas: + CreateCorpusRequest: + description: Request object for creating a new corpus in the Vectara platform. + type: object + properties: + key: + $ref: '#/components/schemas/CorpusKey' + name: + description: The name for the corpus. This value defaults to the key. + type: string + example: My corpus + description: + description: Description of the corpus. + type: string + example: Documents with important information for my prompt. + save_history: + description: Indicates whether to save corpus queries to query history by + default. + type: boolean + default: false + queries_are_answers: + description: Queries made to this corpus are considered answers, and not + questions. + type: boolean + default: false + documents_are_questions: + description: Documents inside this corpus are considered questions, and + not answers. + type: boolean + default: false + encoder_id: + description: '*Deprecated*: Use `encoder_name` instead.' + type: string + pattern: enc_[0-9]+$ + example: enc_1 + deprecated: true + encoder_name: + description: The encoder used by the corpus, `boomerang-2023-q3`. + type: string + example: boomerang-2023-q3 + filter_attributes: + description: The new filter attributes of the corpus. If unset then the + corpus will not have filter attributes. + type: array + default: [] + items: + $ref: '#/components/schemas/FilterAttribute' + custom_dimensions: + description: A custom dimension is an additional numerical field attached + to a document part. You can then multiply this numerical field with a + query time custom dimension of the same name. This allows boosting (or + burying) document parts for arbitrary reasons. This feature is only enabled + for Pro and Enterprise customers. + type: array + default: [] + items: + $ref: '#/components/schemas/CorpusCustomDimension' + required: + - key + UpdateCorpusRequest: + type: object + description: Corpus properties that are modifiable after creation. + properties: + enabled: + description: Set whether or not the corpus is enabled. If unset then the + corpus will remain in the same state. + type: boolean + example: false + name: + description: The name for the corpus. If unset or null, then the corpus + will remain in the same state. + type: string + example: new-name + description: + description: Description of the corpus. If unset or null, then the corpus + will remain in the same state. + type: string + example: New description of the corpus. + save_history: + description: Indicates whether to save corpus queries to query history by + default. + type: boolean + ReplaceFilterAttributesRequest: + description: Request to replace all filter attributes for a corpus with a new + set of attributes. + type: object + properties: + filter_attributes: + description: The new filter attributes. + type: array + items: + $ref: '#/components/schemas/FilterAttribute' + required: + - filter_attributes + ReplaceFilterAttributesResponse: + description: Response containing the job ID for the filter attributes replacement + operation. + type: object + properties: + job_id: + description: Job that was created in order to replace filter attributes. + type: string + pattern: job_.+$ + required: + - job_id + CorpusKey: + description: A user-provided key for a corpus. + type: string + example: my-corpus + pattern: '[a-zA-Z0-9_\=\-]+$' + maxLength: 50 + Corpus: + description: A corpus is a collection of documents and associated configuration + for indexing, searching, and generating responses through RAG. + type: object + properties: + id: + description: Vectara ID of the corpus. + type: string + pattern: crp_[0-9]+$ + key: + $ref: '#/components/schemas/CorpusKey' + name: + description: Name for the corpus. This value defaults to the key. + type: string + description: + description: Corpus description. + type: string + enabled: + description: Specifies whether the corpus is enabled or not. + type: boolean + chat_history_corpus: + description: Indicates that this corpus does not store documents and stores + chats instead. + type: boolean + queries_are_answers: + description: Queries made to this corpus are considered answers, and not + questions. This swaps the semantics of the encoder used at query time. + type: boolean + default: false + documents_are_questions: + description: Documents inside this corpus are considered questions, and + not answers. This swaps the semantics of the encoder used at indexing. + type: boolean + default: false + encoder_id: + description: 'The encoder used by the corpus. *Deprecated*: Use `encoder_name` + instead' + type: string + pattern: enc_[0-9]+$ + deprecated: true + encoder_name: + description: The encoder used by the corpus, `boomerang-2023-q3`. + type: string + example: boomerang-2023-q3 + save_history: + description: Indicates whether to save corpus queries to query history by + default. + type: boolean + filter_attributes: + description: The new filter attributes of the corpus. + type: array + items: + $ref: '#/components/schemas/FilterAttribute' + custom_dimensions: + description: The custom dimensions of all document parts inside the corpus. + type: array + items: + $ref: '#/components/schemas/CorpusCustomDimension' + limits: + type: object + title: CorpusLimits + properties: + used_docs: + description: The number of documents contained in the corpus. + type: integer + format: int64 + used_parts: + description: The number of document parts contained in the corpus. + type: integer + format: int64 + used_bytes: + description: 'NOTE: This field is currently not populated by the system. + The number of bytes contained in the corpus. This includes the document + metadata, document part metadata, and document contents.' + type: integer + format: int64 + used_characters: + description: The number of characters contained in the corpus. This + includes the document metadata, document part metadata, and document + contents. + type: integer + format: int64 + max_bytes: + description: 'NOTE: This field is currently not populated by the system. + The maximum number of bytes the corpus can be.' + type: integer + format: int64 + max_metadata_bytes: + description: The maximum size that metadata can be on documents. + type: integer + format: int64 + index_rate: + description: 'NOTE: This field is currently not populated by the system. + The maximum per-second addition of new documents to corpus.' + type: integer + format: int64 + created_at: + description: Indicates when the corpus was created. + type: string + format: date-time + CorpusCustomDimension: + type: object + description: Custom dimensions attached to all document parts in a corpus. Allows + arbitrary modification of the score for many purposes. + properties: + name: + description: The name of the custom dimension. + type: string + example: importance + description: + description: Description of the custom dimension. + type: string + example: Product importance. + indexing_default: + description: Default value of a custom dimension on a document part if the + custom dimension value is not specified when the document part is indexed. + A value of 0 means that custom dimension is not considered. + type: number + format: double + example: 0 + default: 0 + querying_default: + description: Default value of a custom dimension for a query if the value + of the custom dimension is not specified when querying the corpus. A value + of 0 means that custom dimension is not considered. + type: number + format: double + example: 0 + default: 0 + required: + - name + FilterAttribute: + description: Defines a filter attribute that can be used to filter search results + based on document metadata for precise retrieval. + type: object + properties: + name: + description: The JSON path of the filter attribute in a document or document + part metadata. + type: string + example: Title + level: + description: Indicates whether this is a document or document part metadata + filter. + type: string + enum: + - document + - part + example: document + description: + description: Description of the filter. May be omitted. + type: string + example: The title of the document. + indexed: + description: Indicates whether an index should be created for the filter. + Creating an index will improve query latency when using the filter. + type: boolean + default: true + type: + description: The value type of the filter. + type: string + enum: + - integer + - real_number + - text + - boolean + - list[integer] + - list[real_number] + - list[text] + example: text + required: + - name + - level + - type + ListCorporaResponse: + description: Response containing a list of corpora within a customer account. + type: object + properties: + corpora: + type: array + items: + $ref: '#/components/schemas/Corpus' + metadata: + $ref: '#/components/schemas/ListMetadata' + SearchParameters: + type: object + description: Search parameters to retrieve knowledge for the query. + properties: + offset: + description: Specifies how many results into the result to skip. This is + useful for pagination. + type: integer + format: int32 + default: 0 + minimum: 0 + limit: + description: The maximum number of results returned. + type: integer + format: int32 + minimum: 1 + default: 10 + context_configuration: + $ref: '#/components/schemas/ContextConfiguration' + reranker: + $ref: '#/components/schemas/SearchReranker' + ContextConfiguration: + type: object + description: Configuration on the presentation of each document part in the + result set. + properties: + characters_before: + description: 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. + type: integer + format: int32 + default: 0 + minimum: 0 + example: 30 + characters_after: + description: 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. + type: integer + format: int32 + default: 0 + minimum: 0 + example: 30 + sentences_before: + description: 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. + type: integer + format: int32 + default: 0 + minimum: 0 + example: 3 + sentences_after: + description: 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. + type: integer + format: int32 + default: 0 + minimum: 0 + example: 3 + start_tag: + description: 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. + type: string + example: + end_tag: + description: 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. + type: string + example: + GenerationParameters: + description: The parameters to control generation. + type: object + properties: + generation_preset_name: + description: '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_parameter`s 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.' + type: string + minLength: 1 + example: vectara-summary-ext-v1.2.0 + prompt_name: + description: Use `generation_preset_name` instead of `prompt_name`. + type: string + minLength: 1 + example: vectara-summary-ext-v1.2.0 + deprecated: true + max_used_search_results: + description: The maximum number of search results to be available to the + prompt. + type: integer + format: int32 + minimum: 0 + default: 5 + prompt_template: + description: 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](https://docs.vectara.com/docs/prompts/vectara-prompt-engine). + type: string + example: "[\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: + description: This property is deprecated in favor of clearer naming. Use + `prompt_template`. This property will be ignored if `prompt_template` + is set. + type: string + example: "[\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" + deprecated: true + max_response_characters: + description: '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.' + type: integer + format: int32 + example: 300 + minimum: 0 + response_language: + $ref: '#/components/schemas/Language' + model_parameters: + title: ModelParameters + description: '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.' + type: object + properties: + llm_name: + description: The model (e.g., `gpt-4`) to use for summarization. If + specified, it will override the model behind `generation_preset_name`. + type: string + example: gpt4 + max_tokens: + description: The maximum number of tokens to be returned by the model. + type: integer + format: int32 + minimum: 1 + temperature: + description: The sampling temperature to use. Higher values make the + output more random, while lower values make it more focused and deterministic. + type: number + format: float + frequency_penalty: + description: 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. + type: number + format: float + presence_penalty: + description: 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. + type: number + format: float + citations: + $ref: '#/components/schemas/CitationParameters' + enable_factual_consistency_score: + description: Enable returning the factual consistency score with query results. + type: boolean + default: true + CitationParameters: + description: Style the generator should use when making citations. + type: object + properties: + style: + description: '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 `text_pattern`. * `markdown` - Formatted + as `[text_pattern](url_pattern)`.' + type: string + enum: + - none + - numeric + - html + - markdown + url_pattern: + description: 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. + type: string + example: https://vectara.com/documents/{doc.id} + text_pattern: + description: 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]()` 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]()` when the document's metadata + includes `{"title":"Title"}`. + type: string + example: '{doc.title}' + QueryRequest: + description: Query one or more corpora. + type: object + properties: + query: + description: The search query string, which is the question the user is + asking. + type: string + example: Am I allowed to bring pets to work? + search: + $ref: '#/components/schemas/SearchCorporaParameters' + generation: + $ref: '#/components/schemas/GenerationParameters' + stream_response: + description: Indicates whether the response should be streamed or not. + type: boolean + default: false + save_history: + description: Indicates whether to save the query to query history. + type: boolean + intelligent_query_rewriting: + description: '[Tech Preview] 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. Read [here](https://docs.vectara.com/docs/search-and-retrieval/intelligent-query-rewriting) + for more details.' + type: boolean + default: false + required: + - query + - search + SearchCorporaParameters: + description: The parameters to search one or more corpora. + allOf: + - type: object + properties: + corpora: + description: The corpora that you want to search. + type: array + items: + $ref: '#/components/schemas/KeyedSearchCorpus' + minItems: 1 + - $ref: '#/components/schemas/SearchParameters' + required: + - corpora + QueryCorpusRequest: + description: Request to search a specific corpus within a customer account and + optionally generate a response using RAG techniques. + type: object + properties: + query: + description: The search query string, which is the question the user is + asking. + type: string + search: + title: SearchCorpusParameters + description: The parameters to search one corpus. + allOf: + - $ref: '#/components/schemas/SearchCorpus' + - $ref: '#/components/schemas/SearchParameters' + generation: + $ref: '#/components/schemas/GenerationParameters' + stream_response: + description: Indicates whether the response should be streamed or not. + type: boolean + default: false + save_history: + description: Indicates whether to save the query to query history. + type: boolean + intelligent_query_rewriting: + description: '[Tech Preview] 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. Read [here](https://docs.vectara.com/docs/search-and-retrieval/intelligent-query-rewriting) + for more details.' + type: boolean + default: false + required: + - query + SearchCorpus: + description: Configuration for search parameters specific to a single corpus + within a customer account, including filters and semantics. + type: object + properties: + custom_dimensions: + $ref: '#/components/schemas/CustomDimensions' + metadata_filter: + description: 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](https://docs.vectara.com/docs/learn/metadata-search-filtering/filter-overview) + for more information. + type: string + example: doc.title = 'Charlotte''s Web' + lexical_interpolation: + description: 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. + type: number + format: float + minimum: 0 + maximum: 1 + example: 0.025 + semantics: + $ref: '#/components/schemas/SearchSemantics' + SearchSemantics: + description: Indicates whether to consider a query against this corpus as a + query or a response. + type: string + enum: + - default + - query + - response + default: default + KeyedSearchCorpus: + description: A corpus with its identifying key for use in search operations + within a customer account. + allOf: + - $ref: '#/components/schemas/SearchCorpus' + - type: object + properties: + corpus_key: + $ref: '#/components/schemas/CorpusKey' + query: + description: Query for a particular corpus that will override the overall + query if present. + type: string + required: + - corpus_key + SearchReranker: + type: object + description: 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"`. + discriminator: + propertyName: type + mapping: + customer_reranker: '#/components/schemas/CustomerSpecificReranker' + userfn: '#/components/schemas/UserFunctionReranker' + mmr: '#/components/schemas/MMRReranker' + chain: '#/components/schemas/ChainReranker' + none: '#/components/schemas/NoneReranker' + oneOf: + - $ref: '#/components/schemas/CustomerSpecificReranker' + - $ref: '#/components/schemas/UserFunctionReranker' + - $ref: '#/components/schemas/MMRReranker' + - $ref: '#/components/schemas/ChainReranker' + - $ref: '#/components/schemas/NoneReranker' + CustomerSpecificReranker: + description: Reranker that is specific to the customer. + type: object + properties: + type: + description: When the type is `customer_reranker`, you can specify the `reranker_name` + of a reranker. `reranker_id` is deprecated. The retrieval engine will + then rerank results using that reranker. + type: string + default: customer_reranker + reranker_id: + description: '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.' + type: string + pattern: rnk_(?!272725718)\d+ + example: rnk_272725719 + deprecated: true + reranker_name: + description: The name of the reranker. Do not specify the MMR reranker name + here. Instead, use the MMR reranker object type. + type: string + example: Rerank_Multilingual_v1 + limit: + type: integer + description: '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.' + format: int32 + minimum: 1 + cutoff: + type: number + description: '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.' + format: float + include_context: + type: boolean + default: true + description: If true, the reranker will use text with context (see "context_configuration") + for scoring. + x-vectaraParents: + - SearchReranker + UserFunctionReranker: + description: A reranker that uses user-defined functions to reorder search results. + type: object + properties: + type: + description: 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. + type: string + default: userfn + user_function: + description: The user defined function. + type: string + example: get('$.score') * get('$.document_metadata.boost') + limit: + type: integer + description: "Specifies the maximum number of results to be returned after\ + \ the reranking process. \nWhen a reranker is applied, it performs the\ + \ following steps:\n1. Reranks all input results according to its algorithm.\n\ + 2. Sorts the reranked results based on their new scores.\n3. Returns the\ + \ top N results, where N is the value specified by this limit.\n\nNote:\ + \ 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." + format: int32 + minimum: 1 + cutoff: + type: number + description: '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.' + format: float + x-vectaraParents: + - SearchReranker + MMRReranker: + description: A reranker that uses Maximal Marginal Relevance to balance relevance + and diversity in search results. + type: object + properties: + type: + description: When the type is `mmr`, you can specify the `diversity_bias`, + and the retrieval engine will use the MMR reranker. + type: string + default: mmr + diversity_bias: + description: The diversity bias. Higher values indicate more diversity. + type: number + format: float + example: 0.3 + limit: + type: integer + description: "Specifies the maximum number of results to be returned after\ + \ the reranking process. \nWhen a reranker is applied, it performs the\ + \ following steps:\n1. Reranks all input results according to its algorithm.\n\ + 2. Sorts the reranked results based on their new scores.\n3. Returns the\ + \ top N results, where N is the value specified by this limit.\n\nNote:\ + \ 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." + format: int32 + minimum: 1 + cutoff: + type: number + description: '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.' + format: float + x-vectaraParents: + - SearchReranker + ChainReranker: + description: A reranker that applies multiple rerankers in sequence to produce + the final search results. + type: object + properties: + type: + description: When the type is `chain`, you can then chain re-rankers together. + type: string + default: chain + rerankers: + type: array + description: Specify an array of rerankers to apply to search results consecutively. + items: + $ref: '#/components/schemas/SearchReranker' + maxItems: 50 + required: + - rerankers + x-vectaraParents: + - SearchReranker + NoneReranker: + description: A placeholder reranker that does not modify the original search + results ordering. + type: object + properties: + type: + description: When the type is `none`, no reranking will be done. + type: string + default: none + limit: + type: integer + description: '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.' + format: int32 + minimum: 1 + x-vectaraParents: + - SearchReranker + QueryFullResponse: + description: The full response to a RAG query when the result is not streamed. + type: object + properties: + summary: + description: The summary of the search results. + type: string + response_language: + $ref: '#/components/schemas/Language' + search_results: + description: The ranked search results. + type: array + items: + $ref: '#/components/schemas/IndividualSearchResult' + factual_consistency_score: + description: 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. + type: number + format: float + rendered_prompt: + description: The rendered prompt sent to the LLM. Useful when creating customer + `prompt_template` templates. + type: string + warnings: + description: Non-fatal warnings that occurred during request processing + type: array + items: + $ref: '#/components/schemas/QueryWarning' + rewritten_queries: + description: The rewritten queries for the corpora that were searched. Only + populated when `intelligent_query_rewriting` is enabled. + type: array + items: + $ref: '#/components/schemas/RewrittenQuery' + IndividualSearchResult: + description: An individual ranked search result from a query. + type: object + properties: + text: + description: The document part altered by the context configuration that + matches the query. + type: string + score: + description: The score of the individual result. + type: number + format: double + part_metadata: + description: The metadata for the document part. + type: object + additionalProperties: true + document_metadata: + description: The metadata for the document that contains the document part. + type: object + additionalProperties: true + document_id: + description: The ID of the document that contains the document part. + type: string + table: + description: The table that the document part is from. + $ref: '#/components/schemas/Table' + request_corpora_index: + description: 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. + type: integer + format: int32 + example: 0 + minimum: 0 + RewrittenQuery: + description: The rewritten query for a corpus that was searched. + type: object + properties: + corpus_key: + description: The corpus key that the query was made on. + type: string + filter_extraction: + $ref: '#/components/schemas/FilterExtraction' + RerankedSearchResult: + description: An individual reranked search result from a query. + type: object + properties: + text: + description: The document part altered by the context configuration that + matches the query. + type: string + score: + description: The score of the individual result. + type: number + format: double + original_score: + description: The original score of the individual result before reranking. + type: number + format: double + QueryStreamedResponse: + description: An individual event sent with Server-sent Events (SSE) when the + query request is streamed. + type: object + discriminator: + propertyName: type + mapping: + search_results: '#/components/schemas/StreamSearchResponse' + generation_chunk: '#/components/schemas/StreamGenerationChunk' + generation_end: '#/components/schemas/StreamGenerationEnd' + factual_consistency_score: '#/components/schemas/FactualConsistencyScore' + generation_info: '#/components/schemas/GenerationInfo' + error: '#/components/schemas/StreamError' + end: '#/components/schemas/StreamResponseEnd' + oneOf: + - $ref: '#/components/schemas/StreamSearchResponse' + - $ref: '#/components/schemas/StreamGenerationChunk' + - $ref: '#/components/schemas/StreamGenerationEnd' + - $ref: '#/components/schemas/StreamResponseEnd' + - $ref: '#/components/schemas/FactualConsistencyScore' + - $ref: '#/components/schemas/GenerationInfo' + - $ref: '#/components/schemas/StreamError' + StreamSearchResponse: + description: The search response results. + type: object + properties: + type: + description: When the streaming event has the search results, the type will + be `search_results`. + type: string + default: search_results + search_results: + description: The ranked search results. + type: array + items: + $ref: '#/components/schemas/IndividualSearchResult' + rewritten_queries: + description: The rewritten queries for the corpora that were searched. Only + populated when `intelligent_query_rewriting` is enabled. + type: array + items: + $ref: '#/components/schemas/RewrittenQuery' + x-vectaraParents: + - QueryStreamedResponse + - ChatStreamedResponse + StreamGenerationChunk: + description: The chunk response from the generation, which may be a partial + generation. + type: object + properties: + type: + description: When the streaming event contains the next chunk of generator + output, the type will be `generation_chunk`. + type: string + default: generation_chunk + generation_chunk: + description: Part of the message from the generator. All summary chunks + must be appended together in order to get the full summary. + type: string + x-vectaraParents: + - QueryStreamedResponse + - ChatStreamedResponse + - SummarizeDocumentStreamedResponse + FactualConsistencyScore: + description: Event containing the factual consistency score. + type: object + properties: + type: + description: When the streaming event contains the factual consistency score, + the type will be `factual_consistency_score`. + type: string + default: factual_consistency_score + factual_consistency_score: + description: The probability that the summary is factually consistent with + the results. + type: number + format: float + x-vectaraParents: + - QueryStreamedResponse + - ChatStreamedResponse + GenerationInfo: + description: Event containing information on how the generation was accomplished. + type: object + properties: + type: + description: When the streaming event contains the generation information + type will be `generation_info`. + type: string + default: generation_info + rendered_prompt: + description: The rendered prompt sent to the LLM. Useful when creating customer + `prompt_template` templates. + type: string + rephrased_query: + description: View the actual query made to backend that was rephrased by + the LLM from the input query. + type: string + x-vectaraParents: + - QueryStreamedResponse + - ChatStreamedResponse + - SummarizeDocumentStreamedResponse + StreamError: + description: Event signaling there was an error with the request. + properties: + type: + description: If the stream errors, an event with type `error` will be sent. + type: string + default: error + messages: + description: The error messages. + type: array + items: + type: string + x-vectaraParents: + - QueryStreamedResponse + - ChatStreamedResponse + - SummarizeDocumentStreamedResponse + StreamGenerationEnd: + description: The end of generation. There may still be more information such + as the factual consistency score, but generation has stopped. + type: object + properties: + type: + description: Then end of generation will be denoted with an object with + the type `generation_end`. + type: string + default: generation_end + x-vectaraParents: + - QueryStreamedResponse + - ChatStreamedResponse + - SummarizeDocumentStreamedResponse + StreamResponseEnd: + description: The end of a query response stream. + type: object + properties: + type: + description: Then end of stream will be denoted with an object with the + type `end`. + type: string + default: end + x-vectaraParents: + - QueryStreamedResponse + - ChatStreamedResponse + - SummarizeDocumentStreamedResponse + UploadFileRequest: + description: Request to upload and index a file into a corpus within a customer + account. + type: object + properties: + metadata: + description: Arbitrary object that will be attached as document metadata + to the extracted document. + type: object + additionalProperties: true + chunking_strategy: + $ref: '#/components/schemas/ChunkingStrategy' + table_extraction_config: + $ref: '#/components/schemas/TableExtractionConfig' + filename: + description: Optional multipart section to override the filename. + type: string + file: + description: Binary file contents. The file name of the file will be used + as the document ID. + type: string + format: binary + required: + - file + TableExtractionConfig: + type: object + description: Configuration for table extraction from the document. This is optional + and if not provided, the platform does not extract tables from PDF files. + properties: + extract_tables: + type: boolean + description: If set to true, the platform will attempt to extract tables + from the document. The tables will be indexed as separate document parts. + extractor: + $ref: '#/components/schemas/TableExtractorSpec' + generation: + $ref: '#/components/schemas/TableGenerationSpec' + required: + - extract_tables + ChunkingStrategy: + type: object + description: Choose how to split documents into chunks during indexing. This + is optional - if you do not set a chunking strategy, the platform uses the + default strategy which creates one chunk (docpart) per sentence. + discriminator: + propertyName: type + mapping: + max_chars_chunking_strategy: '#/components/schemas/MaxCharsChunkingStrategy' + sentence_chunking_strategy: '#/components/schemas/SentenceChunkingStrategy' + oneOf: + - $ref: '#/components/schemas/MaxCharsChunkingStrategy' + - $ref: '#/components/schemas/SentenceChunkingStrategy' + MaxCharsChunkingStrategy: + type: object + description: Sets a chunking strategy that limits the number of maximum characters + per chunk. The chunks do not cross section boundaries. + properties: + type: + description: When setting the type to max_chars_chunking_strategy, you can + control the size of chunks (docparts). + type: string + default: max_chars_chunking_strategy + max_chars_per_chunk: + description: 'Specifies the maximum number of characters per chunk. The + platform adds sentences to a chunk until the total number of characters + exceeds the limit. If a single sentence exceeds the limit, it splits the + sentence across chunks. Note: This is the only case where the chunk may + not contain a complete sentence.' + type: integer + format: int32 + minimum: 100 + required: + - max_chars_per_chunk + x-vectaraParents: + - ChunkingStrategy + SentenceChunkingStrategy: + type: object + description: Sets a chunking strategy that creates one chunk per sentence. This + is the default strategy used when no chunking strategy is specified. + properties: + type: + description: When setting the type to sentence_chunking_strategy, the platform + will create one chunk per sentence. + type: string + default: sentence_chunking_strategy + x-vectaraParents: + - ChunkingStrategy + CreateDocumentRequest: + description: Creating a document using this endpoint can take multiple forms + depending on how much control of the resulting document parts you desire. + You can create a document with natural structure, and Vectara will use its + proprietary strategy to create document parts. Otherwise, you can create a + document with all the document parts explicitly specified. A document part + is the search result item in search and Retrieval Augmented Generation endpoints. + type: object + discriminator: + propertyName: type + mapping: + core: '#/components/schemas/CoreDocument' + structured: '#/components/schemas/StructuredDocument' + oneOf: + - $ref: '#/components/schemas/CoreDocument' + - $ref: '#/components/schemas/StructuredDocument' + required: + - type + UpdateDocumentRequest: + description: Schema for updating the document. For PUT requests, the request + body metadata replaces the existing metadata. For PATCH requests, the request + body metadata is merged with the existing metadata, adding or modifying only + the specified fields. + type: object + properties: + metadata: + description: The metadata for a document as an arbitrary object. Properties + of this object can be used by document level filter attributes. + type: object + additionalProperties: true + StructuredDocument: + description: A document with layout features. + type: object + properties: + id: + description: The document ID must be unique within the corpus. + type: string + type: + description: When the type of the indexed document is `structured` the rest + of the object is expected to follow this schema. It allows you to create + a document that follows normal document conventions. The Vectara platform + will then create document parts using its internal algorithm. + default: structured + type: string + title: + description: The title of the document. + type: string + description: + description: The description of the document. + type: string + metadata: + description: The metadata for a document as an arbitrary JSON object. Properties + of this object can be used by document level filter attributes. + type: object + additionalProperties: true + custom_dimensions: + $ref: '#/components/schemas/CustomDimensions' + sections: + description: The subsection of the document. + type: array + minItems: 1 + items: + $ref: '#/components/schemas/StructuredDocumentSection' + chunking_strategy: + $ref: '#/components/schemas/ChunkingStrategy' + required: + - id + - type + - sections + x-vectaraParents: + - CreateDocumentRequest + StructuredDocumentSection: + description: A logical section within a structured document. + type: object + properties: + id: + description: The section ID. This gets converted to a metadata field automatically. + type: integer + format: int32 + title: + description: The section title. + type: string + text: + description: The text of the section. + type: string + metadata: + description: Arbitrary object that becomes document part level metadata + on any document part created by this section. Properties of this object + can be used by document part level filters if defined as a corpus filter + attribute. + type: object + properties: {} + additionalProperties: true + tables: + description: The tables that this section contains. + type: array + items: + $ref: '#/components/schemas/Table' + sections: + description: The sections that this section contains. + type: array + items: + $ref: '#/components/schemas/StructuredDocumentSection' + required: + - text + CoreDocument: + description: The document structure that most closely corresponds to Vectara's + internal document data model. + type: object + properties: + id: + description: The document ID must be unique within the corpus. + type: string + example: my-doc-id + type: + description: When the type of the indexed document is `core` the rest of + the object is expected to follow this schema. This schema allows precise + specification of document chunks that get directly translated to retrieve + search results. + default: core + type: string + metadata: + description: Arbitrary object of document level metadata. Properties of + this object can be used by document filters if defined as a corpus filter + attribute. + type: object + properties: {} + additionalProperties: true + example: + title: A Nice Document + lang: eng + tables: + description: The tables that this document contains. + type: array + items: + $ref: '#/components/schemas/Table' + document_parts: + description: Parts of the document that make up the document. + type: array + minItems: 1 + items: + $ref: '#/components/schemas/CoreDocumentPart' + required: + - id + - type + - document_parts + x-vectaraParents: + - CreateDocumentRequest + DocumentPart: + description: A part of a document. This section gets converted into an embedding + and directly maps to a search result. Usually a sentence. + type: object + properties: + text: + description: The text of the document part. + type: string + example: I'm a nice document part. + metadata: + description: The metadata for a document part. These may be used in metadata + filters at query time if filter attributes are configured on the corpus. + type: object + additionalProperties: true + example: + nice_rank: 9000 + context: + description: The context text for the document part. + type: string + custom_dimensions: + $ref: '#/components/schemas/CustomDimensions' + required: + - text + CoreDocumentPart: + description: A part of a document. This section gets converted into an embedding + and directly maps to a search result. Usually this is a sentence. + type: object + properties: + text: + description: The text of the document part. + type: string + example: I'm a nice document part. + metadata: + description: The metadata for a document part. These may be used in metadata + filters at query time if filter attributes are configured on the corpus. + type: object + additionalProperties: true + example: + nice_rank: 9000 + table_id: + description: The ID of the table that this document part belongs to. + type: string + context: + description: The context text for the document part. + type: string + custom_dimensions: + $ref: '#/components/schemas/CustomDimensions' + required: + - text + CustomDimensions: + description: The custom dimensions as additional weights. + type: object + additionalProperties: + type: number + format: double + nullable: false + Document: + description: A document stored in a corpus, containing metadata and indexed + content. + type: object + properties: + id: + description: The document ID. + type: string + example: my-doc-id + metadata: + description: The document metadata. + type: object + additionalProperties: true + tables: + description: The tables that this document contains. Tables are not available + when table extraction is not enabled. + type: array + items: + $ref: '#/components/schemas/Table' + parts: + description: Parts of the document that make up the document. However, parts + are not available when retrieving a list of documents or when creating + a document. This property is only available when retrieving a document + by ID. + type: array + items: + $ref: '#/components/schemas/DocumentPart' + storage_usage: + $ref: '#/components/schemas/DocumentStorageUsage' + extraction_usage: + $ref: '#/components/schemas/ExtractionUsage' + Cell: + description: A cell in a table. + type: object + properties: + text_value: + description: A text value. + type: string + int_value: + description: A signed 64-bit integer value. + type: integer + format: int64 + float_value: + description: A floating-point value with double precision. + type: number + format: double + bool_value: + description: A boolean value. + type: boolean + colspan: + description: The number of columns the cell spans. This field is optional; + if not specified, default is 1. Must be greater than 0. + type: integer + format: int32 + rowspan: + description: The number of rows the cell spans. This field is optional; + if not specified, default is 1. Must be greater than 0. + type: integer + format: int32 + Row: + description: A row in a table. + type: array + items: + $ref: '#/components/schemas/Cell' + Header: + description: The header of a table. + type: array + items: + $ref: '#/components/schemas/Cell' + Data: + description: The data of a table. + type: object + properties: + headers: + description: The headers of the table. + type: array + items: + $ref: '#/components/schemas/Header' + rows: + description: The rows in the data. + type: array + items: + $ref: '#/components/schemas/Row' + Table: + description: A table in a document. + type: object + properties: + id: + description: The unique ID of the table within the document. + type: string + example: table_1 + title: + description: The title of the table. + type: string + data: + description: The data of the table. + $ref: '#/components/schemas/Data' + description: + description: The description of the table. + type: string + EvaluateFactualConsistencyRequest: + description: Request to evaluate the factual consistency of a generated text + against source documents. + type: object + required: + - generated_text + - source_texts + properties: + model_parameters: + description: The model parameters for the evaluation. + type: object + properties: + model_name: + description: The name of the model to use for evaluation. + type: string + example: hhem_v2.2 + default: hhem_v2.2 + generated_text: + type: string + description: The generated text (e.g., summary or answer) to evaluate for + factual consistency. + source_texts: + type: array + description: The source documents or text snippets against which to evaluate + factual consistency. + items: + type: string + EvaluateFactualConsistencyResponse: + description: Results of the factual consistency evaluation. + type: object + required: + - score + properties: + score: + type: number + format: double + description: A prediction score (0.0-1.0) from HHEM, monotonically indicates + the likelihood of hallucinations. + minimum: 0.0 + maximum: 1.0 + DocumentStorageUsage: + type: object + description: How much storage the document used. This information is currently + not returned when retrieving the document, and only returned when indexing + a document. + properties: + bytes_used: + description: Number of bytes used by document counting towards maximum corpus + size, and towards any billing plans. + type: integer + format: int64 + minimum: 0 + metadata_bytes_used: + description: Number of metadata bytes used by a document. + type: integer + format: int64 + minimum: 0 + ExtractionUsage: + type: object + description: How much extraction quota the document used. This information is + currently not returned when retrieving the document, and only returned when + indexing a document. + properties: + table_extraction_used: + description: The number of pages from the document that consumed the extraction + quota. + type: integer + format: int64 + minimum: 0 + ListDocumentsResponse: + description: Response containing a list of documents stored in a corpus. + type: object + properties: + documents: + description: List of documents. + type: array + items: + $ref: '#/components/schemas/Document' + metadata: + $ref: '#/components/schemas/ListMetadata' + LLM: + description: A LLM can be used to enhance query results with a response, and + be used as the responder during a chat. + type: object + properties: + id: + description: The ID of the LLM. + type: string + pattern: llm_.* + name: + description: Name of the LLM. + type: string + description: + description: The description of the LLM. + type: string + enabled: + description: Indicates whether the LLM is enabled. + type: boolean + default: + description: If this is the default LLM, it is used in queries when the + generator is not specified. + type: boolean + prompts: + description: List of prompts that the model can use. This is deprecated; + see `/v2/generation_presets` instead. + items: + $ref: '#/components/schemas/Prompt' + deprecated: true + Prompt: + description: A prompt that can be used with a LLM. A prompt is the template + that is used to render the text sent to the LLM. It also contains various + default model settings such as temperature. + type: object + properties: + id: + description: The ID of the prompt. + type: string + pattern: pmt_.* + name: + description: Name of the prompt. This is used as the `prompt_name` in a + query. + type: string + description: + description: The description of the prompt. + type: string + enabled: + description: Indicates whether the prompt is enabled. + type: boolean + default: + description: Indicates if this prompt is the default prompt used with the + LLM. + type: boolean + CreateLLMRequest: + description: Request to create a Large Language Model connection for generative + capabilities. + type: object + discriminator: + propertyName: type + mapping: + openai-compatible: '#/components/schemas/CreateOpenAILLMRequest' + oneOf: + - $ref: '#/components/schemas/CreateOpenAILLMRequest' + required: + - type + CreateOpenAILLMRequest: + description: Request to create an OpenAI-compatible Large Language Model connection. + type: object + properties: + type: + description: Must be "openai-compatible" for OpenAI and OpenAI-compatible + APIs (like Anthropic Claude, Azure OpenAI, etc) + type: string + default: openai-compatible + name: + description: Name to reference the LLM. This will be used in other endpoints + (like query) when using this LLM. If this name conflicts with a global + LLM (a LLM that is precofnigured with the Vectara platform), then it will + override that LLM for all usages. + type: string + description: + description: Description of the LLM. + type: string + default: '' + nullable: false + model: + description: The model name to use with the API (e.g. gpt-4, claude-2, etc). + This is used in the API request to the remote LLM provider. + type: string + uri: + description: The URI endpoint for the API (can be OpenAI or any compatible + API endpoint) + type: string + format: uri + auth: + $ref: '#/components/schemas/RemoteAuth' + headers: + description: Additional HTTP headers to include with requests to the LLM + API. + type: object + additionalProperties: + type: string + test_model_parameters: + description: Any additional parameters that are required for the LLM during + the test call. + type: object + additionalProperties: true + required: + - type + - name + - model + - uri + x-vectaraParents: + - CreateLLMRequest + ListLLMsResponse: + description: Response containing a list of Large Language Models available for + generative AI capabilities. + type: object + properties: + llms: + description: List of LLMs. + type: array + items: + $ref: '#/components/schemas/LLM' + metadata: + $ref: '#/components/schemas/ListMetadata' + GenerationPreset: + description: Bundle of default values used when calling generation. All values + except model name can be overridden at generation time. + type: object + properties: + name: + description: Name of the generation preset to be used with configuring generation. + type: string + description: + description: Description of the generation preset. + type: string + llm_name: + description: Name of the model that these presets are used with. The list + of available names can be fetched by the `GET /v2/llms` endpoint. + type: string + prompt_template: + description: Preset template used to render the prompt sent to generation. + type: string + max_used_search_results: + description: Preset maximum number of search results that will be available + to the prompt. + type: integer + format: int32 + minimum: 1 + max_tokens: + description: Preset maximum number of tokens to be returned by the generation. + type: integer + format: int32 + minimum: 1 + temperature: + description: The sampling temperature to use. Higher values make the output + more random, while lower values make it more focused and deterministic. + type: number + format: float + frequency_penalty: + description: Higher values penalize new tokens based on their existing frequency + in the generation so far, decreasing the model's likelihood to repeat + the same line verbatim. + type: number + format: float + presence_penalty: + description: Higher values penalize new tokens based on whether they appear + in the generation so far, increasing the model's likelihood to talk about + new topics. + type: number + format: float + enabled: + description: Indicates whether the prompt is enabled. + type: boolean + default: + description: Indicates if this prompt is the default prompt used with the + LLM. + type: boolean + ListGenerationPresetsResponse: + description: Response containing a list of generation presets for configuring + RAG behavior. + type: object + properties: + generation_presets: + description: List of generation presets. + type: array + items: + $ref: '#/components/schemas/GenerationPreset' + metadata: + $ref: '#/components/schemas/ListMetadata' + ChatRequest: + description: Request to start or continue a chat conversation with a large language + model. + type: object + properties: + query: + description: The chat message or question. + type: string + example: How can I use the Vectara platform? + search: + $ref: '#/components/schemas/SearchCorporaParameters' + generation: + $ref: '#/components/schemas/GenerationParameters' + chat: + $ref: '#/components/schemas/ChatParameters' + save_history: + description: Indicates whether to save the chat in both the chat and query + history. This overrides `chat.store`. + type: boolean + default: true + intelligent_query_rewriting: + description: '[Tech Preview] 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. Read [here](https://docs.vectara.com/docs/search-and-retrieval/intelligent-query-rewriting) + for more details.' + type: boolean + default: false + stream_response: + description: Indicates whether the response should be streamed or not. + type: boolean + default: false + required: + - query + - search + ChatParameters: + type: object + description: Parameters to control chat behavior. + properties: + store: + description: Indicates whether to store chat messages and response messages. + type: boolean + default: true + ChatFullResponse: + description: Full response to a chat question when the result is not streamed. + type: object + properties: + chat_id: + description: If the chat response was stored, the ID of the chat. + type: string + turn_id: + description: If the chat response was stored, the ID of the turn. + type: string + answer: + description: The message from the chat model for the chat message. + type: string + response_language: + description: The language that the answer is expected to be. + $ref: '#/components/schemas/Language' + search_results: + description: The ranked search results that the chat model used. + type: array + items: + $ref: '#/components/schemas/IndividualSearchResult' + factual_consistency_score: + description: 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. + type: number + format: float + rendered_prompt: + description: The rendered prompt sent to the LLM. Useful when creating customer + `prompt_template` templates. + type: string + warnings: + description: Non-fatal warnings that occurred during request processing + type: array + items: + $ref: '#/components/schemas/QueryWarning' + rephrased_query: + description: View the actual query made to backend that was rephrased by + the LLM from the input query. + type: string + rewritten_queries: + description: The rewritten queries for the corpora that were searched. Only + populated when intelligent_query_rewriting is enabled. + type: array + items: + $ref: '#/components/schemas/RewrittenQuery' + ChatStreamedResponse: + description: An individual event when the response is streamed. + type: object + discriminator: + propertyName: type + mapping: + search_results: '#/components/schemas/StreamSearchResponse' + chat_info: '#/components/schemas/ChatInfoResponse' + generation_chunk: '#/components/schemas/StreamGenerationChunk' + generation_end: '#/components/schemas/StreamGenerationEnd' + generation_info: '#/components/schemas/GenerationInfo' + factual_consistency_score: '#/components/schemas/FactualConsistencyScore' + end: '#/components/schemas/StreamResponseEnd' + error: '#/components/schemas/StreamError' + oneOf: + - $ref: '#/components/schemas/StreamSearchResponse' + - $ref: '#/components/schemas/ChatInfoResponse' + - $ref: '#/components/schemas/StreamGenerationChunk' + - $ref: '#/components/schemas/StreamGenerationEnd' + - $ref: '#/components/schemas/FactualConsistencyScore' + - $ref: '#/components/schemas/StreamResponseEnd' + - $ref: '#/components/schemas/GenerationInfo' + - $ref: '#/components/schemas/StreamError' + ChatInfoResponse: + description: Information about the chat. + type: object + properties: + type: + description: This will be `chat_info` when the stream event contains information + about how the chat is stored. + type: string + default: chat_info + chat_id: + description: ID of the chat. + type: string + pattern: cht_.+$ + turn_id: + description: ID of the turn. + type: string + pattern: trn_.+$ + x-vectaraParents: + - ChatStreamedResponse + Chat: + description: A chat conversation with associated metadata and settings. + type: object + properties: + id: + description: ID of the chat. + type: string + pattern: cht_.+$ + first_query: + description: The first query of the chat. + type: string + first_answer: + description: The first answer of the chat. + type: string + enabled: + description: Indicates whether this chat is enabled and can have further + turns. + type: boolean + example: true + created_at: + description: Specifies when this chat was created. + type: string + format: date-time + ListChatsResponse: + description: Response containing a list of chat conversations. + type: object + properties: + chats: + description: List of chats. + type: array + items: + $ref: '#/components/schemas/Chat' + metadata: + $ref: '#/components/schemas/ListMetadata' + Turn: + description: A single message exchange in a chat conversation, representing + one user input and the corresponding response. + type: object + properties: + id: + description: The ID of the turn. + type: string + pattern: trn_.+$ + chat_id: + description: The ID of the chat the turn resides in. + type: string + pattern: cht_.+$ + query: + description: The query made to produce this turn. + type: string + example: How do you turn this widget? + answer: + description: The response to the query. + type: string + example: The widget turns counter clockwise. + enabled: + description: Indicates whether the turn is enabled and shown in future turns + of the chat. + type: boolean + example: true + created_at: + description: Specifies when the turn was created. + type: string + format: date-time + ListChatTurnsResponse: + description: Response containing a list of turns (message exchanges) within + a chat conversation. + type: object + properties: + turns: + description: List of turns. + type: array + items: + $ref: '#/components/schemas/Turn' + UpdateTurnRequest: + description: Request to update a specific turn (message exchange) within a chat + conversation. + type: object + properties: + enabled: + description: Indicates whether to disable a turn. It will disable this turn + and all subsequent turns. Enabling a turn is not implemented. + type: boolean + example: false + ListEncodersResponse: + description: Response containing a list of available encoders for converting + text to vector embeddings. + type: object + properties: + encoders: + type: array + items: + $ref: '#/components/schemas/Encoder' + metadata: + $ref: '#/components/schemas/ListMetadata' + CreateApiKeyRequest: + description: Request to create a new API key for authenticating with the platform. + type: object + properties: + name: + description: The human-readable name of the API key. + type: string + api_key_role: + $ref: '#/components/schemas/ApiKeyRole' + corpus_keys: + description: Corpora this API key has roles on if it is not a Personal API + key. This property should be null or missing if this `api_key_role` is + `personal`. + type: array + items: + $ref: '#/components/schemas/CorpusKey' + required: + - name + - api_key_role + ApiKey: + description: An API key used to authenticate and authorize requests to the Vectara + platform. + type: object + properties: + id: + description: The ID of the API key. + type: string + pattern: aky_.* + name: + description: The human-readable name of the API key. + type: string + secret_key: + description: The key used in API requests. The key should be kept secure. + type: string + enabled: + description: If this API key is enabled. + type: boolean + api_key_role: + $ref: '#/components/schemas/ApiKeyRole' + api_policy: + $ref: '#/components/schemas/ApiPolicy' + ApiKeyRole: + description: 'Role of the API key. A serving API key can only perform query + type requests on its corpora. A serving and indexing key can perform both + indexing and query type requests on its corpora. + + A personal API key has all the same permissions as the creator of the API + key.' + type: string + enum: + - serving + - serving_and_indexing + - personal + UpdateApiKeyRequest: + description: Request to update an existing API key's properties or permissions. + type: object + properties: + enabled: + description: Indicates whether to disable or enable an API key. + type: boolean + ListApiKeysResponse: + description: Response containing a list of API keys for the authenticated customer. + type: object + properties: + api_keys: + description: List of API keys. + type: array + items: + $ref: '#/components/schemas/ApiKey' + metadata: + $ref: '#/components/schemas/ListMetadata' + CreateAppClientRequest: + description: Request to create a new OAuth application client for the platform. + type: object + discriminator: + propertyName: type + mapping: + client_credentials: '#/components/schemas/CreateClientCredentialsRequest' + oneOf: + - $ref: '#/components/schemas/CreateClientCredentialsRequest' + required: + - type + CreateClientCredentialsRequest: + description: Create an App Client which allows you to call Vectara APIs using + OAuth 2.0 client credentials. + type: object + properties: + name: + description: Name of the client credentials. + type: string + description: + description: Description of the client credentials. + type: string + type: + description: This will always be the value `client_credentials`. + type: string + default: client_credentials + api_roles: + description: API roles that the client credentials will have. + type: array + items: + $ref: '#/components/schemas/ApiRole' + required: + - name + - type + x-vectaraParents: + - CreateAppClientRequest + AppClient: + description: An OAuth application client configuration used for authentication. + type: object + properties: + id: + description: The Vectara App Client ID. This ID is not used during an OAuth + flow. However, the ID used within the Vectara API. + type: string + pattern: app_.+$ + name: + description: The human-readable name of the App Client. + type: string + description: + description: Description of the App Client. + type: string + client_id: + description: The client ID used with the OAuth flow. + type: string + client_secret: + description: The client secret used in API requests. The secret should + be kept secure. + type: string + api_roles: + description: The API roles attached to the App Client. + type: array + items: + $ref: '#/components/schemas/ApiRole' + api_policy: + $ref: '#/components/schemas/ApiPolicy' + UpdateAppClientRequest: + description: Request to update an existing OAuth application client's properties. + type: object + properties: + description: + description: The new App Client description. + type: string + api_roles: + description: The new roles attached to the App Client. These roles will + replace the current roles. + type: array + items: + $ref: '#/components/schemas/ApiRole' + ListAppClientsResponse: + description: Response containing a list of OAuth application clients. + type: object + properties: + app_clients: + description: List of App Clients. + type: array + items: + $ref: '#/components/schemas/AppClient' + metadata: + $ref: '#/components/schemas/ListMetadata' + CreateEncoderRequest: + type: object + description: Request to create a new encoder + discriminator: + propertyName: type + mapping: + openai-compatible: '#/components/schemas/CreateOpenAIEncoderRequest' + oneOf: + - $ref: '#/components/schemas/CreateOpenAIEncoderRequest' + required: + - type + CreateOpenAIEncoderRequest: + description: Configuration for an OpenAI-compatible encoder + type: object + properties: + type: + description: Must be "openai-compatible" for OpenAI and OpenAI-compatible + APIs + type: string + default: openai-compatible + name: + description: A unique name for the encoder + type: string + example: openai-text-encoder + description: + description: A description of what this encoder does + type: string + example: description + output_dimensions: + description: The number of dimensions in the output embedding vector. If + provided and the model supports truncation, the response will be truncated + to this number of dimensions. + type: integer + format: int32 + minimum: 1 + uri: + description: The URI endpoint for the embedding API (can be OpenAI or any + compatible embedding API endpoint) + type: string + format: uri + example: https://api.openai.com/v1/embeddings + model: + description: The model name to use for embeddings + type: string + example: text-embedding-ada-002 + auth: + $ref: '#/components/schemas/RemoteAuth' + required: + - name + - description + - uri + - model + x-vectaraParents: + - CreateEncoderRequest + Encoder: + description: A model that converts text into vector embeddings for semantic + search. + type: object + properties: + id: + description: The Encoder ID. + type: string + pattern: enc_[0-9]+$ + example: enc_1 + name: + description: The encoder name, `boomerang-2023-q3`. + type: string + example: openai-text-encoder + type: + description: The encoder type + example: openai-compatible + type: string + default: vectara + output_dimensions: + description: When this encoder is used to create an embedding, it shows + the count of dimensions for the output embedding. A high dimensionality + will consume more storage space, but it allows for an increase in the + quality of the embedding. + type: integer + format: int32 + example: 1536 + description: + description: The encoder description. + type: string + default: + description: Indicates whether the default encoder is used when creating + a corpus. + type: boolean + example: true + enabled: + description: Indicates whether the encoder is enabled. + type: boolean + example: true + Reranker: + description: A reranker can be used in query or chat endpoints to reorder the + search results. + type: object + properties: + id: + description: The ID of the reranker. + type: string + pattern: rnk_[0-9]+$ + name: + description: The name of the reranker. + type: string + description: + description: The description of the reranker. + type: string + enabled: + description: Whether the reranker is enabled. + type: boolean + ListRerankersResponse: + description: Response containing a list of available rerankers for improving + search result ordering. + type: object + properties: + rerankers: + description: An array of rerankers. + type: array + items: + $ref: '#/components/schemas/Reranker' + metadata: + $ref: '#/components/schemas/ListMetadata' + TableExtractorSpec: + description: Specification for which table extractor to use. If not specified, + the platform uses the default extractor. + type: object + properties: + name: + description: The name of the table extractor to use. + type: string + example: textract + required: + - name + TableGenerationSpec: + description: Specification for which generation to use during table summarization. + If not specified, the platform uses the default summarizer. All parameters + are optional and overrides the default values. + type: object + properties: + llm_name: + description: The name of the LLM to use. + type: string + example: gpt-4o + prompt_template: + type: string + description: The prompt template to use when generating the table summary. + 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](https://docs.vectara.com/docs/prompts/vectara-prompt-engine). + model_parameters: + type: object + description: Optional parameters for the specified model used when generating + the table summary. + example: + temperature: 0 + max_tokens: 512 + additionalProperties: true + TableExtractor: + description: A table extractor can be used to extract tabular data from documents + during indexing. + type: object + properties: + name: + description: The name of the table extractor. + type: string + example: textract + is_default: + description: Indicates whether it is the default extractor when not specified + during indexing. + type: boolean + description: + description: The description of the table extractor. + type: string + example: Uses the AWS Textract service to extract tables. + generation: + $ref: '#/components/schemas/TableGenerationSpec' + ListTableExtractorsResponse: + type: object + description: Response containing a list of available table extractors for document + processing + properties: + table_extractors: + description: An array of table extractors. + type: array + items: + $ref: '#/components/schemas/TableExtractor' + HallucinationCorrector: + description: A hallucination corrector that detects and corrects hallucinations + in generated text. + type: object + properties: + id: + description: The unique ID for the Hallucination Corrector (HC). + type: string + pattern: hcm_[0-9]+$ + example: hcm_123 + name: + description: The hallucination corrector name, typically including the base + name and variant. + type: string + example: qwen2.5-7b-instruct-hcm + type: + description: The hallucination corrector type. Defaults to `vectara`. + type: string + default: vectara + description: + description: "A short description of the hallucination corrector\u2019s\ + \ purpose." + type: string + example: Qwen/Qwen2.5-7B-Instruct for hallucination correction in AI-generated + text. + enabled: + description: Indicates whether the hallucination corrector is enabled and + available for use in hallucination correction workflows. + type: boolean + example: true + ListHallucinationCorrectorsResponse: + description: Response containing a list of hallucination correctors. + type: object + properties: + hallucination_correctors: + description: An array of hallucination correctors that match the request + parameters. + type: array + items: + $ref: '#/components/schemas/HallucinationCorrector' + metadata: + $ref: '#/components/schemas/ListMetadata' + Job: + description: A background job for processing long-running operations on the + platform. + type: object + properties: + id: + description: The ID of the job. + type: string + pattern: job_.+$ + type: + description: The type of job. + type: string + enum: + - rebuild_vector_index + - replace_filter_attributes + - unknown + corpus_keys: + description: The corpora that this job belongs to. It may not belong to + any corpora. + type: array + items: + $ref: '#/components/schemas/CorpusKey' + state: + $ref: '#/components/schemas/JobState' + created_at: + description: Specifies when the job was created. + type: string + format: date-time + started_at: + description: Specifies when the job was started. + type: string + format: date-time + completed_at: + description: Specifies when the job was completed. + type: string + format: date-time + created_by_username: + description: The username of the user who created the job. This property + may be missing, e.g., if the job was created by the system, not a user. + type: string + JobState: + description: Enum representing the possible states of a background job. + type: string + enum: + - unknown + - queued + - started + - completed + - failed + - failed_will_retry + - aborted + ListJobsResponse: + description: Response containing a list of background jobs and their current + states. + type: object + properties: + jobs: + description: An array of jobs. + type: array + items: + $ref: '#/components/schemas/Job' + metadata: + $ref: '#/components/schemas/ListMetadata' + CreateUserRequest: + description: Request to create a new user account in the system. + type: object + properties: + email: + description: The email address for the user. + type: string + format: email + username: + description: The username for the user. The value defaults to the email. + type: string + description: + description: The description of the user. + type: string + api_roles: + description: The role names assigned to the user. + type: array + items: + $ref: '#/components/schemas/ApiRole' + required: + - email + UpdateUserRequest: + description: Request to update an existing user's properties or permissions. + type: object + properties: + enabled: + description: Indicates whether to enable or disable the user. + type: boolean + api_roles: + description: The new role names of the user. + type: array + items: + $ref: '#/components/schemas/ApiRole' + User: + description: A user account with associated profile information and permissions. + type: object + properties: + id: + description: The Vectara ID for the user. + type: string + pattern: usr_.+ + email: + description: The email address for the user. + type: string + format: email + username: + description: The username for the user. + type: string + enabled: + description: Indicates whether the user is enabled or disabled. + type: boolean + description: + description: The description of the user. + type: string + created_at: + description: When the user was created. + type: string + format: date-time + updated_at: + description: When a user property was last updated. + type: string + format: date-time + api_roles: + description: The role names of the user. + type: array + items: + $ref: '#/components/schemas/ApiRole' + api_policy: + $ref: '#/components/schemas/ApiPolicy' + ListUsersResponse: + description: Response containing a list of user accounts. + type: object + properties: + users: + description: List of users. + type: array + items: + $ref: '#/components/schemas/User' + metadata: + $ref: '#/components/schemas/ListMetadata' + ApiRole: + description: Roles that a user or an app client can take on. + type: string + enum: + - owner + - administrator + - billing_administrator + - corpus_administrator + ApiPolicy: + description: What actions a principal can take on the Vectara platform. + type: object + properties: + name: + description: The name of the API role. + type: string + allowed_operations: + description: Operations that are allowed by the API role. Each operation + may only allow certain resources that are described by a resource path + to resource value map. If the value is null, then the operation is allowed + on any resource. + type: object + additionalProperties: + $ref: '#/components/schemas/ApiOperationPolicy' + required: + - name + - allowed_operations + ApiOperationPolicy: + description: Policy to allow operations if only using the specified resource. + type: object + properties: + allow_any_resource: + description: If any resource is allowed for the operation. + type: boolean + default: true + allowed_resources: + description: Object with keys of resource paths to a list of allowed resources. + A resource path starts with either body, path, or implicit. A body or + path resource is within the operation body, and an implicit resource is + a resource implied by the request. + type: object + additionalProperties: + type: array + items: + type: string + required: + - allow_any_resource + Language: + description: Languages that the Vectara platform supports. + type: string + enum: + - 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: auto + QueryHistorySummary: + description: A summary of a previously executed query, including metadata but + not full results. + type: object + properties: + id: + description: The ID of the query history. + type: string + query: + description: The actual query made. + type: string + corpus_key: + description: The corpus key that the query was made on. + type: string + started_at: + description: ISO date time indicating when the query was first received. + type: string + format: date-time + latency_millis: + description: Time that the query took in milliseconds. + type: integer + chat_id: + description: The unique ID of the chat associated with the query, if this + query is part of a chat. + type: string + generation: + description: Generated response to the query, if requested. + type: string + factual_consistency_score: + description: The factual consistency score of the generation. + type: number + format: float + QueryHistory: + description: A complete record of a previously executed query, including the + request parameters and response. + type: object + properties: + id: + description: The ID of the query history. + type: string + query: + $ref: '#/components/schemas/QueryRequest' + chat_id: + description: The ID of the chat the query is a part of. + type: string + latency_millis: + description: Time taken to complete the query, measured in milliseconds. + type: integer + started_at: + description: ISO date time indicating when the query was first received. + type: string + format: date-time + spans: + description: Parts of the query pipeline. Each span explains what happened + during that stage of the query pipeline. + type: array + items: + $ref: '#/components/schemas/QueryHistorySpan' + QueryHistorySpan: + description: Portion of the query history. + type: object + discriminator: + propertyName: type + mapping: + rephrase: '#/components/schemas/RephraseSpan' + search: '#/components/schemas/SearchSpan' + rerank: '#/components/schemas/RerankSpan' + generation: '#/components/schemas/GenerationSpan' + fcs: '#/components/schemas/FactualConsistencyScoreSpan' + rewritten_query: '#/components/schemas/RewrittenQuerySpan' + oneOf: + - $ref: '#/components/schemas/RephraseSpan' + - $ref: '#/components/schemas/SearchSpan' + - $ref: '#/components/schemas/RerankSpan' + - $ref: '#/components/schemas/GenerationSpan' + - $ref: '#/components/schemas/FactualConsistencyScoreSpan' + - $ref: '#/components/schemas/RewrittenQuerySpan' + RephraseSpan: + description: During the query pipeline, the query may be rephrased to better + suit the corpus. + type: object + properties: + type: + description: This value is always `rephrase`. + type: string + latency_millis: + description: Time taken in milliseconds. + type: integer + started_at: + description: When the span started. + type: string + format: date-time + rephrased_query: + description: Query made to the corpora. + type: string + x-vectaraParents: + - QueryHistorySpan + SearchSpan: + description: The search portion of the query pipeline. This occurs before any + reranking span. + type: object + properties: + type: + description: This value is always `search`. + type: string + latency_millis: + description: Time taken in milliseconds. + type: integer + started_at: + description: Indicates when the span started. + type: string + format: date-time + search_results: + description: The search results before reranking. + type: array + items: + $ref: '#/components/schemas/IndividualSearchResult' + x-vectaraParents: + - QueryHistorySpan + RerankSpan: + description: The reranking of the search result. + type: object + properties: + type: + description: This value is always `rerank`. + type: string + latency_millis: + description: Time taken in milliseconds. + type: integer + started_at: + description: When the span started. + type: string + format: date-time + reranked_search_results: + description: The new search results after reranking. + type: array + items: + $ref: '#/components/schemas/RerankedSearchResult' + x-vectaraParents: + - QueryHistorySpan + GenerationSpan: + description: The generation by an LLM. + type: object + properties: + type: + description: This value is always `generation`. + type: string + latency_millis: + description: Time taken in milliseconds. + type: integer + started_at: + description: When the span started. + type: string + format: date-time + prompt: + description: The text sent as a prompt to the LLM. + type: string + generation: + description: The text generated from the LLM. + type: string + x-vectaraParents: + - QueryHistorySpan + FactualConsistencyScoreSpan: + description: The factual consistency of the generation. + type: object + properties: + type: + description: This value is always `fcs`. + type: string + latency_millis: + description: Time taken in milliseconds. + type: integer + started_at: + description: When the span started. + type: string + format: date-time + score: + description: The probability that the summary is factually consistent with + the results. + type: number + format: float + x-vectaraParents: + - QueryHistorySpan + RewrittenQuerySpan: + description: Provides detailed information about a rewritten query generated + for a specific corpus when intelligent query rewriting is enabled. + type: object + properties: + type: + description: Indicates the type of span. This value is always `rewritten_query`. + type: string + corpus_key: + description: The corpus key that the query was made on. + type: string + latency_millis: + description: Time taken in milliseconds. + type: integer + started_at: + description: When the span started. + type: string + format: date-time + warnings: + description: Warnings that occurred during query rewriting. + items: + $ref: '#/components/schemas/RewrittenQueryWarning' + filter_extraction: + $ref: '#/components/schemas/FilterExtraction' + x-vectaraParents: + - QueryHistorySpan + RewrittenQueryWarning: + description: "The warning for the rewritten query.\n * `no_filter_attrs`: Corpus\ + \ has no filter attributes.\n * `extracted_empty_filter`: No filter found\ + \ in the query to extract or the platform failed to extract it.\n * `failed_to_parse_extracted_filter`:\ + \ Failed to parse the extracted filter due to invalid syntax.\n * `failure`:\ + \ Unexpected error occurred." + type: string + enum: + - no_filter_attrs + - extracted_empty_filter + - failed_to_parse_extracted_filter + - failure + ListQueryHistoriesResponse: + description: An array of query histories. + type: object + properties: + queries: + type: array + items: + $ref: '#/components/schemas/QueryHistorySummary' + metadata: + description: The metadata for the list of query histories. + type: object + properties: + page_key: + description: A query parameter required when requesting the next page + of results. + type: string + QueryWarning: + type: string + description: "Non-fatal warnings that occurred during query processing.\n *\ + \ `exceeded_max_input_length_fcs`: The input to the Factual Consistency Score\ + \ model exceeded the maximum allowed length, so no score is being returned\n\ + \ * `intelligent_query_rewriting_failed`: Intelligent query rewriting failed\ + \ due to an internal error" + enum: + - exceeded_max_input_length_fcs + - intelligent_query_rewriting_failed + ComputeCorpusSizeResponse: + type: object + description: Response containing the computed size of a corpus + properties: + used_docs: + description: Number of documents in the corpus + type: integer + format: int64 + used_parts: + description: Number of document parts in the corpus + type: integer + format: int64 + used_characters: + description: Total number of characters in the corpus + type: integer + format: int64 + used_metadata_characters: + description: Number of metadata characters in the corpus + type: integer + format: int64 + RemoteAuth: + type: object + description: Authentication configuration for an LLM + discriminator: + propertyName: type + mapping: + bearer: '#/components/schemas/BearerAuth' + header: '#/components/schemas/HeaderAuth' + oneOf: + - $ref: '#/components/schemas/BearerAuth' + - $ref: '#/components/schemas/HeaderAuth' + required: + - type + BearerAuth: + type: object + description: Bearer token authentication + properties: + type: + description: Must be "bearer" for bearer token auth + type: string + default: bearer + token: + description: The bearer token to use for authentication + type: string + required: + - type + - token + x-vectaraParents: + - RemoteAuth + HeaderAuth: + type: object + description: Custom header-based authentication + properties: + type: + description: Must be "header" for header-based auth + type: string + default: header + header: + description: The header name to use (e.g. x-api-key) + type: string + value: + description: The header value to use + type: string + required: + - type + - header + - value + x-vectaraParents: + - RemoteAuth + ListMetadata: + type: object + description: The standard metadata in the response of a list operation. + properties: + page_key: + description: When requesting the next page of this list, this is needed + as a query parameter. + type: string + FilterExtraction: + type: object + description: The result of query filter extraction. + properties: + query: + description: The query rephrased from the input query and executed. + type: string + metadata_filter: + description: The metadata filter extracted from the input query. + type: string + SummarizeDocumentRequest: + type: object + description: Request to summarize a document + required: + - llm_name + properties: + llm_name: + description: The name of the LLM. + type: string + prompt_template: + type: string + description: The prompt template to use when generating the summary. 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](https://docs.vectara.com/docs/prompts/vectara-prompt-engine). + model_parameters: + type: object + description: Optional parameters for the specified model used when generating + the summary. + additionalProperties: true + stream_response: + description: Indicates whether the response should be streamed or not. + type: boolean + default: false + SummarizeDocumentResponse: + type: object + description: Response containing the summary of a document + properties: + summary: + description: The summary of the document + type: string + rendered_prompt: + description: The rendered prompt sent to the LLM. Useful when `prompt_template` + is sent in the request. + type: string + SummarizeDocumentStreamedResponse: + description: An individual event sent with Server-sent Events (SSE) when the + document summarization request is streamed. + type: object + discriminator: + propertyName: type + mapping: + generation_chunk: '#/components/schemas/StreamGenerationChunk' + generation_info: '#/components/schemas/GenerationInfo' + generation_end: '#/components/schemas/StreamGenerationEnd' + error: '#/components/schemas/StreamError' + end: '#/components/schemas/StreamResponseEnd' + oneOf: + - $ref: '#/components/schemas/StreamGenerationChunk' + - $ref: '#/components/schemas/GenerationInfo' + - $ref: '#/components/schemas/StreamGenerationEnd' + - $ref: '#/components/schemas/StreamResponseEnd' + - $ref: '#/components/schemas/StreamError' + HallucinationCorrectionRequest: + description: The request to detect and correct hallucinations in generated text. + type: object + required: + - generated_text + - documents + - model + properties: + generated_text: + type: string + description: The generated text to be evaluated. The hallucination corrector + reviews this text and applies corrections based on the provided source + documents. + documents: + type: array + description: The source documents that were used to generate the text. + items: + $ref: '#/components/schemas/HcmSourceDocument' + model: + type: string + description: The name of the LLM model to use for hallucination correction. + HcmSourceDocument: + description: An array of source documents used to verify the factual accuracy + of the generated text. Each document should reflect the context used to generate + the original text. + type: object + required: + - text + properties: + text: + type: string + description: The full text content of the source document. Hallucination + correction uses this content as the factual basis for correcting the generated + text. + HallucinationCorrectionResponse: + description: The response that contains the hallucination correction results. + type: object + required: + - corrected_text + - corrections + properties: + corrections: + type: array + description: A list of corrections applied to the text, with explanations. + items: + $ref: '#/components/schemas/CorrectionItem' + corrected_text: + type: string + description: The revised version of the text, with minimal edits made to + correct unsupported or inaccurate statements. If no corrections are needed, + this value is identical to the original text. + model: + type: string + description: The name of the model used for hallucination correction. + CorrectionItem: + description: A single correction applied to a span of text in the generated + text. + type: object + required: + - original_text + - corrected_text + - explanation + properties: + original_text: + type: string + description: The original text containing a hallucination or error. + corrected_text: + type: string + description: The corrected version of the text. + explanation: + type: string + description: An explanation of why the correction was needed for the text. + NotFoundError: + description: Error returned when a requested resource does not exist. + type: object + properties: + id: + description: The ID cannot be found. + type: string + messages: + type: array + items: + title: message + type: string + request_id: + description: The ID of the request that can be used to help Vectara support + debug what went wrong. + type: string + BadRequestError: + description: Error returned when a request contains invalid parameters or violates + schema validation. + type: object + properties: + field_errors: + description: The errors that relate to specific fields in the request. + type: object + additionalProperties: + type: string + messages: + type: array + items: + title: message + type: string + request_id: + description: The ID of the request that can be used to help Vectara support + debug what went wrong. + type: string + Error: + description: A general error response with an error code and message. + type: object + properties: + messages: + description: The messages describing why the error occurred. + type: array + items: + title: message + type: string + example: Internal server error. + request_id: + description: The ID of the request that can be used to help Vectara support + debug what went wrong. + type: string + CreateChatCompletionRequest: + description: The request object for creating a chat completion with an OpenAI-compatible + interface. This object is compatible with OpenAI's chat completion schema + and supports customizable parameters for response generation. + type: object + required: + - messages + - model + properties: + model: + type: string + description: The ID of the model to use. This field is required. + messages: + type: array + description: An ordered array of messages that represent the full context + of the conversation to date. Each message includes a `role` and `content`. + minItems: 1 + items: + $ref: '#/components/schemas/ChatCompletionRequestMessage' + stream: + type: boolean + description: Optional. When set to `true`, the API streams partial message + deltas as they become available, similar to ChatGPT's streaming mode. + default: false + additionalProperties: true + ChatCompletionRequestMessage: + description: A message in the chat completion request, representing part of + the conversation. + type: object + required: + - role + - content + properties: + role: + type: string + description: The role of the author of this message. Common values include + 'system', 'user', 'assistant', 'function', and 'tool'. + content: + type: string + description: The contents of the message. + name: + type: string + description: The name of the author of this message, used to connect messages + in a conversation. + CreateChatCompletionResponse: + description: Response object containing the generated chat completion. + type: object + required: + - object + - choices + properties: + object: + type: string + enum: + - chat.completion + description: The object type, which is always 'chat.completion'. + choices: + type: array + description: A list of chat completion choices. Can be more than one if + `n` is greater than `1`. + items: + $ref: '#/components/schemas/ChatCompletionResponseChoice' + additionalProperties: true + ChatCompletionResponseChoice: + description: A single chat completion choice returned in the response + type: object + required: + - index + - message + properties: + index: + type: integer + description: The index of the choice in the array of choices. + message: + $ref: '#/components/schemas/ChatCompletionResponseMessage' + additionalProperties: true + ChatCompletionResponseMessage: + description: A message in the chat completion response from the assistant. + type: object + required: + - role + properties: + role: + type: string + description: The role of the author of this message, typically 'assistant' + for responses. + additionalProperties: true + CreateChatCompletionStreamResponse: + description: The response object for streaming chat completions in chunks. + type: object + required: + - object + - choices + properties: + object: + type: string + enum: + - chat.completion.chunk + description: The object type, which is always 'chat.completion.chunk' for + streaming responses. + choices: + type: array + description: A list of chat completion chunks. + items: + $ref: '#/components/schemas/ChatCompletionStreamResponseChoice' + additionalProperties: true + ChatCompletionStreamResponseChoice: + description: A single chat completion chunk choice in a streaming response. + type: object + required: + - index + - delta + properties: + index: + type: integer + description: The index of the choice in the array of choices. + delta: + $ref: '#/components/schemas/ChatCompletionStreamResponseDelta' + additionalProperties: true + ChatCompletionStreamResponseDelta: + description: A partial message update to be merged with previous chunks in a + streaming response. + type: object + properties: + role: + type: string + description: The role of the author of this message, typically 'assistant' + for responses. + additionalProperties: true + securitySchemes: + OAuth2: + type: oauth2 + description: OAuth2 access to Vectara + flows: + clientCredentials: + tokenUrl: https://auth.vectara.io/oauth2/token + scopes: {} + ApiKeyAuth: + type: apiKey + in: header + name: x-api-key + parameters: + RequestTimeout: + in: header + name: Request-Timeout + description: The API will make a best effort to complete the request in the + specified seconds or time out. + schema: + type: integer + minimum: 1 + required: false + RequestTimeoutMillis: + in: header + name: Request-Timeout-Millis + description: The API will make a best effort to complete the request in the + specified milliseconds or time out. + schema: + type: integer + minimum: 1 +security: +- ApiKeyAuth: [] +- OAuth2: [] diff --git a/fern/apis/vectara-oas.yml b/fern/apis/vectara-oas.yml new file mode 100644 index 000000000..b6b4ac061 --- /dev/null +++ b/fern/apis/vectara-oas.yml @@ -0,0 +1,3967 @@ +openapi: 3.0.0 +info: + title: Vectara REST API + version: 1.0.0 + termsOfService: https://vectara.com/legal/online-customer-agreement/ + x-logo: + url: https://docs.vectara.com/img/vectara_wordmark.png + altText: Vectara + x-dark-logo: + url: https://docs.vectara.com/img/vectara_wordmark_light.png + altText: Vectara + contact: + name: Vectara Support + email: support@vectara.com + url: http://support.vectara.com/ + description: "Vectara provides an end-to-end platform for creating GenAI products using \na simple to use API.\n\nYou can [sign up for an account](https://console.vectara.com/signup) and \nthen view several [API Recipes](https://docs.vectara.com/docs/api-recipes) with example queries \nand parameter values.\n\nThe Vectara API Playground lets you experiment with REST endpoints from \nyour browser. Select an endpoint to view its definition, including the \nrequired or optional headers, body, responses, and sample commands. On the \nright side of each endpoint page, you manually \nenter your API Key or OAuth Bearer Token, `customer_id`, and then any \nrequired body parameters like the `corpusID` before sending the API \nrequest.\n\n:::note\n\nVectara has three kinds of API keys: the Personal API Key, Index API Keys, \nand Query API Keys. The Personal API Key enables administrative tasks \nincluding creating, deleting, and listing corpora, and managing Index and \nQuery API keys for accessible corpora, reading usage data, updating \ncorpora filters, executing queries, and indexing. Query API Keys are used\nfor read-only querying operations, while Index API Keys provide read and \nwrite access. The OAuth operations authenticate with a Bearer Token via the\nOAuth 2.0 client credentials grant. Review the [**OAuth 2.0 section**](https://docs.vectara.com/docs/learn/authentication/oauth-2) about \nhow to generate the token." +tags: + - name: AdminService + description: Administrative operations, such as creating or deleting corpora + - name: IndexService + description: Indexing operations, such as creating and deleting documents + - name: QueryService + description: Query operations, such as performing a search and retrieval augmented generation + - name: DocumentService + description: Document operations, listing documents in a corpus + - name: ChatService + description: Chat operations, such as listing and reading conversations +# add file upload API and auth options for other APIs +paths: + /v1/compute-account-size: + post: + operationId: ComputeAccountSize + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminComputeAccountSizeResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminComputeAccountSizeRequest" + description: >- + Please note that this is an expensive operation, and the requests can be throttled + + by the platform. + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Computes the amount of quota consumed across the entire Vectara account. + + Some tips for this API: + * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2). + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/compute-corpus-size: + post: + operationId: ComputeCorpusSize + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminComputeCorpusSizeResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminComputeCorpusSizeRequest" + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: "Computes the amount of quota consumed by a corpus. This capability is useful for administrators to track and monitor the amount \nof usage for specific corpora.\n\nSome tips for this API:\n* This operation works with the Personal API Key and OAuth 2.0 (in a JWT \"Bearer Token\") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).\n* The `filter` feature applies to either the name *or* the description of a corpus.\n" + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/create-api-key: + post: + operationId: CreateApiKey + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminCreateApiKeyResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminCreateApiKeyRequest" + description: |- + This request can be used to create one or more ApiKeys. + Every ApiKey is bound to one or more corpora. + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Creates an API key that you bind with a specific corpus or multiple corpora. You can create an API key that only gives access to query data (read-only) or an API key that gives access to both querying and serving (read-write). + + Some tips for this API: + * This operation only works with OAuth 2.0 (in a JWT "Bearer Token") authentication. It does not work with API Keys. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2). + security: + - oAuth: [] + /v1/create-corpus: + post: + operationId: CreateCorpus + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminCreateCorpusResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminCreateCorpusRequest" + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Creates a corpus, which is a container to store data in. + + Some tips for this API: + * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2). + * The `name` of the corpus is the only required field. + * Filter attributes tell Vectara which metadata fields you'd like to run SQL-style filters against. If you need to change them after you've created the corpus, see the [Replace Filter Attributes API](https://docs.vectara.com/docs/rest-api/replace-corpus-filter-attrs) + * `textless` and `customDimensions` are features that are only available to [Scale](https://vectara.com/pricing/) accounts. + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/delete-api-key: + post: + operationId: DeleteApiKey + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminDeleteApiKeyResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminDeleteApiKeyRequest" + type: object + properties: + keyIds: + type: array + items: + type: string + examples: + DeleteSingleKey: + value: + keyIds: + - "ID of API Key" + DeleteMultipleKeys: + value: + keyIds: + - "ID of Key 1" + - "ID of Key 2" + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: "Deletes API keys to help you manage the security and lifecycle of API keys in your application. \nSome tips for this API:\n* This operation only works with OAuth 2.0 (in a JWT \"Bearer Token\") authentication. It does not work with API Keys. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).\n" + security: + - oAuth: [] + /v1/delete-conversations: + post: + operationId: DeleteConversations + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/chatDeleteConversationsResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/chatDeleteConversationsRequest" + required: true + tags: + - ChatService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: "Delete conversations from the chat history corpus. This is useful for data management to help ensure that you maintain data hygiene and support compliance with data retention policies. \n\nSome tips for this API:\n* 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](https://docs.vectara.com/docs/console-ui/manage-api-access).\n" + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/delete-corpus: + post: + operationId: DeleteCorpus + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminDeleteCorpusResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminDeleteCorpusRequest" + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Deletes a corpus and all of the data contained inside of the corpus. + + Some tips for this API: + * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2). + * It can take a few seconds to completely delete the corpus if there's heavy system load. Be patient if the corpus is still present after a deletion request is initiated. + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/delete-doc: + post: + operationId: Delete + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/vectaraDeleteDocumentResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/vectaraDeleteDocumentRequest" + description: Request to delete a document from an index. + required: true + tags: + - IndexService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Delete documents from a corpus. + + Some tips for this API: + * This operation authenticates with either the Personal API Key, Index 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](https://docs.vectara.com/docs/console-ui/manage-api-access). + * You can quickly delete all documents from a corpus to clear it out by using the [Reset Corpus](https://docs.vectara.com/docs/rest-api/reset-corpus) operation. + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/delete-turns: + post: + operationId: DeleteTurns + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/chatDeleteTurnsResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/chatDeleteTurnsRequest" + required: true + tags: + - ChatService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: "Deletes specific turns from a conversation within the chat history corpus. This enables developers to remove inaccurate or inappropriate responses from the conversation history. \n\nSome tips for this API:\n* 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](https://docs.vectara.com/docs/console-ui/manage-api-access).\n" + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/disable-turns: + post: + operationId: DisableTurns + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/chatDisableTurnsResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/chatDisableTurnsRequest" + required: true + tags: + - ChatService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: "Disables specific turns from a conversation within the chat history corpus. This is useful for excluding specific turns from a conversation. \n\nSome tips for this API:\n* 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](https://docs.vectara.com/docs/console-ui/manage-api-access).\n" + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/enable-api-key: + post: + operationId: EnableApiKey + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminEnableApiKeyResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminEnableApiKeyRequest" + examples: + EnableAPIKey: + value: + keyEnablement: + - keyId: "ID of the API Key" + enable: true + DisableAPIKey: + value: + keyEnablement: + - keyId: "ID of the API Key" + enable: false + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: "Enables or disables a specific API key.\n \nSome tips for this API:\n* This operation works with the Personal API Key and OAuth 2.0 (in a JWT \"Bearer Token\") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).\n" + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/get-usage-metrics: + post: + operationId: GetUsageMetrics + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminUsageMetricsResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminUsageMetricsRequest" + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Displays usage information about indexing and query operations in a corpus. This helps administrators in analyzing and managing resource consumption more efficiently for specific corpora. + + Some tips for this API: + * Use these metrics to determine usage patterns that enable you to optimize resource allocations. + * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2). + * The `filter` feature applies to either the name *or* the description of a corpus. + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/index: + post: + operationId: Index + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/vectaraIndexDocumentResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/vectaraIndexDocumentRequest" + examples: + BookExample: + value: + customerId: 123456 + corpusId: 1 + document: + documentId: "isbn-9781405053976" + title: "The Hitchhiker's Guide to the Galaxy" + description: "A great book with the answer to life, the universe, and everything" + metadataJson: '{"author": "Douglas Adams"}' + section: + - title: Intro + text: "Far out in the uncharted backwaters of the unfashionable end of the western spiral arm of the Galaxy lies a small unregarded yellow sun." + metadataJson: '{"page": 1}' + - title: The answer + text: "The Answer to the Great Question ... Of Life, the Universe and Everything ... Is ... Forty-two." + metadataJson: '{"speaker": "Deep Thought"}' + GrowthExample: + value: + customerId: 890123 + corpusId: 8 + document: + documentId: "literature-1234-5678-analysis-expanded" + title: "Exploring the Depths of 'Moby Dick': An Expanded Analysis" + description: "An expanded in-depth analysis of the characters, themes, narrative structure, and historical context within Herman Melville's 'Moby Dick'." + metadataJson: '{"author": "Leslie Thompson", "genre": "Classic Literature", "publishedYear": "1851"}' + section: + - title: Character Analysis + text: "A detailed look at the development of key characters, exploring their symbolic meanings within the narrative." + metadataJson: '{"section": "characterAnalysis"}' + - title: Thematic Exploration + text: "Examination of major themes, including the struggle against fate and the exploration of good vs. evil." + metadataJson: '{"section": "thematicExploration"}' + - title: Narrative Structure + text: "Analysis of Melville's innovative narrative structure, including the use of multiple narrators and non-linear storytelling." + metadataJson: '{"section": "narrativeStructure"}' + - title: Historical Context + text: "A look at the historical backdrop of 'Moby Dick', including its reflection of contemporary social issues and the whaling industry." + metadataJson: '{"section": "historicalContext"}' + ScaleExample: + value: + customerId: 901234 + corpusId: 9 + document: + documentId: "home-improvement-8765-4321-review-expanded" + title: "Ultimate Guide to Power Tools: Expanded Edition" + description: "An expanded comprehensive review of the latest drills, saws, safety equipment, and innovative tools available at Home Depot." + metadataJson: '{"author": "Derek Lee", "category": "Power Tools", "store": "Home Depot"}' + customDims: + - name: "Rating" + value: 4.5 + - name: "Affordability" + value: 3.5 + section: + - title: Drill Reviews + text: "Deep dive into the best drills, comparing models based on power, battery life, and ease of use." + metadataJson: '{"section": "drillReviews"}' + customDims: + - name: "PowerRating" + value: 5 + - title: Saw Reviews + text: "Evaluation of top saws for precision cutting, highlighting key features for woodworkers." + metadataJson: '{"section": "sawReviews"}' + customDims: + - name: "Durability" + value: 4.5 + - title: Safety Equipment + text: "Reviews of essential safety equipment for using power tools, including goggles, gloves, and ear protection." + metadataJson: '{"section": "safetyEquipment"}' + customDims: + - name: "SafetyRating" + value: 5 + - title: Innovative Tools + text: "Spotlight on innovative tools that are changing the game in home improvement, from smart drills to laser-guided saws." + metadataJson: '{"section": "innovativeTools"}' + customDims: + - name: "InnovationScore" + value: 4.8 + ReviewExample: + value: + customerId: 234567 + corpusId: 2 + document: + documentId: "review-f876-1937-90d6-a7e9" + title: "The Fusion Mug: The Hottest Way to Burn Your Mouth and Your Wallet" + description: "Have you ever wanted to combine the pleasure of drinking coffee with the thrill of nuclear fusion? Look no further than the Fusion Mug!" + metadataJson: '{"author": "George P Burdell"}' + section: + - title: Intro + text: "This revolutionary mug promises to keep your coffee piping hot for millennia, thanks to its built-in fusion reactor. Yes, you read that right - a real, honest-to-goodness fusion reactor! What could possibly go wrong?" + metadataJson: '{"section": "intro"}' + - title: Main Benefit + text: "Let me tell you, folks, this mug is a game-changer. The fusion reactor heats up your coffee to the perfect temperature in seconds, without any of that annoying waiting around for your drip pot to do its thing. And the taste? Oh, man. It's like the coffee beans themselves were infused with pure energy from the heart of the sun. I've never tasted anything like it." + metadataJson: '{"section": "benefit1"}' + - title: Counterpoint + text: "Now, I know what you're thinking... 'But George, isn't nuclear fusion dangerous? Won't it give me cancer or something?' Ha! That's just the kind of paranoia that keeps people from truly experiencing life. Sure, there might be some minor risks involved, but come on. What's a little radiation poisoning compared to the pure, unadulterated joy of a perfect cup of coffee?" + metadataJson: '{"section": "counterpoint"}' + - title: Conclusion + text: "In conclusion, if you're not using the Fusion-Powered Perfection mug to drink your coffee, you might as well be drinking mud. This mug is the ultimate in technological sophistication and gourmet taste. It will make your coffee so good that you'll never want to drink anything else again. And if you're worried about the so-called 'risks' of using a fusion reactor to heat your beverage, well, maybe you're just not cut out for the high-stakes world of elite coffee connoisseurship. So go ahead and stick with your bland, boring, non-nuclear coffee mugs. We'll be over here, sipping the sweet nectar of the gods from our Fusion-Powered Perfection mugs." + metadataJson: '{"section": "conclusion"}' + required: true + tags: + - IndexService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + This is the "standard" Indexing API for indexing semi-structured, text-heavy "documents." Indexing data into Vectara is typically very fast: within a few seconds. + + Some tips for this API: + * This operation authenticates with either the Personal API Key, Index 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](https://docs.vectara.com/docs/console-ui/manage-api-access). + * Vectara does require a special format for JSON objects you'd like to index. Some tips on how to model data in the indexing API, see the documentation [here](https://docs.vectara.com/docs/learn/document-data-structuring). + * The `metadataJson` object needs the JSON to be escaped so that it's not confused with other parts of the request JSON. + * [Custom dimensions](https://docs.vectara.com/docs/learn/semantic-search/add-custom-dimensions) (`customDims`) is a feature that is only available to [Scale](https://vectara.com/pricing/) accounts. + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/list-api-keys: + post: + operationId: ListApiKeys + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminListApiKeysResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminListApiKeysRequest" + type: object + properties: + numResults: + type: integer + apiKeyType: + type: array + items: + type: string + readCorporaInfo: + type: boolean + examples: + PersonalKey: + value: + numResults: 5 + apiKeyType: + - "API_KEY_TYPE__PERSONAL" + readCorporaInfo: true + QueryKey: + value: + numResults: 5 + apiKeyType: + - "API_KEY_TYPE__SERVING" + readCorporaInfo: true + IndexandQueryKey: + value: + numResults: 5 + apiKeyType: + - "API_KEY_TYPE__SERVING_INDEXING" + readCorporaInfo: true + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Lists the API keys and the associated corpora names and IDs. + + Some tips for this API: + * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2). + * The `filter` feature applies to either the name *or* the description of a corpus. + security: + - ApiKeyAuth: [] + - oAuth: [] + # add chat endpoints + /v1/list-conversations: + post: + operationId: ListConversations + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/chatListConversationsResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/chatListConversationsRequest" + required: true + tags: + - ChatService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + List all the conversations in a specific corpus. This data enables developers to monitor chatbot interactions and understand how users engage with the data. Pagination lets developers navigate through large datasets. + + 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](https://docs.vectara.com/docs/console-ui/manage-api-access). + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/list-corpora: + post: + operationId: ListCorpora + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminListCorporaResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminListCorporaRequest" + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Lists all corpora accessible to the OAuth client. + + Some tips for this API: + * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2). + * The `filter` feature applies to either the name *or* the description of a corpus. + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/list-documents: + post: + operationId: ListDocuments + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/listsListDocumentsResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/listsListDocumentsRequest" + description: Request to list documents in a corpus. + required: true + tags: + - DocumentService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Lists information about each document ingested into the corpus including the Document ID and metadata. This is useful for managing the lifecycle of documents and a quick way to check which documents are already in the index. + + Some tips for this API: + * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2). + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/list-jobs: + post: + operationId: ListJobs + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminListJobsResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminListJobsRequest" + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + List the jobs associated with this account. Jobs are background processes like [replacing the filterable metadata attributes](https://docs.vectara.com/docs/rest-api/replace-corpus-filter-attrs). + + Some tips for this API: + * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2). + * It's best practice to filter as much as possible (by date, by status, and/or by job ID) to make job lists as easy to interpret as possible, as there can be many for a given time window. + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/list-users: + post: + operationId: ListUsers + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminListUsersResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminListUsersRequest" + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: "Lists the users in your account along with their corpus access and customer-level authorizations. \nSome tips for this API:\n* This operation only works with OAuth 2.0 (in a JWT \"Bearer Token\") authentication. It does not work with API Keys. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).\n* Use this API to view the members on your team. If you need to manage their access, use the Manage User endpoint.\n" + security: + - oAuth: [] + /v1/manage-user: + post: + operationId: ManageUser + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminManageUserResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminManageUserRequest" + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Lets you manage users in your account by adding, deleting, enabling, or disabling users. You can also reset their passwords and edit user roles. This endpoint can help you streamline your onboarding process by programmatically adding new users, assigning appropriate roles, and setting up permissions. + Some tips for this API: + * This operation only works with OAuth 2.0 (in a JWT "Bearer Token") authentication. It does not work with API Keys. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2). + * Add multiple users by including additional β€œuser” objects into the userAction array. + security: + - oAuth: [] + /v1/query: + post: + operationId: Query + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/servingBatchQueryResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + $ref: "#/components/requestBodies/servingBatchQueryRequest" + content: + application/json: + examples: + GrowthExample: + value: + query: + - query: "What are they latest trends in renewable energy?" + start: 0 + numResults: 5 + contextConfig: + charsBefore: 20 + charsAfter: 20 + startTag: "" + endTag: "" + corpusKey: + - corpusId: 2 + lexicalInterpolationConfig: + lambda: 0.5 + summary: + - maxSummarizedResults: 3 + responseLang: "en" + factualConsistencyScore: true + ScaleExample: + value: + query: + - query: "What are they latest trends in renewable energy?" + start: 0 + numResults: 10 + contextConfig: + sentencesBefore: 3 + sentencesAfter: 3 + startTag: "" + endTag: "" + corpusKey: + - corpusId: 3 + semantics: "DEFAULT" + dim: + - name: "relevance" + weight: 1.5 + metadataFilter: "sector = 'energy'" + lexicalInterpolationConfig: + lambda: 0.7 + rerankingConfig: + rerankerId: 272725718 + mmrConfig: + diversityBias: 0.4 + summary: + - summarizerPromptName: "vectara-summary-ext-v1.3.0" + maxSummarizedResults: 3 + responseLang: "en" + promptText: | + [ + {"role": "system", "content": "You are an expert in summarizing the latest trends in renewable energy. Your summaries are insightful, concise, and highlight key innovations and challenges."}, + #foreach ($result in $vectaraQueryResults) + {"role": "user", "content": "What are the key points in result number $vectaraIdxWord[$foreach.index] about renewable energy trends?"}, + {"role": "assistant", "content": "In result number $vectaraIdxWord[$foreach.index], the key points are: ${result.getText()}"}, + #end + {"role": "user", "content": "Can you generate a comprehensive summary on 'renewable energy trends' incorporating all the key points discussed?"} + ] + responseChars: 500 + modelParams: + maxTokens: 1024 + temperature: 0.6 + frequencyPenalty: 0.2 + presencePenalty: 0.1 + factualConsistencyScore: true + ChatExample: + value: + query: + - query: "What is renewable energy?" + queryContext: "" + start: 0 + numResults: 10 + contextConfig: + charsBefore: 0 + charsAfter: 0 + startTag: "%START_SNIPPET%" + endTag: "%END_SNIPPET%" + corpusKey: + - corpusId: 12 + semantics: 0 + metadataFilter: "" + summary: + - chat: + store: true + conversationId: "1d8f0258-3358-475a-b5eb-02a775cee09e" + maxSummarizedResults: 5 + responseLang: "eng" + schema: + $ref: '#/components/schemas/servingBatchQueryRequest' + tags: + - QueryService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Search for relevant results, highlight relevant snippets, and do + [Retrieval Augmented Generation](https://docs.vectara.com/docs/learn/grounded-generation/grounded-generation-overview) (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](https://docs.vectara.com/docs/console-ui/manage-api-access). + * 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](https://docs.vectara.com/docs/learn/semantic-search/hybrid-search). + * 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](https://docs.vectara.com/docs/learn/grounded-generation/grounded-generation-overview). + * 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](https://vectara.com/pricing/) accounts. + * Reranking enhances search accuracy and variety and more details can be found [here](https://docs.vectara.com/docs/api-reference/search-apis/reranking). + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/read-conversations: + post: + operationId: ReadConversations + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/chatReadConversationsResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/chatReadConversationsRequest" + required: true + tags: + - ChatService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: "Retrieves detailed information about specific conversations. This information enables developers to analyze the flow of user chats and understand the context of interactions, which helps in refining chatbot responses. You can read up to 100 conversations. \n\nSome tips for this API:\n* 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](https://docs.vectara.com/docs/console-ui/manage-api-access).\n" + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/read-corpus: + post: + operationId: ReadCorpus + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminReadCorpusResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminReadCorpusRequest" + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Displays detailed information about corpora within your account including basic information, metadata, and whether it is enabled or disabled. + This endpoint can help administrators monitor the amount of quota consumed by tenants. + + Some tips for this API: + * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2). + * The `filter` feature applies to either the name *or* the description of a corpus. + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/replace-corpus-filter-attrs: + post: + operationId: ReplaceCorpusFilterAttrs + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminReplaceCorpusFilterAttrsResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminReplaceCorpusFilterAttrsRequest" + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Updates the filterable metadata fields for the corpus. + + See our documentation on [filterable metadata fields](https://docs.vectara.com/docs/learn/metadata-search-filtering/filter-overview) for more details on how these are used. + + Some tips for this API: + * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2). + * Each request to replace the corpus filter attributes kicks off a background [job](https://docs.vectara.com/docs/rest-api/list-jobs). The job ID is returned when you kick off a metadata filter update job so you can track it later. + * Existing filters will continue to apply until the update job completes. + * The time that update filter jobs take is roughly proportional to the size of the corpus. Updates on small corpora generally take a few minutes at most, but updates on large corpora can take many minutes to hours to complete. + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/reset-corpus: + post: + operationId: ResetCorpus + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminResetCorpusResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminResetCorpusRequest" + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Resets a corpus by removing all of the documents inside of it. + + Some tips for this API: + * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2). + * The `filter` feature applies to either the name *or* the description of a corpus. + * If you want to delete individual documents instead of all documents in the corpus, you can use the [Delete API](https://docs.vectara.com/docs/rest-api/delete). + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/stream-query: + post: + operationId: StreamQuery + responses: + "200": + description: A successful response.(streaming responses) + content: + application/json: + schema: + type: object + properties: + result: + $ref: "#/components/schemas/servingQueryResponsePart" + error: + $ref: "#/components/schemas/googlerpcStatus" + title: Stream result of servingQueryResponsePart + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + $ref: "#/components/requestBodies/servingBatchQueryRequest" + tags: + - QueryService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Stream responses as you search for relevant results, highlight relevant snippets, and do + [Retrieval Augmented Generation](https://docs.vectara.com/docs/learn/grounded-generation/grounded-generation-overview) (RAG). + + Instead of receiving a complete response like with the Standard Query API, you receive partial responses in this order: + 1. Search results. + 2. If summarization is enabled, you get chunks of the summary, like "This", "is", "a", "summary". + 3. If FCS is enabled, then the FCS is the final response. + + 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](https://docs.vectara.com/docs/console-ui/manage-api-access). + * 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](https://vectara.com/pricing/) accounts. + * Reranking enhances search accuracy and variety and more details can be found [here](https://docs.vectara.com/docs/api-reference/search-apis/reranking). + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/update-corpus-enablement: + post: + operationId: UpdateCorpusEnablement + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/adminUpdateCorpusEnablementResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/adminUpdateCorpusEnablementRequest" + required: true + tags: + - AdminService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + Lets you enable or disable a corpus. This is useful when you need to take the corpus offline without having to delete the corpus. + + Some tips for this API: + * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2). + * The `filter` feature applies to either the name *or* the description of a corpus. + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/core/index: + post: + operationId: CoreIndex + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/vectaraIndexCoreDocumentResponse" + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/googlerpcStatus" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/vectaraIndexCoreDocumentRequest" + description: Request to index a document. + required: true + tags: + - IndexService + parameters: + - $ref: '#/components/parameters/customerIdentifier' + - $ref: '#/components/parameters/timeout' + description: | + This API is intended to be used by experts. It gives you fine-grained control over chunking + strategies by using the `parts`. Most users will want to use the [File Upload API](https://docs.vectara.com/docs/rest-api/file-upload) or the "standard" [Index API](https://docs.vectara.com/docs/rest-api/index). + + Some tips for this API: + * This operation authenticates with either the Personal API Key, Index 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](https://docs.vectara.com/docs/console-ui/manage-api-access). + * The `metadataJson` object needs the JSON to be escaped so that it's not confused with other parts of the request JSON. + * [Custom dimensions](https://docs.vectara.com/docs/learn/semantic-search/add-custom-dimensions) (`customDims`) is a feature that is only available to [Scale](https://vectara.com/pricing/) accounts. + security: + - ApiKeyAuth: [] + - oAuth: [] + /v1/upload: + post: + description: | + The File Upload API can be used to index binary files like PDFs, Word Documents, and similar. + Vectara will attempt to automatically extract the text and any metadata from the document like + author or title, though you can provide additional metadata as well. + + Some tips for this API: + * This operation authenticates with either the Personal API Key, Index 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](https://docs.vectara.com/docs/console-ui/manage-api-access). + * You can find a full list of supported file formats [here](https://docs.vectara.com/docs/api-reference/indexing-apis/file-upload/file-upload-filetypes). + * To provide additional metadata, set the `doc_metadata` field. You can find some additional details [here](https://docs.vectara.com/docs/api-reference/indexing-apis/file-upload/file-upload#attach-additional-metadata) + * PDFs must contain text: Vectara does not currently support indexing scanned images via OCR. + * There is a known issue with the OpenAPI plugin where the generated Python script for file uploads incorrectly uses placeholder values for the file path and filename. Manually replace '/path/to/file' and 'file' in the files array with the actual file path and filename. + operationId: FileUpload + tags: + - IndexService + security: + - ApiKeyAuth: [] + - oAuth: [] + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + doc_metadata: + description: A JSON string of any additional metadata you want attached to the file. + type: string + file: + description: The file to be indexed into Vectara. + type: string + format: binary + required: + - file + parameters: + - in: query + name: c + required: true + description: Customer ID + schema: + type: integer + - in: query + name: o + required: true + description: Corpus ID + schema: + type: integer + example: 1 + - in: query + name: d + required: false + description: If true, the server returns the extracted document that was indexed + schema: + type: boolean + responses: + "200": + description: A successful response + content: + application/json: + schema: + type: object + properties: + response: + type: object + properties: + status: + type: object + quotaConsumed: + type: object + properties: + numChars: + type: string + description: The number of characters Vectara indexed from the file uploaded. + numMetadataChars: + type: string + description: The number of metadata characters Vectara indexed from the file uploaded. + "400": + description: An invalid request was sent. e.g. one or more parameters was missing, or the corpus does not exist. + content: + application/json: + schema: + type: object + properties: + httpCode: + type: integer + description: Returned HTTP code + "401": + description: The request was not authenticated + "403": + description: The caller is not authorized to add documents to the corpus + "409": + description: |- + A document already exists in the corpus with the same document ID, yet the contents of the indexed document are different than the file being uploaded. + Since the indexer is idempotent, the same document (identified by the document ID) can be uploaded multiple times. + The indexer does not support updates yet, so an error is returned when a different document is uploaded for the same document ID + Note that when a raw file is uploaded, the file name is used as the document ID. + "507": + description: There is no more indexing quota left for the corpus or customer to index more documents. Upgrade your account, add a credit card, or contact sales. +components: + requestBodies: + servingBatchQueryRequest: + content: + application/json: + schema: + $ref: "#/components/schemas/servingBatchQueryRequest" + required: true + schemas: + CorpusKeySemantics: + type: string + enum: + - DEFAULT + - QUERY + - RESPONSE + default: DEFAULT + description: >- + 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. + CreateApiKeyRequestApiKeyCorpus: + type: object + properties: + description: + type: string + description: Description of the ApiKey. + apiKeyType: + $ref: "#/components/schemas/adminApiKeyType" + corpusId: + type: array + items: + type: integer + format: int64 + description: List of corpus ids to bind the ApiKey to. + description: ApiKey data to create the ApiKey bound to one or more corpora. + CreateApiKeyResponseApiKeyOrStatus: + type: object + properties: + keyId: + type: string + description: A valid ApiKey. + status: + $ref: "#/components/schemas/comvectaraStatus" + description: A valid key or Status of the ApiKey creation (in case of failure). + EnableApiKeyRequestApiKeyEnablement: + type: object + properties: + keyId: + type: string + description: ApiKey id to enable or disable. + enable: + type: boolean + title: Enable or disable using this variable + ListApiKeysResponseKeyAndCorpora: + type: object + properties: + apiKey: + $ref: "#/components/schemas/adminApiKey" + corpus: + type: array + items: + $ref: "#/components/schemas/ListApiKeysResponseKeyAndCorporaCorpusInfo" + description: List of corpora associated with the ApiKey. + description: A message containing ApiKey and associated corpora. + ListApiKeysResponseKeyAndCorporaCorpusInfo: + type: object + properties: + id: + type: integer + format: int64 + description: Corpus id. + name: + type: string + description: Corpus name. + description: Message containing corpus name and id. + ListDocumentsResponseDocumentInfo: + type: object + properties: + id: + type: string + description: The document ID that was used when indexing the document. + metadata: + type: array + items: + $ref: "#/components/schemas/comvectaraAttribute" + description: Document metadata. + description: Document information format of each document in the list. + ManageUserRequestUserAction: + type: object + properties: + user: + $ref: "#/components/schemas/adminUser" + userActionType: + $ref: "#/components/schemas/adminUserActionType" + title: User and action to be performed on user + ManageUserResponseUserResponse: + type: object + properties: + user: + $ref: "#/components/schemas/adminUser" + status: + $ref: "#/components/schemas/comvectaraStatus" + title: List of users and their status + QueryRequestContextConfig: + type: object + example: + sentences_before: 3 + sentences_after: 3 + start_tag: + end_tag: + properties: + charsBefore: + type: integer + format: int32 + example: 30 + description: >- + chars_before is used for showing the end user the characters leading up + + to the result snippet. This can help the end-user understand the + + context of that result. Ignored if sentences_before is set. + charsAfter: + type: integer + format: int32 + example: 30 + description: >- + chars_after is used for showing the end user the characters after the + + result snippet. This can help the end-user understand the context of + + that result. Ignored if sentences_before is set. + sentencesBefore: + type: integer + format: int32 + example: 3 + description: >- + sentences_before is used for showing the end user the sentences leading + + up to the result snippet. This can help the end-user understand the + + context of that result. + sentencesAfter: + type: integer + format: int32 + example: 3 + description: >- + sentences_after is used for showing the end user the sentences leading + + up to the result snippet. This can help the end-user understand the + + context of that result. + startTag: + type: string + example: + description: >- + The tag that wraps the snippet at the start. Often this is 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 snippet begins. + endTag: + type: string + example: + description: >- + The tag that wraps the snippet at the end. Often this is 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 snippet ends and the context after begins. + description: |- + Allows processing a matched document part text before being returned + as a search result. Allows a search result to have more of the document + than just the matched document part. + required: + - sentencesBefore + - sentencesAfter + - startTag + - endTag + QueryRequestRerankingConfig: + type: object + properties: + rerankerId: + type: integer + format: int64 + title: |- + Which reranking model to use if reranking. Currently, the only IDs + available are: + - 272725717, HuggingFace Open Source x-attentional reranker + - 272725718, Maximum Marginal Relevance Reranker + mmrConfig: + $ref: "#/components/schemas/servingMMRConfig" + description: Configuration options to apply to the reranking. + SummarizationRequestModelParams: + type: object + properties: + maxTokens: + type: integer + format: int64 + temperature: + type: number + format: float + description: >- + The sampling temperature to use. Higher values make the summary more random, while lower + + values make it more focused and deterministic. + frequencyPenalty: + type: number + format: float + description: >- + 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. + presencePenalty: + type: number + format: float + description: >- + 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. + description: >- + Parameters for the summarizer model. These are currently a Scale-only feature. + + See https://vectara.com/pricing/ for more details on becoming a Scale customer. + + 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. + UsageMetricsRequestMetricType: + type: string + enum: + - METRICTYPE__NONE + - METRICTYPE__INDEXING + - METRICTYPE__SERVING + default: METRICTYPE__NONE + title: The type of metric to get + UsageMetricsResponseIntervalValue: + type: object + properties: + indexingValue: + $ref: "#/components/schemas/adminIndexingMetric" + servingValue: + $ref: "#/components/schemas/adminServingMetric" + title: The response for a single interval + adminAbsoluteWindow: + type: object + properties: + startEpochSecs: + type: string + format: int64 + endEpochSecs: + type: string + format: int64 + title: This window is used to specify a time range for metrics + adminApiKey: + type: object + properties: + id: + type: string + description: + type: string + description: Description of the ApiKey. + keyType: + $ref: "#/components/schemas/adminApiKeyType" + enabled: + type: boolean + description: Whether the ApiKey is enabled. + tsStart: + type: string + format: int64 + description: Seconds sinch Epoch when the ApiKey becomes active. + tsEnd: + type: string + format: int64 + description: Seconds sinch Epoch when the ApiKey becomes inactive. + status: + $ref: "#/components/schemas/adminApiKeyStatus" + publicId: + type: integer + format: int64 + description: An id of the key that is not sensitive. + description: >- + Represents an ApiKey. + + An ApiKey provides anonymous access to common tasks such as index data, query data, etc. + adminApiKeyStatus: + type: string + enum: + - UNKNOWN + - ENABLED + - DISABLED + - DELETED + default: UNKNOWN + description: Status of ApiKey. + adminApiKeyType: + type: string + enum: + - API_KEY_TYPE__UNDEFINED + - API_KEY_TYPE__SERVING + - API_KEY_TYPE__SERVING_INDEXING + - API_KEY_TYPE__PERSONAL + default: API_KEY_TYPE__UNDEFINED + description: >- + Types of ApiKey. + + + + + + + + + + + + - API_KEY_TYPE__SERVING: ApiKey for serving. Only gives access to query data. + - API_KEY_TYPE__SERVING_INDEXING: ApiKey for serving and indexing. Gives access to both query and index data. + - API_KEY_TYPE__PERSONAL: ApiKey for personal access key. + adminComputeAccountSizeRequest: + type: object + description: >- + Please note that this is an expensive operation, and the requests can be throttled + + by the platform. + adminComputeAccountSizeResponse: + type: object + properties: + size: + type: array + items: + $ref: "#/components/schemas/adminTextSize" + description: >- + One TextSize represents one cluster. The account size is a sum of all the sizes. + + Generally, this will only have one value. + status: + $ref: "#/components/schemas/comvectaraStatus" + adminComputeCorpusSizeRequest: + type: object + properties: + corpusId: + type: integer + format: int64 + description: The corpus for which to compute the size. + adminComputeCorpusSizeResponse: + type: object + properties: + size: + $ref: "#/components/schemas/adminCorpusSize" + status: + $ref: "#/components/schemas/comvectaraStatus" + adminCorpus: + type: object + properties: + id: + type: integer + format: int64 + description: |- + The Corpus ID. + This value is ignored during Corpus creation. + name: + type: string + description: The name of the corpus. + description: + type: string + description: A description for the corpus. + dtProvision: + type: string + format: int64 + description: |- + The time at which the corpus was provisioned. + This value is ignored during Corpus creation. + enabled: + type: boolean + description: |- + Whether the corpus is enabled for use or not. + This value is ignored during Corpus creation. + swapQenc: + type: boolean + swapIenc: + type: boolean + description: >- + The default query encoder is designed for normal question-answering types + + of queries when the text contains the answer. Swapping the index encoder + + is generally rare, but can be used to help directly match questions to + + questions. This can be useful if you have a FAQ dataset and you want to + + directly match the user question to the question in the FAQ. + textless: + type: boolean + description: >- + When a corpus is "textless", Vectara does not store the original text. + + Instead, Vectara converts the text to vectors and only retains metadata. + encrypted: + type: boolean + description: Encryption is on by default and cannot be turned off. + encoderId: + type: string + format: uint64 + description: >- + This is an advanced setting for changing the underlying model type. The + + default value is "1", which is Vectara's high-performing global model. + + Underlying models may be swapped for some paying customers by contacting + + our support team. + metadataMaxBytes: + type: integer + format: int64 + description: An optional maximum size of the metadata that each document can contain. + customDimensions: + type: array + items: + $ref: "#/components/schemas/adminDimension" + filterAttributes: + type: array + items: + $ref: "#/components/schemas/adminFilterAttribute" + adminCorpusSize: + type: object + properties: + epochSecs: + type: string + format: int64 + description: The time at which the size was calculated. + size: + type: string + format: uint64 + description: The size of the corpus. + adminCreateApiKeyRequest: + type: object + properties: + apiKeyData: + type: array + items: + $ref: "#/components/schemas/CreateApiKeyRequestApiKeyCorpus" + description: List of ApiKey data to create. + description: |- + This request can be used to create one or more ApiKeys. + Every ApiKey is bound to one or more corpora. + adminCreateApiKeyResponse: + type: object + properties: + response: + type: array + items: + $ref: "#/components/schemas/CreateApiKeyResponseApiKeyOrStatus" + description: List of ApiKeyOrStatus corresponding to the list of ApiKey data in request. + description: Response of the CreateApiKeyRequest. + adminCreateCorpusRequest: + type: object + properties: + corpus: + $ref: "#/components/schemas/adminCorpus" + adminCreateCorpusResponse: + type: object + properties: + corpusId: + type: integer + format: int64 + description: The Corpus ID that was created. + status: + $ref: "#/components/schemas/comvectaraStatus" + adminCustomerRole: + type: string + enum: + - CustomerRole_None + - CustomerRole_Owner + - CustomerRole_Admin + - CustomerRole_Billing_Admin + - CustomerRole_Corpus_Admin + default: CustomerRole_None + description: >2- + - CustomerRole_Owner: The owner is the root user of the account. Only an owner can shut + down the account completely. + - CustomerRole_Admin: An account administrator can do things like create corpora, add or remove users etc. + - CustomerRole_Billing_Admin: View and modify billing-related information for the account. + - CustomerRole_Corpus_Admin: View and modify corpus-related information for the account. + adminDeleteApiKeyRequest: + type: object + properties: + keyId: + type: array + items: + type: string + description: List of ApiKey ids to delete. + adminDeleteApiKeyResponse: + type: object + properties: + status: + type: array + items: + $ref: "#/components/schemas/comvectaraStatus" + description: Status of the DeleteApiKeyRequest. + adminDeleteCorpusRequest: + type: object + example: + corpusId: 1 + properties: + customerId: + type: integer + format: int64 + description: The Customer ID that contains the corpus to be deleted. + corpusId: + type: integer + format: int64 + description: The Corpus ID to be deleted. + minimum: 1 + required: + - customerId + - corpusId + adminDeleteCorpusResponse: + type: object + properties: + status: + $ref: "#/components/schemas/comvectaraStatus" + adminDimension: + type: object + properties: + name: + type: string + description: |- + The name of the custom dimension. The maximum length of the name is + 8 characters. + description: + type: string + description: A description for the custom dimension. + servingDefault: + type: number + format: double + description: >- + The default weight to give this dimension when running queries. A value of + + 0.0, for example, gives it no weight at all. + indexingDefault: + type: number + format: double + description: The default value to give to documents for this custom dimension. + description: >- + A custom dimension is additional numeric metadata that you want to affect + + Vectara's scoring. For example, these could be "number of stars" ratings, + + or other business metrics like a product's margins that you want to use + + to boost where a result is in the list. + adminEnableApiKeyRequest: + type: object + properties: + keyEnablement: + type: array + items: + $ref: "#/components/schemas/EnableApiKeyRequestApiKeyEnablement" + description: List of ApiKey ids to enable or disable. + adminEnableApiKeyResponse: + type: object + properties: + status: + type: array + items: + $ref: "#/components/schemas/comvectaraStatus" + description: List of Status such as OK, FAILED corresponding to the EnableApiKeyRequest. + adminFilterAttribute: + type: object + properties: + name: + type: string + description: Name of the field, as seen in metadata. + description: + type: string + description: An optional description. + indexed: + type: boolean + description: Whether the field is indexed for maximum query speed. + type: + $ref: "#/components/schemas/adminFilterAttributeType" + level: + $ref: "#/components/schemas/adminFilterAttributeLevel" + description: Defines metadata fields that can be used in predicate queries. + adminFilterAttributeLevel: + type: string + enum: + - FILTER_ATTRIBUTE_LEVEL__UNDEFINED + - FILTER_ATTRIBUTE_LEVEL__DOCUMENT + - FILTER_ATTRIBUTE_LEVEL__DOCUMENT_PART + default: FILTER_ATTRIBUTE_LEVEL__UNDEFINED + title: |- + - FILTER_ATTRIBUTE_LEVEL__DOCUMENT: Document-level attribute + - FILTER_ATTRIBUTE_LEVEL__DOCUMENT_PART: Part-level attribute + adminFilterAttributeType: + type: string + enum: + - FILTER_ATTRIBUTE_TYPE__UNDEFINED + - FILTER_ATTRIBUTE_TYPE__INTEGER + - FILTER_ATTRIBUTE_TYPE__INTEGER_LIST + - FILTER_ATTRIBUTE_TYPE__REAL + - FILTER_ATTRIBUTE_TYPE__REAL_LIST + - FILTER_ATTRIBUTE_TYPE__TEXT + - FILTER_ATTRIBUTE_TYPE__TEXT_LIST + - FILTER_ATTRIBUTE_TYPE__BOOLEAN + default: FILTER_ATTRIBUTE_TYPE__UNDEFINED + adminIndexingMetric: + type: object + properties: + docCount: + type: string + format: uint64 + title: The number of documents indexed + docPartCount: + type: string + format: uint64 + title: The number of document parts indexed + docPartBytes: + type: string + format: uint64 + description: >- + The number of bytes indexed. + + In case of Upload API, this is the actual bytes extracted from the document and not + + the size of the document. + + In case of Index API, this is the combined size of text in all the sections of the document. + startEpochSecs: + type: string + format: int64 + title: The start time for this metric + title: Indexing data + adminJob: + type: object + properties: + id: + type: string + type: + $ref: "#/components/schemas/adminJobType" + corpusId: + type: array + items: + type: integer + format: int64 + description: Set if the job belongs to a corpus. + state: + $ref: "#/components/schemas/adminJobState" + tsCreate: + type: string + format: int64 + description: Epoch (secs) when the job was created. + tsStart: + type: string + format: int64 + description: |- + Epoch (secs) when the job was started. Not set if the job + hasn't started yet. + tsComplete: + type: string + format: int64 + description: |- + Epoch (secs) when the job completed. Not set if the job + hasn't completed yet. + userHandle: + type: string + description: Handle of the user that created this job. + description: >- + Represents a job in the system. + + A job is typically a long running unit of work for achieving a particular outcome. + + Example job: replace filter attributes of a corpus. + adminJobState: + type: string + enum: + - JOB_STATE__UNKNOWN + - JOB_STATE__QUEUED + - JOB_STATE__STARTED + - JOB_STATE__COMPLETED + - JOB_STATE__FAILED + - JOB_STATE__TRANSIENT_FAILURE_RETRY_IMMINENT + - JOB_STATE__ABORTED + default: JOB_STATE__UNKNOWN + description: The state of a job. + adminJobType: + type: string + enum: + - JOB__UNKNOWN + - JOB__CORPUS_REBUILD_VECTOR_INDEX + - JOB__CORPUS_REPLACE_FILTER_ATTRS + default: JOB__UNKNOWN + description: Type of jobs. + adminListApiKeysRequest: + type: object + properties: + numResults: + type: integer + format: int64 + description: Max results to return. + pageKey: + type: string + format: byte + description: |- + A key that is passed to retrieve a specific page of results. + Leave empty to retrieve first page. Subsequent page requests should + use the page key returned in previous response, and all other + fields are ignored. + apiKeyType: + type: array + items: + $ref: "#/components/schemas/adminApiKeyType" + description: >- + [Optional] Get API keys of these types. + + Default: If not set, API_KEY_TYPE__SERVING and API_KEY_TYPE__SERVING_INDEXING are returned. + readCorporaInfo: + type: boolean + description: If set, returns corpus name & id associated with api keys. + adminListApiKeysResponse: + type: object + properties: + keyData: + type: array + items: + $ref: "#/components/schemas/ListApiKeysResponseKeyAndCorpora" + description: List of ApiKey and associated corpora. + pageKey: + type: string + format: byte + description: |- + A key that is passed into a subsequent result in order to + retrieve the next page of results. + status: + $ref: "#/components/schemas/comvectaraStatus" + adminListCorporaRequest: + type: object + example: + numResults: 10 + filter: "[Tt][Ee][Ss][Tt]" + properties: + filter: + type: string + example: "[Tt][Ee][Ss][Tt]" + description: A regex over the names and descriptions to match corpora against. + numResults: + type: integer + format: int64 + description: The maximum results to return. + minimum: 1 + pageKey: + type: string + format: byte + description: A key that is passed in to retrieve a specific page of results. + required: + - numResults + adminListCorporaResponse: + type: object + properties: + corpus: + type: array + items: + $ref: "#/components/schemas/adminCorpus" + pageKey: + type: string + format: byte + description: |- + A key that is passed into a subsequent result in order to + retrieve the next page of results. + status: + $ref: "#/components/schemas/comvectaraStatus" + adminListJobsRequest: + type: object + properties: + jobId: + type: string + description: |- + Optional filters. If specified, the filters are logically ANDed. + + [Optional] If specified, return the job for this id. + corpusId: + type: array + items: + type: integer + format: int64 + description: "[Optional] If specified, return jobs for these corpora only." + epochSecs: + type: string + format: int64 + description: |- + [Optional] Get jobs that were created since this epoch timestamp. + Max allowed value is 180 days ago. Default is 180 days. + state: + type: array + items: + $ref: "#/components/schemas/adminJobState" + description: >- + [Optional] Get jobs with these states. If not specified, all job + + states are fetched. + + Default: If not set, JOB_STATE__QUEUED and JOB_STATE__STARTED are returned. + numResults: + type: integer + format: int64 + description: Maximum results to return. Max allowed value is 100. + pageKey: + type: string + format: byte + description: |- + A key that is passed in to retrieve a specific page of results. + Leave empty to retrieve first page. Subsequent page request should + use the page key returned in previous response, and all other + fields are ignored. + adminListJobsResponse: + type: object + properties: + status: + type: array + items: + $ref: "#/components/schemas/comvectaraStatus" + job: + type: array + items: + $ref: "#/components/schemas/adminJob" + pageKey: + type: string + format: byte + description: |- + A key that is passed into a subsequent result in order to + retrieve the next page of results. + adminListUsersRequest: + type: object + properties: + listUsersType: + $ref: "#/components/schemas/adminListUsersType" + pageKey: + type: string + format: byte + description: |- + A key that is passed to retrieve a specific page of results. + Leave empty to retrieve first page. Subsequent page requests should + use the page key returned in previous response, and all other + fields are ignored. + numResults: + type: integer + format: int64 + description: Number of results to return. + adminListUsersResponse: + type: object + properties: + user: + type: array + items: + $ref: "#/components/schemas/adminUser" + title: List of users + pageKey: + type: string + format: byte + description: |- + A key that is passed into a subsequent result in order to + retrieve the next page of results. + status: + $ref: "#/components/schemas/comvectaraStatus" + adminListUsersType: + type: string + enum: + - LIST_USERS_TYPE__NONE + - LIST_USERS_TYPE__CUSTOMER + - LIST_USERS_TYPE__ALL + default: LIST_USERS_TYPE__NONE + title: >- + - LIST_USERS_TYPE__CUSTOMER: Only List users with customer account-level authorizations. + + + + + + + + + + + - LIST_USERS_TYPE__ALL: List All the users + adminManageUserRequest: + type: object + properties: + userAction: + type: array + items: + $ref: "#/components/schemas/ManageUserRequestUserAction" + title: List of users and actions to be performed on them + adminManageUserResponse: + type: object + properties: + response: + type: array + items: + $ref: "#/components/schemas/ManageUserResponseUserResponse" + description: List of users alongwith relative status such as OK, FAILED etc. + adminReadCorpusRequest: + type: object + properties: + corpusId: + type: array + items: + type: integer + format: int64 + description: Corpora IDs to read. + readBasicInfo: + type: boolean + description: >- + Subset of information to read. + + Set to true to read basic information about the corpus such as id, name, + + description, enabled, etc. + readSize: + type: boolean + description: Set to true to read the size of the corpus. + readApiKeys: + type: boolean + description: Set to true to read the API keys associated with the corpus. + readCustomDimensions: + type: boolean + description: Set to true to read the custom dimensions of the corpus. + readFilterAttributes: + type: boolean + description: Set to true to read the filter attributes of the corpus. + adminReadCorpusResponse: + type: object + properties: + corpora: + type: array + items: + $ref: "#/components/schemas/adminReadCorpusResponseCorpusInfo" + description: Information about the requested corpora. + adminReadCorpusResponseCorpusInfo: + type: object + properties: + corpus: + $ref: "#/components/schemas/adminCorpus" + corpusStatus: + $ref: "#/components/schemas/comvectaraStatus" + size: + $ref: "#/components/schemas/adminCorpusSize" + sizeStatus: + $ref: "#/components/schemas/comvectaraStatus" + apiKey: + type: array + items: + $ref: "#/components/schemas/adminApiKey" + description: API keys associated with the corpus. Only populated if read_api_keys is true. + apiKeyStatus: + $ref: "#/components/schemas/comvectaraStatus" + customDimension: + type: array + items: + $ref: "#/components/schemas/adminDimension" + description: Custom dimensions of the corpus. Only populated if read_custom_dimensions is true. + customDimensionStatus: + $ref: "#/components/schemas/comvectaraStatus" + filterAttribute: + type: array + items: + $ref: "#/components/schemas/adminFilterAttribute" + description: Filter attributes of the corpus. Only populated if read_filter_attributes is true. + filterAttributeStatus: + $ref: "#/components/schemas/comvectaraStatus" + description: A Corpus information object containing the requested information. + adminReplaceCorpusFilterAttrsRequest: + type: object + properties: + corpusId: + type: integer + format: int64 + description: The corpus for which to update filters. + filterAttributes: + type: array + items: + $ref: "#/components/schemas/adminFilterAttribute" + description: The filters to set. The existing filters are replaced with this list of filters. + adminReplaceCorpusFilterAttrsResponse: + type: object + properties: + status: + $ref: "#/components/schemas/comvectaraStatus" + jobId: + type: string + description: >- + If 'status' represents success, this contains the ID assigned to the job + + for updating the list of filters. This ID can be used to query the status + + of the job. + adminResetCorpusRequest: + type: object + example: + corpusId: 1 + properties: + customerId: + type: integer + format: int64 + description: The Customer ID that contains the corpus to be reset. + corpusId: + type: integer + format: int64 + description: The Corpus ID to be reset. + minimum: 1 + required: + - customerId + - corpusId + adminResetCorpusResponse: + type: object + properties: + status: + $ref: "#/components/schemas/comvectaraStatus" + adminServingMetric: + type: object + properties: + rowsRead: + type: string + format: uint64 + title: The number of rows read + queryCount: + type: string + format: uint64 + title: The number of queries + startEpochSecs: + type: string + format: int64 + title: The start time for this metric + title: Serving/querying data + adminTextSize: + type: object + properties: + numChars: + type: string + format: uint64 + description: Count of actual characters in the text that will be searched. + numMetadataChars: + type: string + format: uint64 + description: Count of metadata characters such as URL, author, date of creation etc. + description: A TextSize object represents the size of stored text. + adminUpdateCorpusEnablementRequest: + type: object + properties: + corpusId: + type: integer + format: int64 + description: The corpus to enable or disable. + enable: + type: boolean + description: If true, enable the corpus. Otherwise, disable it. + adminUpdateCorpusEnablementResponse: + type: object + properties: + status: + $ref: "#/components/schemas/comvectaraStatus" + adminUsageMetricsRequest: + type: object + properties: + corpusId: + type: integer + format: int64 + description: The corpus for which the metric is requested. + window: + $ref: "#/components/schemas/adminAbsoluteWindow" + type: + $ref: "#/components/schemas/UsageMetricsRequestMetricType" + aggregationIntervalSecs: + type: string + format: int64 + description: >- + The response stats will be aggregated by this interval. Minimum aggregation interval is 1 minute. + + Supported granularity units for aggregation are days, hours and minutes. + + For example, If 2.5 days (in seconds) are passed, results will be aggregated by 2 days. + + Similarly, if 7.6 hours (in seconds) are passed, results will be aggregated by 7 hours. + title: The request type for usage metrics + adminUsageMetricsResponse: + type: object + properties: + values: + type: array + items: + $ref: "#/components/schemas/UsageMetricsResponseIntervalValue" + description: >- + List of IntervalValue containing values for either Indexing or Serving. These are + + aggregated by the interval specified in the request. + status: + $ref: "#/components/schemas/comvectaraStatus" + adminUser: + type: object + properties: + id: + type: integer + format: int64 + description: >- + Unique ID for the user. This is required for deleting, enabling, disabling a user + + or to reset their password. This can be retrieved via ListUsers API or it is also + + returned as part of ManageUser API when a new user is created. + handle: + type: string + description: Name of the user. This is required for creating a new user. + type: + $ref: "#/components/schemas/adminUserType" + comment: + type: string + title: Comment about the user + tsCreate: + type: string + format: int64 + description: Seconds since epoch when the user was created. + idCreate: + type: integer + format: int64 + description: ID of the user who created this user. + email: + type: string + description: Email address associated with the user. This is required for creating a new user. + userStatus: + $ref: "#/components/schemas/adminUserStatus" + role: + type: array + items: + $ref: "#/components/schemas/adminCustomerRole" + title: List of customer level roles + description: |- + Represents a user in an account. + A user is a person or an application that has access to the system. + adminUserActionType: + type: string + enum: + - USER_ACTION_TYPE__NONE + - USER_ACTION_TYPE__ADD + - USER_ACTION_TYPE__DELETE + - USER_ACTION_TYPE__DISABLE + - USER_ACTION_TYPE__ENABLE + - USER_ACTION_TYPE__RESET_PASSWORD + default: USER_ACTION_TYPE__NONE + title: |- + - USER_ACTION_TYPE__ADD: Add User + - USER_ACTION_TYPE__DELETE: Delete User + - USER_ACTION_TYPE__DISABLE: Disable User + - USER_ACTION_TYPE__ENABLE: Enable User + - USER_ACTION_TYPE__RESET_PASSWORD: Reset User Password + adminUserStatus: + type: string + enum: + - USER_STATUS__NONE + - USER_STATUS__ACTIVE + - USER_STATUS__DISABLED + default: USER_STATUS__NONE + title: |- + - USER_STATUS__ACTIVE: User is active + - USER_STATUS__DISABLED: User is disabled + adminUserType: + type: string + enum: + - USER_TYPE__NONE + - USER_TYPE__USER + - USER_TYPE__FEDERATED_USER + - USER_TYPE__APP_CLIENT + default: USER_TYPE__NONE + description: >2- + - USER_TYPE__USER: A normal user + - USER_TYPE__FEDERATED_USER: A user that is authenticated by an external identity provider such as Google etc. + - USER_TYPE__APP_CLIENT: An application client. Please note that this doesn't work with ManageUser API. + To create an App Client, use the ManageAppClient API. + chatConversation: + type: object + properties: + id: + type: string + description: The ID of the conversation. This is unique within the chat history corpus. + turn: + type: array + items: + $ref: "#/components/schemas/chatTurn" + description: The turns comprising this conversation. + description: A chat contains several back-and-forth messages called turns. + chatDeleteConversationsRequest: + type: object + properties: + conversationId: + type: array + items: + type: string + description: "The IDs of the conversations to delete. Limit: 1000 conversations." + chatDeleteConversationsResponse: + type: object + properties: + status: + $ref: "#/components/schemas/comvectaraStatus" + chatDeleteTurnsRequest: + type: object + properties: + conversationId: + type: string + description: The ID of the conversations from which to delete turns. + turnId: + type: string + description: >- + The ID of the turn to start deletion from. All turns in this conversation starting from this + + turn (inclusive) will be deleted. + chatDeleteTurnsResponse: + type: object + properties: + status: + $ref: "#/components/schemas/comvectaraStatus" + chatDisableTurnsRequest: + type: object + properties: + conversationId: + type: string + description: The ID of the conversations from which to disable turns. + turnId: + type: string + description: >- + The ID of the turn to start disabling from. All turns in this conversation starting from this + + turn will be disabled. + chatDisableTurnsResponse: + type: object + properties: + status: + $ref: "#/components/schemas/comvectaraStatus" + chatListConversationsRequest: + type: object + properties: + numResults: + type: integer + format: int64 + description: Maximum number of conversations to return per page. + example: 0 + pageKey: + type: string + format: byte + description: >- + A key that is passed in to retrieve a specific page of results. + + Leave empty to retrieve the first page. Subsequent page request should + + use the page key returned in previous response, and all other + + fields are ignored. + example: "" + # add required headers + chatListConversationsResponse: + type: object + properties: + conversation: + type: array + items: + $ref: "#/components/schemas/chatTurn" + description: >- + The first turn in each conversation. + + This doesn't comprise all turns in each conversation; only the first turn of each + + conversation is returned. + status: + $ref: "#/components/schemas/comvectaraStatus" + pageKey: + type: string + format: byte + description: >- + A key that is passed in to retrieve a specific page of results. + + Pass this as is in to the next request to retrieve the next page of results. + chatReadConversationsRequest: + type: object + properties: + conversationId: + type: array + items: + type: string + description: "The IDs of the conversations to read. Limit: 10 conversations." + chatReadConversationsResponse: + type: object + properties: + Conversation: + type: array + items: + $ref: "#/components/schemas/chatConversation" + status: + $ref: "#/components/schemas/comvectaraStatus" + chatTurn: + type: object + properties: + id: + type: string + description: >- + The ID of the turn. The ID of the first turn in a conversation is the same as the + + ID of the conversation. This is unique within the chat history corpus. + conversationId: + type: string + description: >- + The ID of the conversation this turn belongs to. This is the same as the ID of the + + first turn in the conversation. + query: + type: string + description: The query text. + answer: + type: string + description: The answer text. + enabled: + type: boolean + description: >- + Whether this turn is enabled. If a turn is disabled, it will not be used when + + generating answers for subsequent queries in the conversation. + epochSecs: + type: string + format: int64 + description: The time at which this turn was created. + description: |- + A turn in a conversation is a single exchange of query and answer. + A conversation is composed of several turns. + comvectaraAttribute: + type: object + properties: + name: + type: string + description: Name of the document metadata attribute. + value: + type: string + description: Value of the document metadata attribute. + description: A key/value pair representing a document attribute (metadata item). + comvectaraStatus: + type: object + properties: + code: + $ref: "#/components/schemas/vectaraStatusCode" + statusDetail: + type: string + googlerpcStatus: + type: object + properties: + code: + type: integer + format: int32 + message: + type: string + details: + type: array + items: + $ref: "#/components/schemas/protobufAny" + indexingSection: + type: object + properties: + id: + type: integer + format: int32 + description: >- + Optionally, the unique ID of this section. If set, it will be returned as + + metadata in query results. + title: + type: string + description: Optionally, the title of the section. This may be empty. + text: + type: string + description: The text of the section. This should never be empty. + metadataJson: + type: string + description: >- + Metadata about this section. This should be a json string. It is passed + + through the system, without being used at indexing time. It can be + + retrieved at query time. + section: + type: array + items: + $ref: "#/components/schemas/indexingSection" + description: A list of subsections. + description: A section within a structured document. + listsListDocumentsRequest: + type: object + properties: + corpusId: + type: integer + format: int64 + description: The Corpus ID. + numResults: + type: integer + format: int64 + description: |- + Maximum number of results to be returned by the server. + Max is 1000. + If the value is larger than 1000, it will be capped to 1000. + pageKey: + type: string + format: byte + description: >- + Key of the specific page of the list results to return. + + Null/empty value means the very first page of the results is requested. + metadataFilter: + type: string + description: >- + Filter on document metadata. If empty, no filtering is done. + + Otherwise, only documents that match all of the specified metadata + + will be returned. The syntax is the same as for QueryRequest.metadata. + description: Request to list documents in a corpus. + listsListDocumentsResponse: + type: object + properties: + document: + type: array + items: + $ref: "#/components/schemas/ListDocumentsResponseDocumentInfo" + description: The list of documents. + nextPageKey: + type: string + format: byte + description: >- + Represents the pagination key to retrieve the next page of results. + + If the value is "", it means no further results for the request. + + To retrieve the next page of results, client shall pass the value of next_page_key in the subsequent + + ListDocumentsRequest method call (in the request message's page_key field). + description: Response of listing documents in a corpus. + protobufAny: + type: object + properties: + "@type": + type: string + description: >- + 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. + additionalProperties: {} + description: >- + `Any` contains an arbitrary serialized protocol buffer message along with a + + URL that describes the type of the serialized message. + + + Protobuf library provides support to pack/unpack Any values in the form + + of utility functions or additional generated methods of the Any type. + + + Example 1: Pack and unpack a message in C++. + + + + + + + + + + + + + Foo foo = ...; + Any any; + any.PackFrom(foo); + ... + if (any.UnpackTo(&foo)) { + ... + } + + Example 2: Pack and unpack a message in Java. + + + + + + + + + + + + + Foo foo = ...; + Any any = Any.pack(foo); + ... + if (any.is(Foo.class)) { + foo = any.unpack(Foo.class); + } + + Example 3: Pack and unpack a message in Python. + + + + + + + + + + + + + foo = Foo(...) + any = Any() + any.Pack(foo) + ... + if any.Is(Foo.DESCRIPTOR): + any.Unpack(foo) + ... + + Example 4: Pack and unpack a message in Go + + + + + + + + + + + + + foo := &pb.Foo{...} + any, err := anypb.New(foo) + if err != nil { + ... + } + ... + foo := &pb.Foo{} + if err := any.UnmarshalTo(foo); err != nil { + ... + } + + The pack methods provided by protobuf library will by default use + + 'type.googleapis.com/full.type.name' as the type URL and the unpack + + methods only use the fully qualified type name after the last '/' + + in the type URL, for example "foo.bar.com/x/y.z" will yield type + + name "y.z". + + + + JSON + + + The JSON representation of an `Any` value uses the regular + + representation of the deserialized, embedded message, with an + + additional field `@type` which contains the type URL. Example: + + + + + + + + + + + + + package google.profile; + message Person { + string first_name = 1; + string last_name = 2; + } + + { + "@type": "type.googleapis.com/google.profile.Person", + "firstName": , + "lastName": + } + + If the embedded message type is well-known and has a custom JSON + + representation, that representation will be embedded adding a field + + `value` which holds the custom JSON in addition to the `@type` + + field. Example (for message [google.protobuf.Duration][]): + + + + + + + + + + + + + { + "@type": "type.googleapis.com/google.protobuf.Duration", + "value": "1.212s" + } + servingBatchQueryRequest: + type: object + properties: + query: + type: array + items: + $ref: "#/components/schemas/servingQueryRequest" + description: >- + Each request can have multiple queries that result in multiple search results. Each query can search multiple corpora. + required: ["query"] + example: + query: + - query: "What is the answer to the life, the universe, and everything?" + start: 0 + numResults: 10 + contextConfig: + sentencesBefore: 3 + sentencesAfter: 3 + startTag: "" + endTag: "" + corpusKey: + - customerId: 12345 + corpusId: 12 + summary: + - maxSummarizedResults: 10 + responseLang: "en" + servingBatchQueryResponse: + type: object + properties: + responseSet: + type: array + items: + $ref: "#/components/schemas/servingResponseSet" + description: >- + 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. + status: + type: array + items: + $ref: "#/components/schemas/comvectaraStatus" + metrics: + $ref: "#/components/schemas/servingPerformanceMetrics" + servingChat: + type: object + properties: + conversationId: + type: string + description: The conversation id of the chat. + turnId: + type: string + description: The id assigned to this query and answer. + status: + $ref: "#/components/schemas/comvectaraStatus" + description: Values needed to refer to the chat later. + servingChatRequest: + type: object + properties: + store: + type: boolean + description: Whether to store the query/answer pair. + conversationId: + type: string + description: |- + The conversation id of the chat. + If empty, a new conversation will be started. + description: The chat request. + servingCitationParams: + type: object + properties: + style: + $ref: "#/components/schemas/servingCitationStyle" + urlPattern: + type: string + title: |- + The url pattern if the citation_style is set to HTML or MARKDOWN. + The pattern can access part and doc fields. + i.e. https://my.doc/foo/{doc.id}/{part.id} + textPattern: + type: string + title: >- + The text pattern if the citation_style is set to HTML or MARKDOWN. + + This pattern defaults to N being the index of result if it is not set. + + Final result looks like in this case: [N](https://my.doc/foo) + + It can also be customized to access the part/doc fields by passing + + the field name in curly braces. e.g., {doc.title} or {part.page} + + Final result would look like [Title](https://my.doc/foo/2/1) + description: Citation parameters for the summary. + servingCitationStyle: + type: string + enum: + - NUMERIC + - NONE + - HTML + - MARKDOWN + default: NUMERIC + description: |- + The citation style to be used in summary. They are used to reference + the source of the information from the documents in the summary. + + - NUMERIC: Default style. E.g., [1], [2] + - NONE: No citations. + - HTML: HTML E.g. [N] + - MARKDOWN: MARKDOWN E.g. [N](https://my.doc/foo) + servingCorpusKey: + type: object + example: + corpus_id: 12 + properties: + customerId: + type: integer + format: int64 + description: The Customer ID. + corpusId: + type: integer + format: int64 + description: The Corpus ID. + semantics: + $ref: "#/components/schemas/CorpusKeySemantics" + metadataFilter: + type: string + description: >- + 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: + $ref: "#/components/schemas/servingLinearInterpolation" + description: Object to specify how each corpus in a query is searched. + required: + - corpusId + servingFactualConsistency: + type: object + properties: + score: + type: number + format: float + description: The probability that the summary is factually consistent with the results in the ResponseSet. + status: + $ref: "#/components/schemas/comvectaraStatus" + servingLinearInterpolation: + type: object + properties: + lambda: + type: number + format: float + example: 0.025 + title: >- + Controls the weight given to lexical matches. The final score, S, is then: + + + + + + + + + + + S = (lambda) * (lexical score) + (1 - lambda) * (dense score) + description: Configuration for a linear interpolation. + servingMMRConfig: + type: object + properties: + diversityBias: + type: number + format: float + example: 0.3 + description: The diversity bias. Higher values indicate more diversity. + description: Configuration for the maximum marginal relevance (MMR) reranker. + servingPerformanceMetrics: + type: object + properties: + queryEncodeMs: + type: integer + format: int64 + description: How long it took to encode the query. + retrievalMs: + type: integer + format: int64 + description: How long it took to retrieve relevant results. + userdataRetrievalMs: + type: integer + format: int64 + description: How long it took to retrieve user data. + rerankMs: + type: integer + format: int64 + description: How long it took to rerank the results. + description: Basic performance metrics that can be attached to a server response. + servingQueryRequest: + type: object + properties: + query: + type: string + description: "The query text to use from the end user." + start: + type: integer + format: int64 + title: The start position in the result set + description: "The starting point for the query." + numResults: + type: integer + format: int64 + description: "The number of results to return. Possible values: >= 1" + minimum: 1 + example: 10 + contextConfig: + $ref: "#/components/schemas/QueryRequestContextConfig" + type: object + description: "Allows processing a matched document part text before being returned as a search result." + properties: + charsBefore: + type: integer + description: "chars_before is used for showing the end user the characters leading up to the result snippet. Ignored if sentences_before is set." + charsAfter: + type: integer + description: "chars_after is used for showing the end user the characters after the result snippet. Ignored if sentences_before is set." + sentencesBefore: + type: integer + description: "sentences_before is used for showing the end user the sentences leading up to the result snippet." + example: 3 + sentencesAfter: + type: integer + description: "sentences_after is used for showing the end user the sentences leading up to the result snippet." + example: 3 + startTag: + type: string + description: "The tag that wraps the snippet at the start." + example: "" + endTag: + type: string + description: "The tag that wraps the snippet at the end." + example: "" + corpusKey: + type: array + items: + $ref: "#/components/schemas/servingCorpusKey" + type: object + properties: + customerId: + type: integer + description: "The Customer ID." + corpusId: + type: integer + description: "The Corpus ID. Possible values: >= 1" + minimum: 1 + example: 12 + semantics: + type: string + description: "Semantics controls the interpretation of the query string by the server." + enum: ["DEFAULT", "QUERY", "RESPONSE"] + default: "DEFAULT" + metadataFilter: + type: string + description: "Filter the documents and document parts based on their metadata." + lexicalInterpolationConfig: + type: object + description: "Configuration for a linear interpolation." + properties: + lambda: + type: number + description: "Linear interpolation parameter." + required: ["corpusId"] + description: |- + The query is run on all these corpora, and the results are merged together in the response, ranked by score. + summary: + type: array + items: + $ref: "#/components/schemas/servingSummarizationRequest" + type: object + properties: + summarizerPromptName: + type: string + description: "The name of the summarizer+prompt combination to use for summarization." + maxSummarizedResults: + type: integer + description: "Maximum number of results to summarize." + example: 10 + responseLang: + type: string + description: "ISO 639-1 or ISO 639-3 language code for the response." + example: "en" + promptText: + type: string + description: "The prompt_text is in the form of an Apache Velocity template." + debug: + type: boolean + description: "Debugging the generative prompt." + responseChars: + type: integer + description: "Controls the length of the summary." + modelParams: + type: object + description: "Parameters for the summarizer model." + properties: + maxTokens: + type: integer + description: "Maximum tokens for the summarizer model." + temperature: + type: number + description: "The sampling temperature to use." + frequencyPenalty: + type: number + description: "Higher values penalize new tokens based on their existing frequency in the text so far." + presencePenalty: + type: number + description: "Higher values penalize new tokens based on whether they appear in the text so far." + citationParams: + type: object + description: "Citation parameters for the summary." + properties: + style: + type: string + description: "The citation style to be used in summary." + enum: ["NUMERIC", "NONE", "HTML", "MARKDOWN"] + default: "NUMERIC" + urlPattern: + type: string + description: "The URL pattern if the citation_style is set to HTML or MARKDOWN." + textPattern: + type: string + description: "The text pattern if the citation_style is set to HTML or MARKDOWN." + chat: + type: object + description: "The chat request." + properties: + store: + type: boolean + description: "Whether to store the query/answer pair." + conversationId: + type: string + description: "The conversation ID of the chat. If empty, a new conversation will be started." + factualConsistencyScore: + type: boolean + description: "If unset or true, the response will include the factual consistency score." + required: ["maxSummarizedResults", "responseLang"] + description: "Optionally, one or more requests to summarize the results." + required: ["numResults", "corpusKey"] + servingQueryResponsePart: + type: object + properties: + batchQueryResponse: + $ref: "#/components/schemas/servingBatchQueryResponse" + responseSet: + $ref: "#/components/schemas/servingResponseSet" + summary: + $ref: "#/components/schemas/servingSummary" + status: + type: array + items: + $ref: "#/components/schemas/comvectaraStatus" + description: A status code at the level of a BatchQueryResponse. + description: |- + This message contains individual partial results that are returned + asynchronously by the streaming interface. + servingResponseSet: + type: object + properties: + response: + type: array + items: + $ref: "#/components/schemas/vectaraservingResponse" + description: Search results for the query. + status: + type: array + items: + $ref: "#/components/schemas/comvectaraStatus" + description: Potentially multiple warnings. + document: + type: array + items: + $ref: "#/components/schemas/servingResponseSetDocument" + description: Document level metadata for document parts that are in the response. + summary: + type: array + items: + $ref: "#/components/schemas/servingSummary" + description: >- + 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. + futureId: + type: integer + format: int32 + description: >- + Populated for streaming requests only. This id should matched against + + the query response in order to know which query generated this object. + servingResponseSetDocument: + type: object + properties: + id: + type: string + description: The document id. + metadata: + type: array + items: + $ref: "#/components/schemas/vectaraservingAttribute" + description: Document level metadata. + servingSummarizationRequest: + type: object + example: + max_summarized_results: 10 + response_lang: en + properties: + summarizerPromptName: + type: string + description: The name of the summarizer+prompt combination to use for summarization. + maxSummarizedResults: + type: integer + format: int64 + description: Maximum number of results to summarize. + responseLang: + type: string + description: >- + ISO 639-1 or ISO 639-3 language code for the response, or "auto" to indicate that + + the auto-detected language of the incoming query should be used. + promptText: + type: string + description: >- + Vectara manages both system and user roles and prompts for the generative + + LLM out of the box by default. However, Scale customers can override the + + prompt_text via this variable. The prompt_text is in the form of an + + Apache Velocity template. For more details on how to configure the + + prompt_text, see the long-form documentation at + + https://docs.vectara.com/docs/prompts/vectara-prompt-engine + + See https://vectara.com/pricing/ for more details on becoming a Scale customer. + debug: + type: boolean + description: >- + Debugging the generative prompt is currently a Scale-only feature. + + See https://vectara.com/pricing/ for more details on becoming a Scale customer. + responseChars: + type: integer + format: int64 + description: >- + Controls the length of the summary. + + This is a rough estimate and not a hard limit: the end summary can be longer or shorter + + than this value. This is currently a Scale-only feature. + + See https://vectara.com/pricing/ for more details on becoming a Scale customer. + modelParams: + $ref: "#/components/schemas/SummarizationRequestModelParams" + citationParams: + $ref: "#/components/schemas/servingCitationParams" + chat: + $ref: "#/components/schemas/servingChatRequest" + factualConsistencyScore: + type: boolean + description: If unset or true, the response will include the factual consistency score. + description: How a LLM uses the search results to provide a response to a query. + required: + - maxSummarizedResults + - responseLang + servingSummary: + type: object + properties: + text: + type: string + description: The summary text. + lang: + type: string + description: >- + 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: + $ref: "#/components/schemas/servingChat" + factualConsistency: + $ref: "#/components/schemas/servingFactualConsistency" + done: + type: boolean + description: >- + 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: + type: array + items: + $ref: "#/components/schemas/comvectaraStatus" + description: >- + Statuses are marked β€œrepeated” for consistency and flexibility. A failed + + summary should bubble up into the status code of the entire ResponseSet. + futureId: + type: integer + format: int32 + description: Populated for streaming requests only. + vectaraDeleteDocumentRequest: + type: object + properties: + customerId: + type: string + format: int64 + description: The Customer ID to issue the request for. + corpusId: + type: string + format: int64 + description: The Corpus ID that contains the document. + minimum: 1 + example: 1 + documentId: + type: string + description: The Document ID to be deleted. + description: Request to delete a document from an index. + required: ['customerId', 'corpusId', 'documentId'] + vectaraDeleteDocumentResponse: + type: object + vectaraIndexDocumentRequest: + type: object + properties: + customerId: + type: string + format: int64 + corpusId: + type: string + format: int64 + minimum: 1 + example: 1 + document: + $ref: "#/components/schemas/vectaraindexingDocument" + required: ['customerId', 'corpusId', 'document'] + vectaraIndexDocumentResponse: + type: object + properties: + status: + $ref: "#/components/schemas/comvectaraStatus" + quotaConsumed: + $ref: "#/components/schemas/vectaraStorageQuota" + vectaraStatusCode: + type: string + enum: + - 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: OK + vectaraStorageQuota: + type: object + properties: + numChars: + type: string + format: int64 + description: The number of chars from the document that consumed the storage quota. + numMetadataChars: + type: string + format: int64 + description: >- + The number of chars in the metadata of the document that consumed the + + storage quota. + title: |- + Encapsulates storage quota consumed by indexed documents. + NextId: 3 + vectaraindexingCustomDimension: + type: object + properties: + name: + type: string + description: The name of the dimension. + value: + type: number + format: double + description: The value of the dimension. + description: The value of a custom dimension. A valid list of custom dimensions is defined ahead of time for a corpus. + vectaraindexingDocument: + type: object + properties: + documentId: + type: string + description: Client assigned document ID to this document. + title: + type: string + description: The title of the document. + description: + type: string + description: An optional description for the document. + metadataJson: + type: string + description: "Metadata about the document. This is a string containing a JSON\nobject. It can be an arbitrary object except that any keys \nthat match a metadata filter of the corpus must have the\nsame value type as metadata filter's value type.\n\nA query can use this object to filter if the object's key/value pair\nhas been defined as a metadata filter.\n\nThe whole object will be in the query result." + section: + type: array + items: + $ref: "#/components/schemas/indexingSection" + description: |- + The actual content of the document, structured as a repeating list + of sections. + description: A document to index. + vectaraservingAttribute: + type: object + properties: + name: + type: string + value: + type: string + vectaraservingCustomDimension: + type: object + properties: + name: + type: string + description: The name of the custom dimension. + weight: + type: number + format: double + description: >- + The weight of the custom dimension on the query side. This gets multipled + + by the matching index custom dimension weight and added to the score. + description: Defined the weight of a custom dimension at query time. + vectaraservingResponse: + type: object + properties: + text: + type: string + description: The text of the document part after being modified by the context config. + score: + type: number + format: float + description: The score used for ranking results. The higher the score, the better the match. + metadata: + type: array + items: + $ref: "#/components/schemas/vectaraservingAttribute" + description: Document part level metadata. + documentIndex: + type: integer + format: int64 + description: Use this ID to find the document in the ResponseSet. + corpusKey: + $ref: "#/components/schemas/servingCorpusKey" + description: A document part that matched a query. + indexingCoreDocument: + type: object + properties: + documentId: + type: string + description: A document ID to assign to this document. + metadataJson: + type: string + description: |- + Metadata about the document. This should be a json string. It can be + retrieved at query time. + parts: + type: array + items: + $ref: "#/components/schemas/indexingCoreDocumentPart" + description: All parts of this document. + defaultPartContext: + type: string + description: >- + This field provides a way to specify a blanket context for all parts. If + + the context in a part is empty, this context will be used. + customDims: + type: array + items: + $ref: "#/components/schemas/vectaraindexingCustomDimension" + description: |- + A list of custom dimension values that are included in the generated + representation of all parts. + description: A document to index. + indexingCoreDocumentPart: + type: object + properties: + text: + type: string + description: A part of the document. e.g., a sentence. + context: + type: string + description: Context of the part. + metadataJson: + type: string + description: >- + Metadata about this part of the document. This should be a json string. + + It is passed through the system, without being used at indexing time. It + + can be retrieved at query time. + customDims: + type: array + items: + $ref: "#/components/schemas/vectaraindexingCustomDimension" + title: >- + A list of custom dimension values that are included in the generated + + representation of this part. These are optional and take on the corpus + + default custom dimension value if not explicitly provided for the document + description: Part of a document. A document consists of several such parts. + vectaraIndexCoreDocumentRequest: + type: object + properties: + customerId: + type: string + format: int64 + description: The Customer ID to issue the request for. + corpusId: + type: string + format: int64 + description: The Corpus ID to index the document into. + document: + $ref: "#/components/schemas/indexingCoreDocument" + description: Request to index a document. + vectaraIndexCoreDocumentResponse: + type: object + properties: + status: + $ref: "#/components/schemas/comvectaraStatus" + quotaConsumed: + $ref: "#/components/schemas/vectaraStorageQuota" + securitySchemes: + oAuth: + type: oauth2 + description: OAuth2 access to Vectara + flows: + clientCredentials: + tokenUrl: https://vectara-prod-YOUR_VECTARA_CUSTOMER_ID.auth.us-west-2.amazoncognito.com/oauth2/token + scopes: {} + ApiKeyAuth: + type: apiKey + in: header + name: x-api-key + # defaults + parameters: + customerIdentifier: + in: header + name: customer-id + required: true + description: Enter the Customer ID to use for the request. + schema: + type: integer + timeout: + in: header + name: timeout + required: false + description: (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. + schema: + type: string + default: "30S" +# add oauth and api key security +security: + - oAuth: [] +# add server endpoint +servers: + - url: https://api.vectara.io \ No newline at end of file diff --git a/fern/changelog/2025-05-29.mdx b/fern/changelog/2025-05-29.mdx new file mode 100644 index 000000000..ffd8acd73 --- /dev/null +++ b/fern/changelog/2025-05-29.mdx @@ -0,0 +1,35 @@ +--- +title: "May 29, 2025" +slug: "2025-05-29" +--- + +# May 29, 2025 + +### ✨ New Features +- Released advanced vector similarity scoring with customizable distance metrics (#487) +- Added multi-corpus search capabilities for cross-domain queries (#484) +- Introduced automated document categorization using machine learning (#481) + +### πŸ“š API Changes +- Enhanced Search API with new ranking algorithms and precision controls (#490) +- Added support for custom metadata schemas in Create Corpus endpoint (#486) +- Introduced new Chat History API for conversation management (#483) + +### πŸ“ Documentation Changes +- Added comprehensive guide for implementing custom rerankers (#491) +- Updated Quick Start tutorial with new onboarding flow (#488) +- Enhanced metadata filtering documentation with advanced use cases (#485) + +### πŸ“‹ Example Updates +- Added React hooks examples for seamless frontend integration (#489) +- Updated Node.js SDK samples with async/await patterns (#482) +- Enhanced Go SDK examples with proper error handling (#479) + +### πŸ—‘ Deprecated +- Legacy v1 indexing endpoint will be sunset on August 1, 2025 (#480) +- Old authentication method deprecated in favor of OAuth 2.0 (#477) + +### πŸ›  Documentation Platform Updates +- Improved mobile responsiveness across all documentation pages (#478) +- Added code syntax highlighting for additional programming languages (#476) +- Enhanced search autocomplete with intelligent suggestions (#475) diff --git a/fern/changelog/2025-05-30.mdx b/fern/changelog/2025-05-30.mdx new file mode 100644 index 000000000..9d87b029f --- /dev/null +++ b/fern/changelog/2025-05-30.mdx @@ -0,0 +1,31 @@ +--- +title: "May 30, 2025" +slug: "2025-05-30" +--- + +# May 30, 2025 + +### ✨ New Features +- Introduced enhanced semantic search capabilities with improved multilingual support (#501) +- Added new batch processing APIs for large-scale document ingestion (#498) +- Launched real-time chat streaming with WebSocket support (#495) + +### πŸ“š API Changes +- Updated Query API to support new filtering parameters for enhanced search precision (#503) +- Added pagination support to List Documents endpoint (#500) +- Introduced new authentication headers for improved security (#497) + +### πŸ“ Documentation Changes +- Enhanced API Reference with interactive examples and improved code samples (#504) +- Updated authentication guides with new OAuth 2.0 flow documentation (#502) +- Improved error handling documentation with comprehensive error codes (#499) + +### πŸ“‹ Example Updates +- Added Python SDK examples for the new batch processing workflow (#506) +- Updated JavaScript samples to demonstrate real-time chat integration (#496) +- Enhanced cURL examples with proper authentication headers (#493) + +### πŸ›  Documentation Platform Updates +- Upgraded documentation search functionality with better relevance scoring (#505) +- Added dark mode support across all documentation pages (#494) +- Implemented faster page loading with optimized asset delivery (#492) diff --git a/fern/changelog/overview.mdx b/fern/changelog/overview.mdx new file mode 100644 index 000000000..e4000fb5e --- /dev/null +++ b/fern/changelog/overview.mdx @@ -0,0 +1,41 @@ +--- +title: "Changelog Overview" +slug: "overview" +--- +Welcome to the Vectara API changelog! Here you'll find the latest updates, improvements, and changes to our platform and documentation. + +## What You'll Find Here + +Our changelog is organized by release date and includes the following types of updates: + +### ✨ New Features +Exciting new capabilities and functionality added to the Vectara platform, including new APIs, search enhancements, and platform features. + +### πŸ“š API Changes +Updates to existing APIs, including new endpoints, parameter changes, and improvements to API functionality. + +### πŸ“ Documentation Changes +Improvements to our documentation, including new guides, updated examples, and enhanced explanations of features and concepts. + +### πŸ“‹ Example Updates +Updates to code samples, SDK examples, and tutorial content to help you integrate with Vectara more effectively. + +### πŸ—‘ Deprecated +Information about features, APIs, or functionality that will be removed in future versions, along with migration guidance. + +### πŸ›  Documentation Platform Updates +Improvements to the documentation site itself, including design updates, performance enhancements, and new interactive features. + +## Stay Updated + +- **Follow our releases**: Each changelog entry includes links to relevant pull requests and detailed technical information +- **Migration guides**: When breaking changes occur, we provide comprehensive migration documentation +- **Community feedback**: We welcome feedback on all updates through our community channels + +## Recent Updates + +Check out our most recent changelog entries to see what's new with Vectara! + +--- + +*For technical support or questions about any changes, please reach out through our support channels or community forums.* diff --git a/fern/docs.yml b/fern/docs.yml index ff2f4f56d..497f07cf9 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -2,14 +2,22 @@ instances: - url: https://vectara.docs.buildwithfern.com title: Vectara | Documentation default-language: python -navigation: - - page: Introduction - path: ./pages/introduction.mdx - - api: API Reference - snippets: - python: vectara - typescript: vectara + +experimental: + openapi-parser-v3: true + +layout: + searchbar-placement: header + page-width: full + tabs-placement: header + logo: light: ./assets/logo-light.svg dark: ./assets/logo-dark.svg favicon: ./assets/favicon.jpeg + +versions: + - display-name: v2.0 (Latest) + path: ./versions/v2.yml + - display-name: v1.0 + path: ./versions/v1.yml diff --git a/fern/fern.config.json b/fern/fern.config.json index b9c3c9bb5..7e7734120 100644 --- a/fern/fern.config.json +++ b/fern/fern.config.json @@ -1,4 +1,4 @@ { "organization": "vectara", - "version": "0.57.35" + "version": "0.63.23" } \ No newline at end of file diff --git a/fern/generators.yml b/fern/generators.yml index 7e29046f0..f23eb355e 100644 --- a/fern/generators.yml +++ b/fern/generators.yml @@ -25,6 +25,9 @@ api: env: VECTARA_API_KEY specs: - openapi: ../www/static/vectara-oas-v2.yaml + namespace: V2 + - openapiV1: ../www/static/vectara-oas.yaml + namespace: V1 readme: apiReferenceLink: https://vectara.docs.buildwithfern.com/ defaultEndpoint: POST /v2/query diff --git a/fern/versions/v1.yml b/fern/versions/v1.yml new file mode 100644 index 000000000..85819687a --- /dev/null +++ b/fern/versions/v1.yml @@ -0,0 +1,15 @@ +tabs: + api: + display-name: API Reference + icon: fa-regular fa-code + skip-slug: true + +navigation: + - tab: api + layout: + - api: API Reference + api-name: v2 + - changelog: ../changelog + title: Changelog + slug: v2-changelog + diff --git a/fern/versions/v2.yml b/fern/versions/v2.yml new file mode 100644 index 000000000..f771741b5 --- /dev/null +++ b/fern/versions/v2.yml @@ -0,0 +1,30 @@ +tabs: + home: + display-name: Home + icon: fa-regular fa-home + skip-slug: true + api: + display-name: API Reference + icon: fa-regular fa-code + skip-slug: true + + +navigation: + - tab: home + layout: + - section: Introduction + skip-slug: true + contents: + - page: Introduction + path: ../pages/introduction.mdx + - tab: api + layout: + - api: API Reference + api-name: v2 + snippets: + python: vectara + typescript: vectara + - changelog: ../changelog + title: Changelog + slug: changelog +