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: 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 and document extraction
  - name: Index
    description: Index and manage core and structured documents for efficient search and retrieval
  - name: Corpora
    description: Create, manage, and update corpora and their associated settings for administration purposes
  - 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 and administrative monitoring
  - name: Large Language Models
    description: List LLMs for text summarization, chat, and other generation tasks
  - name: Encoders
    description: List encoders that turn text into vectors such as Boomerang
  - 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: Application Clients
    description: Manage app clients, and perform authentication operations for admin-level access control
  - name: API Keys
    description: Manage API keys for the account

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.
      operationId: createCorpus
      tags:
        - Corpora
      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'
    get:
      summary: List corpora
      description: |
        List corpora in the account. The corpus objects that are returned are less
        detailed than the direct corpus retrieval operation.
      operationId: listCorpora
      tags:
        - Corpora
      parameters:
        - 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: 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'
  /v2/corpora/{corpus_key}:
    get:
      tags:
        - Corpora
      summary: Retrieve metadata about a corpus
      description: Get metadata about a corpus. This operation is not a method of searching a corpus.
      operationId: getCorpus
      parameters:
        - 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'
    delete:
      tags:
        - Corpora
      summary: Delete a corpus and all its data
      description: Delete a corpus and all the data that it contains.
      operationId: deleteCorpus
      parameters:
        - 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'
    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. Update the name and description of a corpus 
        dynamically to help keep your data aligned with changing business needs.
      operationId: updateCorpus
      parameters:
        - 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'
  /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.
      operationId: resetCorpus
      parameters:
        - 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'
  /v2/corpora/{corpus_key}/replace_filter_attributes:
    post:
      tags:
        - Corpora
      summary: Replace the filter attributes of a corpus
      description: |
        Replace the filter attributes of a corpus. This does not happen immediately, but
        instead creates a job and will complete when that job completes. Until that
        job completes, using new filter attributes will not work.

        You can monitor the status of the filter change using the returned job id.
      operationId: replaceFilterAttributes
      parameters:
        - in: path
          name: corpus_key
          description: Key of the corpus to have 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 don't 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'
  /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.
        * 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:
        - 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: Maximum number of results to return.
          required: false
          schema:
            type: integer
            default: 10
            minimum: 1
        - in: query
          name: offset
          description: Position from which to start in the result set.
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
      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'
    post:
      tags:
        - Queries
      summary: Advanced Single Corpus Query
      description: |
        Query a specific corpus and find relevant results, highlight relevant snippets, and use Retrieval Augmented Generation:

        * 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 a RAG-specific LLM like Mockingbird (`mockingbird-1.0-2024-07-16`) 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:
        - 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'
  /v2/query:
    post:
      tags:
        - Queries
      summary: Multiple Corpora Query
      description: |
        Perform a multi-purpose query to retrieve relevant information from one or more corpora and generate a response using Retrieval Augmented Generation (RAG).

        * 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 a RAG-specific LLM like Mockingbird (`mockingbird-1.0-2024-07-16`) 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
      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 was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /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. Vectara will attempt to automatically extract text and any metadata.
        The File Upload endpoint request expects a `multipart/form-data` request containing the following parts:
        * `metadata` - (Optional) Specifies a JSON object representing any additional metadata to be associated with the extracted document. For example, `'metadata={"key": "value"};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:
        - 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
              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
      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 files 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'
  /v2/corpora/{corpus_key}/documents:
    post:
      tags:
        - Index
      summary: Add a document to a corpus
      description: |
        Add a document to a corpus. You can add documents that are either in a typical structured format,
        or in a format that explicitly specifies each document part that becomes a search result.
      operationId: createCorpusDocument
      parameters:
        - 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 creating a file in the corpus.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Corpus not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
    get:
      tags:
        - Documents
      summary: List the documents in the corpus
      operationId: listCorpusDocuments
      parameters:
        - 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 the 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'
  /v2/corpora/{corpus_key}/documents/{document_id}:
    delete:
      tags:
        - Documents
      summary: Delete a document
      operationId: deleteCorpusDocument
      parameters:
        - 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.
            The `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'
    get:
      tags:
        - Documents
      summary: Retrieve a document
      operationId: getCorpusDocument
      parameters:
        - 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.
            The `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'
  /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
      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'
    get:
      tags:
        - Chats
      summary: List chats
      description: Retrieve a list of previous chats in the Vectara account.
      operationId: listChats
      parameters:
        - 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 the 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'
  /v2/llms:
    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:
        - 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 the 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'
  /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:
        - 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 the 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'
  /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:
        - 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'
    delete:
      tags:
        - Chats
      summary: Delete a chat
      description: Delete a chat and any turns it contains permanently.
      operationId: deleteChat
      parameters:
        - 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'
  /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 tha make up the dialog.
      operationId: createChatTurn
      parameters:
        - 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'
    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:
        - 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'
  /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:
        - 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'
    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:
        - 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'
    patch:
      tags:
        - Chats
      summary: Update a turn
      description: Update a turn; used to disable or enable a chat.
      operationId: updateChatTurn
      parameters:
        - 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'
  /v2/encoders:
    get:
      tags:
        - Encoders
      summary: List encoders
      description: Encoders are used to store and retrieve from a corpus. 
      operationId: listEncoders
      parameters:
        - 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 the 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'
  /v2/rerankers:
    get:
      tags:
        - Rerankers
      summary: List rerankers
      description: Rerankers are used to improve the ranking (ordering) of search results.
      operationId: listRerankers
      parameters:
        - 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 the 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'
  /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:
        - 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: Get jobs after a date time.
          required: false
          schema:
            type: string
            format: date-time
        - name: state
          in: query
          description: Indicates the states the jobs can be in.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/JobState'
        - 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: page_key
          in: query
          description: Used to the retrieve the next page of documents 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'
  /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:
        - name: job_id
          in: path
          description: The ID of 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'
  /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
      requestBody:
        content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: The created user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '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'
    get:
      tags:
        - Users
      summary: List users in the account
      description: Lists all users in the account.
      operationId: listUsers
      parameters:
        - 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 the retrieve the next page of users after the limit has been reached. 
          required: false
          schema:
            type: string
      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'
  /v2/users/{username}:
    get:
      tags:
        - Users
      summary: Get a user
      description: |
        Get a user and view details like the email, username, and roles associated with a user.
      operationId: getUser
      parameters:
        - name: username
          in: path
          description: |
            Specifies the User ID that to retrieve.
            Note 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: Corpus not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
    patch:
      tags:
        - Users
      summary: Update a user
      description: Update details about a user such as role names.
      operationId: updateUser
      parameters:
        - name: username
          in: path
          description: |
            Specifies the User ID to update.
            Note 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'
    delete:
      tags:
        - Users
      summary: Delete a user
      description: Delete a user from the account.
      operationId: deleteUser
      parameters:
        - name: username
          in: path
          description: |
            Specifies the username to delete.
            Note 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'
  /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:
        - name: username
          in: path
          description: |
            Specifies the username to update.
            Note the username must be percent encoded and URI safe.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: User was sent the password reset email.
        '403':
          description: Permissions do not allow resting the user password.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /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
      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'
    get:
      tags:
        - API Keys
      summary: List API keys
      operationId: listApiKeys
      parameters:
        - 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 the retrieve the next page of API keys after the limit has been reached. 
          required: false
          schema:
            type: string
      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'
  /v2/api_keys/{api_key_id}:
    get:
      tags:
        - API Keys
      summary: Get an API key
      operationId: getApiKey
      parameters:
        - name: api_key_id
          in: path
          description: The name 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 keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    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:
        - name: api_key_id
          in: path
          description: The name 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 keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    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:
        - name: api_key_id
          in: path
          description: The name 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 keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /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
      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'
    get:
      tags:
        - Application Clients
      summary: List App Clients
      operationId: listAppClient
      parameters:
        - 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: 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'
  /v2/app_clients/{app_client_id}:
    get:
      tags:
        - Application Clients
      summary: Get an App Client
      operationId: getAppClient
      parameters:
        - name: app_client_id
          in: path
          description: The name 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 Clients.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
        - Application Clients
      summary: Update an App Client
      operationId: updateAppClient
      parameters:
        - 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 getting this App Clients.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - Application Clients
      summary: Delete an App Client
      operationId: deleteAppClient
      parameters:
        - name: app_client_id
          in: path
          description: The name 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 Clients.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreateCorpusRequest:
      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 for the corpus.
          type: string
          example: Documents with important information for my prompt.
        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.
          type: string
          example: boomerang
        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 deboosting) document parts for arbitrary reasons.
            This feature is only enabled for Scale 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 for the corpus.
    ReplaceFilterAttributesRequest:
      type: object
      properties:
        filter_attributes:
          description: The new filter attributes.
          type: array
          items:
            $ref: '#/components/schemas/FilterAttribute'
      required:
        - filter_attributes
    ReplaceFilterAttributesResponse:
      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:
      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 amd 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.
          type: string
          example: boomerang
        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_bytes:
              description: |
                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: 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: 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
        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:
      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 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:
      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 before the matching document part that are shown.
            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,
            so as 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 after the matching document part that are shown. 
            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,
            so as 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 before the matching document part that are shown.
            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 after the matching document part that are shown. 
            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: '<em>'
        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: '</em>'
    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 then sent to the LLM.
              * The LLM used.
              * `model_parameter`s such as temperature.
             
            All of these properties except the model can be overriden by setting them in this
            object. Even when a `prompt_template` is set, the `generation_preset_name` is used to set 
            the model used.

            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, Scale customers 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).
            See [pricing](https://vectara.com/pricing/) for more details on becoming a Scale customer.
          type: string
          example: |
            [
              {"role": "system", "content": "You are a helpful search assistant."},
              #foreach ($qResult in $vectaraQueryResults)
                 {"role": "user", "content": "Given the $vectaraIdxWord[$foreach.index] search result."},
                 {"role": "assistant", "content": "${qResult.getText()}" },
              #end
              {"role": "user", "content": "Generate a summary for the query '${vectaraQuery}' based on the above results."}
            ]
        prompt_text:
          description: |
            This is property is deprecated in favor clearer naming. Use `prompt_template`. This property will be
            ignored if `prompt_template` is set.
          type: string
          example: |
            [
              {"role": "system", "content": "You are a helpful search assistant."},
              #foreach ($qResult in $vectaraQueryResults)
                 {"role": "user", "content": "Given the $vectaraIdxWord[$foreach.index] search result."},
                 {"role": "assistant", "content": "${qResult.getText()}" },
              #end
              {"role": "user", "content": "Generate a summary for the query '${vectaraQuery}' based on the above results."}
            ]
          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.

            So, this value This is currently a Scale-only feature.
            See [pricing](https://vectara.com/pricing/) for more details on becoming a Scale customer.
          type: integer
          format: int32
          example: 300
          minimum: 0
        response_language:
          $ref: '#/components/schemas/Language'
        model_parameters:
          title: ModelParameters
          description: |
            The parameters for the model.  These are currently a Scale-only feature.
            See [pricing](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.
          type: object
          properties:
            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 url like `<a href="url_pattern">text_pattern</a>`.
            * `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](<url_pattern>)` for markdown.

            You can use metadata attributes in the `text_pattern`. For example,
            the pattern `{doc.title}` with citation style `markdown` would result
            in final citation output like `[Title](<url_pattern>)` when
            the document's metadata includes `{"title":"Title"}`.
          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
      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:
      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
      required:
        - query
    SearchCorpus:
      type: object
      properties:
        custom_dimensions:
          $ref: '#/components/schemas/CustomDimensions'
        metadata_filter:
          description: |
            The filter string to narrow the search to according to metadata attributes. The query against this
            corpus will be confined to document parts that match the `metadata_filter`. Only metadata
            set as `filter_attributes` on the corpus can be filtered. Filter syntax is similiar 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: .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:
      allOf:
        - $ref: '#/components/schemas/SearchCorpus'
        - type: object
          properties:
            corpus_key:
              $ref: '#/components/schemas/CorpusKey'
      required:
        - corpus_key
    SearchReranker:
      type: object
      description: |
        Rerank results of the search. Rerankers are very powerful tools to better order 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 type is 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. Current reranker that may be used by Scale customers 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
      x-vectaraParents:
        - SearchReranker
    UserFunctionReranker:
      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')"
      x-vectaraParents:
        - SearchReranker
    MMRReranker:
      type: object
      properties:
        type:
          description: |
            When the type is `mmr`, you can specify the `diversity_bias`, and the
            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: .3
      x-vectaraParents:
        - SearchReranker
    ChainReranker:
      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 search results consecutively after each other.
          items:
            $ref: '#/components/schemas/SearchReranker' 
          minItems: 2
      required:
        - rerankers
      x-vectaraParents:
        - SearchReranker
    NoneReranker:
      type: object
      properties:
        type:
          description: |
            When the type is `none`, no reranking will be done.
          type: string
          default: none
      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: |
            The probability that the summary is factually consistent with the results.
          type: number
          format: float
        rendered_prompt:
          description: |
            The rendered prompt sent to the LLM. Useful when creating customer `prompt_text` templates. Only available
            to Scale customers.
          type: string
    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
        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
    QueryStreamedResponse:
      description: An individual event sent with 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'
      x-vectaraParents:
        - QueryStreamedResponse
        - ChatStreamedResponse
    StreamGenerationChunk:
      description: The chunk response from the generation, possibly 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
    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_text` templates. Only available
            to Scale customers.
          type: string
        rephrased_query:
          description: |
            If you are on the Scale plan, you can view the actual query made to backend that was rephrased 
            by the LLM from the input query.
          type: string
      x-vectaraParents:
        - QueryStreamedResponse
        - ChatStreamedResponse
    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
    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
    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
    UploadFileRequest:
      type: object
      properties:
        metadata:
          description: Arbitrary object that will be attached as document metadata to the extracted document.
          type: object
          additionalProperties: true
        file:
          description: Binary file contents. The file name of the file will be used as the document ID.
          type: string
          format: binary
      required:
        - file
    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 it's proprietary strategy to create document parts.

        Otherwise, you can create a document with all the document parts explicitly specified.

        A document part is the a 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
    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 and is 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'
      required:
        - id
        - type
        - sections
      x-vectaraParents:
        - CreateDocumentRequest
    StructuredDocumentSection:
      description: A logical section within a structured document.
      type: object
      properties:
        id:
          description: The section ID. Gets converted to a metadata field.
          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
        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 retrieval search results.
          default: core
          type: string
        metadata:
          description: |
            Arbitrary object of document level metadata. Properties of this object
            can be used by document filter if defined as a corpus filter attribute.
          type: object
          properties: {}
          additionalProperties: true
          example: {"title":"A Nice Document", "lang":"eng"}
        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. Attributes matching corpus document part filter attributes are used as document part filter attributes.
          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 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. Attributes matching corpus document part filter attributes are used as document part filter attributes.
          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
    CustomDimensions:
      description: The custom dimensions as additional weights.
      type: object
      additionalProperties:
        type: number
        format: double
    Document:
      type: object
      properties:
        id:
          description: The Document ID.
          type: string
          example: my-doc-id
        metadata:
          description: The document metadata.
          type: object
          additionalProperties: true
        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'
    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 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 document metadata.
          type: integer
          format: int64
          minimum: 0
    ListDocumentsResponse:
      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
    ListLLMsResponse:
      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 overriden 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.
          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 to 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 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
        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:
      type: object
      properties:
        generation_presets:
          description: List of generation presets.
          type: array
          items:
            $ref: '#/components/schemas/GenerationPreset'
        metadata:
          $ref: '#/components/schemas/ListMetadata'
    ChatRequest:
      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'
        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 message and response message.
          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: |
            The probability that the summary is factually consistent with the results.
          type: number
          format: float
        rendered_prompt:
          description: |
            The rendered prompt sent to the LLM. Useful when creating customer `prompt_text` templates. Only available
            to Scale customers.
          type: string
        rephrased_query:
          description: |
            If you are on the Scale plan, you can view the actual query made to backend that was rephrased 
            by the LLM from the input query.
          type: string
    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:
      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:
      type: object
      properties:
        chats:
          description: List of chats.
          type: array
          items:
            $ref: '#/components/schemas/Chat'
        metadata:
          $ref: '#/components/schemas/ListMetadata'
    Turn:
      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 a 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 futures turns of the chat.
          type: boolean
          example: true
        created_at:
          description: Specifies when the turn was created.
          type: string
          format: date-time
    ListChatTurnsResponse:
      type: object
      properties:
        turns:
          description: List of turns.
          type: array
          items:
            $ref: '#/components/schemas/Turn'
    UpdateTurnRequest:
      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:
      type: object
      properties:
        encoders:
          type: array
          items:
            $ref: '#/components/schemas/Encoder'
        metadata:
          $ref: '#/components/schemas/ListMetadata'
    CreateApiKeyRequest:
      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:
      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. 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:
      type: object
      properties:
        enabled:
          description: Indicates whether to disable or enable an API key.
          type: boolean
    ListApiKeysResponse:
      type: object
      properties:
        api_keys:
          description: List of API keys.
          type: array
          items:
            $ref: '#/components/schemas/ApiKey'
        metadata:
          $ref: '#/components/schemas/ListMetadata'
    CreateAppClientRequest:
      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:
      type: object
      properties:
        id:
          description: |
            The Vectara App Client ID. This ID is not used during an OAuth
            flow but 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 key used in API requests. 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:
      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:
      type: object
      properties:
        app_clients:
          description: List of App Clients.
          type: array
          items:
            $ref: '#/components/schemas/AppClient'
        metadata:
          $ref: '#/components/schemas/ListMetadata'
    Encoder:
      type: object
      properties:
        id:
          description: The Encoder ID.
          type: string
          pattern: 'enc_[0-9]+$'
          example: enc_1
        name:
          description: The encoder name.
          type: string
          example: boomerang
        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 the quality of
            the embedding.
          type: integer
          format: int32
          example: 768
        description:
          description: The encoder description.
          type: string
        default:
          description: Indicates whether the encoder is default 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:
      type: object
      properties:
        rerankers:
          description: An array of rerankers.
          type: array
          items:
            $ref: '#/components/schemas/Reranker'
        metadata:
          $ref: '#/components/schemas/ListMetadata'
    Job:
      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
    JobState:
      type: string
      enum:
        - unknown
        - queued
        - started
        - completed
        - failed
        - failed_will_retry
        - aborted
    ListJobsResponse:
      type: object
      properties:
        jobs:
          description: An array of jobs.
          type: array
          items:
            $ref: '#/components/schemas/Job'
        metadata:
          $ref: '#/components/schemas/ListMetadata'
    CreateUserRequest:
      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 for the user.
          type: string
        api_roles:
          description: The role names assigned to the user.
          type: array
          items:
            $ref: '#/components/schemas/ApiRole'
      required:
        - email
    UpdateUserRequest:
      type: object
      properties:
        enabled:
          description: Indicates whether to disable or disable the user.
          type: boolean
        api_roles:
          description: The new role names of the user.
          type: array
          items:
            $ref: '#/components/schemas/ApiRole'
    User:
      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 for 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:
      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
    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
    NotFoundError:
      type: object
      properties:
        id:
          description: The ID cannot found.
          type: string
        messages:
          type: array
          items:
            title: message
            type: string
        request_id:
          description: ID of the request that can be used to help Vectara support debug what went wrong.
          type: string
    BadRequestError:
      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:
      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
  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
security:
  - ApiKeyAuth: []
  - OAuth2: []