openapi: 3.0.0
info:
  title: Vectara REST API
  version: 1.0.0
  termsOfService: https://vectara.com/legal/online-customer-agreement/
  x-logo:
    url: https://docs.vectara.com/img/vectara_wordmark.png
    altText: Vectara
  x-dark-logo:
    url: https://docs.vectara.com/img/vectara_wordmark_light.png
    altText: Vectara
  contact:
    name: Vectara Support
    email: support@vectara.com
    url: http://support.vectara.com/
  description: "Vectara provides an end-to-end platform for creating GenAI products using \na simple to use API.\n\nYou can [sign up for an account](https://console.vectara.com/signup) and \nthen view several [API Recipes](https://docs.vectara.com/docs/api-recipes) with example queries \nand parameter values.\n\nThe Vectara API Playground lets you experiment with REST endpoints from \nyour browser. Select an endpoint to view its definition, including the \nrequired or optional headers, body, responses, and sample commands. On the \nright side of each endpoint page, you manually \nenter your API Key or OAuth Bearer Token, `customer_id`, and then any \nrequired body parameters like the `corpusID` before sending the API \nrequest.\n\n:::note\n\nVectara has three kinds of API keys: the Personal API Key, Index API Keys, \nand Query API Keys. The Personal API Key enables administrative tasks \nincluding creating, deleting, and listing corpora, and managing Index and \nQuery API keys for accessible corpora, reading usage data, updating \ncorpora filters, executing queries, and indexing. Query API Keys are used\nfor read-only querying operations, while Index API Keys provide read and \nwrite access. The OAuth operations authenticate with a Bearer Token via the\nOAuth 2.0 client credentials grant. Review the [**OAuth 2.0 section**](https://docs.vectara.com/docs/learn/authentication/oauth-2) about \nhow to generate the token."
tags:
  - name: AdminService
    description: Administrative operations, such as creating or deleting corpora
  - name: IndexService
    description: Indexing operations, such as creating and deleting documents
  - name: QueryService
    description: Query operations, such as performing a search and retrieval augmented generation
  - name: DocumentService
    description: Document operations, listing documents in a corpus
  - name: ChatService
    description: Chat operations, such as listing and reading conversations
# add file upload API and auth options for other APIs
paths:
  /v1/compute-account-size:
    post:
      operationId: ComputeAccountSize
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminComputeAccountSizeResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminComputeAccountSizeRequest"
        description: >-
          Please note that this is an expensive operation, and the requests can be throttled

          by the platform.
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Computes the amount of quota consumed across the entire Vectara account.

        Some tips for this API:
        * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/compute-corpus-size:
    post:
      operationId: ComputeCorpusSize
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminComputeCorpusSizeResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminComputeCorpusSizeRequest"
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: "Computes the amount of quota consumed by a corpus. This capability is useful for administrators to track and monitor the amount \nof usage for specific corpora.\n\nSome tips for this API:\n* This operation works with the Personal API Key and OAuth 2.0 (in a JWT \"Bearer Token\") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).\n* The `filter` feature applies to either the name *or* the description of a corpus.\n"
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/create-api-key:
    post:
      operationId: CreateApiKey
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminCreateApiKeyResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminCreateApiKeyRequest"
        description: |-
          This request can be used to create one or more ApiKeys.
          Every ApiKey is bound to one or more corpora.
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Creates an API key that you bind with a specific corpus or multiple corpora. You can create an API key that only gives access to query data (read-only) or an API key that gives access to both querying and serving (read-write).

        Some tips for this API:
        * This operation only works with OAuth 2.0 (in a JWT "Bearer Token") authentication. It does not work with API Keys. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).
      security:
        - oAuth: []
  /v1/create-corpus:
    post:
      operationId: CreateCorpus
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminCreateCorpusResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminCreateCorpusRequest"
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Creates a corpus, which is a container to store data in.

        Some tips for this API:
        * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).
        * The `name` of the corpus is the only required field.
        * Filter attributes tell Vectara which metadata fields you'd like to run SQL-style filters against.  If you need to change them after you've created the corpus, see the [Replace Filter Attributes API](https://docs.vectara.com/docs/rest-api/replace-corpus-filter-attrs)
        * `textless` and `customDimensions` are features that are only available to [Scale](https://vectara.com/pricing/) accounts.
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/delete-api-key:
    post:
      operationId: DeleteApiKey
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminDeleteApiKeyResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminDeleteApiKeyRequest"
              type: object
              properties:
                keyIds:
                  type: array
                  items:
                    type: string
            examples:
              DeleteSingleKey:
                value:
                  keyIds:
                    - "ID of API Key"
              DeleteMultipleKeys:
                value:
                  keyIds:
                    - "ID of Key 1"
                    - "ID of Key 2"
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: "Deletes API keys to help you manage the security and lifecycle of API keys in your application.  \nSome tips for this API:\n* This operation only works with OAuth 2.0 (in a JWT \"Bearer Token\") authentication. It does not work with API Keys. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).\n"
      security:
        - oAuth: []
  /v1/delete-conversations:
    post:
      operationId: DeleteConversations
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/chatDeleteConversationsResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/chatDeleteConversationsRequest"
        required: true
      tags:
        - ChatService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: "Delete conversations from the chat history corpus. This is useful for data management to help ensure that you maintain data hygiene and support compliance with data retention policies.        \n\nSome tips for this API:\n* This operation authenticates with either an API Key or OAuth 2.0 (in a JWT \"Bearer Token\"). You can find details of how to set up an API key or use OAuth 2.0 [here](https://docs.vectara.com/docs/console-ui/manage-api-access).\n"
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/delete-corpus:
    post:
      operationId: DeleteCorpus
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminDeleteCorpusResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminDeleteCorpusRequest"
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Deletes a corpus and all of the data contained inside of the corpus.

        Some tips for this API:
        * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).
        * It can take a few seconds to completely delete the corpus if there's heavy system load.  Be patient if the corpus is still present after a deletion request is initiated.
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/delete-doc:
    post:
      operationId: Delete
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/vectaraDeleteDocumentResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/vectaraDeleteDocumentRequest"
        description: Request to delete a document from an index.
        required: true
      tags:
        - IndexService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Delete documents from a corpus.

        Some tips for this API:
        * This operation authenticates with either the Personal API Key, Index API Key, or OAuth 2.0 (in a JWT "Bearer Token"). You can find details of how to set up an API key or use OAuth 2.0 [here](https://docs.vectara.com/docs/console-ui/manage-api-access).
        * You can quickly delete all documents from a corpus to clear it out by using the [Reset Corpus](https://docs.vectara.com/docs/rest-api/reset-corpus) operation.
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/delete-turns:
    post:
      operationId: DeleteTurns
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/chatDeleteTurnsResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/chatDeleteTurnsRequest"
        required: true
      tags:
        - ChatService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: "Deletes specific turns from a conversation within the chat history corpus. This enables developers to remove inaccurate or inappropriate responses from the conversation history.        \n\nSome tips for this API:\n* This operation authenticates with either an API Key or OAuth 2.0 (in a JWT \"Bearer Token\"). You can find details of how to set up an API key or use OAuth 2.0 [here](https://docs.vectara.com/docs/console-ui/manage-api-access).\n"
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/disable-turns:
    post:
      operationId: DisableTurns
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/chatDisableTurnsResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/chatDisableTurnsRequest"
        required: true
      tags:
        - ChatService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: "Disables specific turns from a conversation within the chat history corpus. This is useful for excluding specific turns from a conversation.        \n\nSome tips for this API:\n* This operation authenticates with either an API Key or OAuth 2.0 (in a JWT \"Bearer Token\"). You can find details of how to set up an API key or use OAuth 2.0 [here](https://docs.vectara.com/docs/console-ui/manage-api-access).\n"
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/enable-api-key:
    post:
      operationId: EnableApiKey
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminEnableApiKeyResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminEnableApiKeyRequest"
            examples:
              EnableAPIKey:
                value:
                  keyEnablement:
                    - keyId: "ID of the API Key"
                      enable: true
              DisableAPIKey:
                value:
                  keyEnablement:
                    - keyId: "ID of the API Key"
                      enable: false
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: "Enables or disables a specific API key.\n \nSome tips for this API:\n* This operation works with the Personal API Key and OAuth 2.0 (in a JWT \"Bearer Token\") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).\n"
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/get-usage-metrics:
    post:
      operationId: GetUsageMetrics
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminUsageMetricsResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminUsageMetricsRequest"
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Displays usage information about indexing and query operations in a corpus. This helps administrators in analyzing and managing resource consumption more efficiently for specific corpora.

        Some tips for this API:
        * Use these metrics to determine usage patterns that enable you to optimize resource allocations.
        * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).
        * The `filter` feature applies to either the name *or* the description of a corpus.
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/index:
    post:
      operationId: Index
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/vectaraIndexDocumentResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/vectaraIndexDocumentRequest"
            examples:
              BookExample:
                value:
                  customerId: 123456
                  corpusId: 1
                  document:
                    documentId: "isbn-9781405053976"
                    title: "The Hitchhiker's Guide to the Galaxy"
                    description: "A great book with the answer to life, the universe, and everything"
                    metadataJson: '{"author": "Douglas Adams"}'
                    section:
                      - title: Intro
                        text: "Far out in the uncharted backwaters of the unfashionable end of the western spiral arm of the Galaxy lies a small unregarded yellow sun."
                        metadataJson: '{"page": 1}'
                      - title: The answer
                        text: "The Answer to the Great Question ... Of Life, the Universe and Everything ... Is ... Forty-two."
                        metadataJson: '{"speaker": "Deep Thought"}'
              GrowthExample:
                value:
                  customerId: 890123
                  corpusId: 8
                  document:
                    documentId: "literature-1234-5678-analysis-expanded"
                    title: "Exploring the Depths of 'Moby Dick': An Expanded Analysis"
                    description: "An expanded in-depth analysis of the characters, themes, narrative structure, and historical context within Herman Melville's 'Moby Dick'."
                    metadataJson: '{"author": "Leslie Thompson", "genre": "Classic Literature", "publishedYear": "1851"}'
                    section:
                      - title: Character Analysis
                        text: "A detailed look at the development of key characters, exploring their symbolic meanings within the narrative."
                        metadataJson: '{"section": "characterAnalysis"}'
                      - title: Thematic Exploration
                        text: "Examination of major themes, including the struggle against fate and the exploration of good vs. evil."
                        metadataJson: '{"section": "thematicExploration"}'
                      - title: Narrative Structure
                        text: "Analysis of Melville's innovative narrative structure, including the use of multiple narrators and non-linear storytelling."
                        metadataJson: '{"section": "narrativeStructure"}'
                      - title: Historical Context
                        text: "A look at the historical backdrop of 'Moby Dick', including its reflection of contemporary social issues and the whaling industry."
                        metadataJson: '{"section": "historicalContext"}'
              ScaleExample:
                value:
                  customerId: 901234
                  corpusId: 9
                  document:
                    documentId: "home-improvement-8765-4321-review-expanded"
                    title: "Ultimate Guide to Power Tools: Expanded Edition"
                    description: "An expanded comprehensive review of the latest drills, saws, safety equipment, and innovative tools available at Home Depot."
                    metadataJson: '{"author": "Derek Lee", "category": "Power Tools", "store": "Home Depot"}'
                    customDims:
                      - name: "Rating"
                        value: 4.5
                      - name: "Affordability"
                        value: 3.5
                  section:
                    - title: Drill Reviews
                      text: "Deep dive into the best drills, comparing models based on power, battery life, and ease of use."
                      metadataJson: '{"section": "drillReviews"}'
                      customDims:
                        - name: "PowerRating"
                          value: 5
                    - title: Saw Reviews
                      text: "Evaluation of top saws for precision cutting, highlighting key features for woodworkers."
                      metadataJson: '{"section": "sawReviews"}'
                      customDims:
                        - name: "Durability"
                          value: 4.5
                    - title: Safety Equipment
                      text: "Reviews of essential safety equipment for using power tools, including goggles, gloves, and ear protection."
                      metadataJson: '{"section": "safetyEquipment"}'
                      customDims:
                        - name: "SafetyRating"
                          value: 5
                    - title: Innovative Tools
                      text: "Spotlight on innovative tools that are changing the game in home improvement, from smart drills to laser-guided saws."
                      metadataJson: '{"section": "innovativeTools"}'
                      customDims:
                        - name: "InnovationScore"
                          value: 4.8
              ReviewExample:
                value:
                  customerId: 234567
                  corpusId: 2
                  document:
                    documentId: "review-f876-1937-90d6-a7e9"
                    title: "The Fusion Mug: The Hottest Way to Burn Your Mouth and Your Wallet"
                    description: "Have you ever wanted to combine the pleasure of drinking coffee with the thrill of nuclear fusion? Look no further than the Fusion Mug!"
                    metadataJson: '{"author": "George P Burdell"}'
                    section:
                      - title: Intro
                        text: "This revolutionary mug promises to keep your coffee piping hot for millennia, thanks to its built-in fusion reactor. Yes, you read that right - a real, honest-to-goodness fusion reactor! What could possibly go wrong?"
                        metadataJson: '{"section": "intro"}'
                      - title: Main Benefit
                        text: "Let me tell you, folks, this mug is a game-changer. The fusion reactor heats up your coffee to the perfect temperature in seconds, without any of that annoying waiting around for your drip pot to do its thing. And the taste? Oh, man. It's like the coffee beans themselves were infused with pure energy from the heart of the sun. I've never tasted anything like it."
                        metadataJson: '{"section": "benefit1"}'
                      - title: Counterpoint
                        text: "Now, I know what you're thinking... 'But George, isn't nuclear fusion dangerous? Won't it give me cancer or something?' Ha! That's just the kind of paranoia that keeps people from truly experiencing life. Sure, there might be some minor risks involved, but come on. What's a little radiation poisoning compared to the pure, unadulterated joy of a perfect cup of coffee?"
                        metadataJson: '{"section": "counterpoint"}'
                      - title: Conclusion
                        text: "In conclusion, if you're not using the Fusion-Powered Perfection mug to drink your coffee, you might as well be drinking mud. This mug is the ultimate in technological sophistication and gourmet taste. It will make your coffee so good that you'll never want to drink anything else again. And if you're worried about the so-called 'risks' of using a fusion reactor to heat your beverage, well, maybe you're just not cut out for the high-stakes world of elite coffee connoisseurship. So go ahead and stick with your bland, boring, non-nuclear coffee mugs. We'll be over here, sipping the sweet nectar of the gods from our Fusion-Powered Perfection mugs."
                        metadataJson: '{"section": "conclusion"}'
        required: true
      tags:
        - IndexService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        This is the "standard" Indexing API for indexing semi-structured, text-heavy "documents."  Indexing data into Vectara is typically very fast: within a few seconds.

        Some tips for this API:
        * This operation authenticates with either the Personal API Key, Index API Key, or OAuth 2.0 (in a JWT "Bearer Token"). You can find details of how to set up an API key or use OAuth 2.0 [here](https://docs.vectara.com/docs/console-ui/manage-api-access).
        * Vectara does require a special format for JSON objects you'd like to index.  Some tips on how to model data in the indexing API, see the documentation [here](https://docs.vectara.com/docs/learn/document-data-structuring).
        * The `metadataJson` object needs the JSON to be escaped so that it's not confused with other parts of the request JSON.
        * [Custom dimensions](https://docs.vectara.com/docs/learn/semantic-search/add-custom-dimensions) (`customDims`) is a feature that is only available to [Scale](https://vectara.com/pricing/) accounts.
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/list-api-keys:
    post:
      operationId: ListApiKeys
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminListApiKeysResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminListApiKeysRequest"
              type: object
              properties:
                numResults:
                  type: integer
                apiKeyType:
                  type: array
                  items:
                    type: string
                readCorporaInfo:
                  type: boolean
            examples:
              PersonalKey:
                value:
                  numResults: 5
                  apiKeyType:
                    - "API_KEY_TYPE__PERSONAL"
                  readCorporaInfo: true
              QueryKey:
                value:
                  numResults: 5
                  apiKeyType:
                    - "API_KEY_TYPE__SERVING"
                  readCorporaInfo: true
              IndexandQueryKey:
                value:
                  numResults: 5
                  apiKeyType:
                    - "API_KEY_TYPE__SERVING_INDEXING"
                  readCorporaInfo: true
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Lists the API keys and the associated corpora names and IDs.

        Some tips for this API:
        * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).
        * The `filter` feature applies to either the name *or* the description of a corpus.
      security:
        - ApiKeyAuth: []
        - oAuth: []
  # add chat endpoints
  /v1/list-conversations:
    post:
      operationId: ListConversations
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/chatListConversationsResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/chatListConversationsRequest"
        required: true
      tags:
        - ChatService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        List all the conversations in a specific corpus. This data enables developers to monitor chatbot interactions and understand how users engage with the data. Pagination lets developers navigate through large datasets.

        Some tips for this API:
        * This operation authenticates with either an API Key or OAuth 2.0 (in a JWT "Bearer Token"). You can find details of how to set up an API key or use OAuth 2.0 [here](https://docs.vectara.com/docs/console-ui/manage-api-access).
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/list-corpora:
    post:
      operationId: ListCorpora
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminListCorporaResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminListCorporaRequest"
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Lists all corpora accessible to the OAuth client.

        Some tips for this API:
        * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).
        * The `filter` feature applies to either the name *or* the description of a corpus.
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/list-documents:
    post:
      operationId: ListDocuments
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/listsListDocumentsResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/listsListDocumentsRequest"
        description: Request to list documents in a corpus.
        required: true
      tags:
        - DocumentService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Lists information about each document ingested into the corpus including the Document ID and metadata. This is useful for managing the lifecycle of documents and a quick way to check which documents are already in the index.

        Some tips for this API:
        * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/list-jobs:
    post:
      operationId: ListJobs
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminListJobsResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminListJobsRequest"
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        List the jobs associated with this account.  Jobs are background processes like [replacing the filterable metadata attributes](https://docs.vectara.com/docs/rest-api/replace-corpus-filter-attrs).

        Some tips for this API:
        * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).
        * It's best practice to filter as much as possible (by date, by status, and/or by job ID) to make job lists as easy to interpret as possible, as there can be many for a given time window.
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/list-users:
    post:
      operationId: ListUsers
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminListUsersResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminListUsersRequest"
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: "Lists the users in your account along with their corpus access and customer-level authorizations. \nSome tips for this API:\n* This operation only works with OAuth 2.0 (in a JWT \"Bearer Token\") authentication. It does not work with API Keys. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).\n* Use this API to view the members on your team. If you need to manage their access, use the Manage User endpoint.\n"
      security:
        - oAuth: []
  /v1/manage-user:
    post:
      operationId: ManageUser
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminManageUserResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminManageUserRequest"
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Lets you manage users in your account by adding, deleting, enabling, or disabling users. You can also reset their passwords and edit user roles. This endpoint can help you streamline your onboarding process by programmatically adding new users, assigning appropriate roles, and setting up permissions.
        Some tips for this API:
        * This operation only works with OAuth 2.0 (in a JWT "Bearer Token") authentication. It does not work with API Keys. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).
        * Add multiple users by including additional “user” objects into the userAction array.
      security:
        - oAuth: []
  /v1/query:
    post:
      operationId: Query
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/servingBatchQueryResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        $ref: "#/components/requestBodies/servingBatchQueryRequest"
        content:
          application/json:
            examples:
              GrowthExample:
                value:
                  query:
                    - query: "What are they latest trends in renewable energy?"
                      start: 0
                      numResults: 5
                      contextConfig:
                        charsBefore: 20
                        charsAfter: 20
                        startTag: "<b>"
                        endTag: "</b>"
                      corpusKey:
                        - corpusId: 2
                          lexicalInterpolationConfig:
                            lambda: 0.5
                      summary:
                        - maxSummarizedResults: 3
                          responseLang: "en"
                          factualConsistencyScore: true
              ScaleExample:
                value:
                  query:
                    - query: "What are they latest trends in renewable energy?"
                      start: 0
                      numResults: 10
                      contextConfig:
                        sentencesBefore: 3
                        sentencesAfter: 3
                        startTag: "<b>"
                        endTag: "</b>"
                      corpusKey:
                        - corpusId: 3
                          semantics: "DEFAULT"
                          dim:
                            - name: "relevance"
                              weight: 1.5
                          metadataFilter: "sector = 'energy'"
                          lexicalInterpolationConfig:
                            lambda: 0.7
                      rerankingConfig:
                        rerankerId: 272725718
                        mmrConfig:
                          diversityBias: 0.4
                      summary:
                        - summarizerPromptName: "vectara-summary-ext-v1.3.0"
                          maxSummarizedResults: 3
                          responseLang: "en"
                          promptText: |
                            [
                              {"role": "system", "content": "You are an expert in summarizing the latest trends in renewable energy. Your summaries are insightful, concise, and highlight key innovations and challenges."},
                              #foreach ($result in $vectaraQueryResults)
                                {"role": "user", "content": "What are the key points in result number $vectaraIdxWord[$foreach.index] about renewable energy trends?"},
                                {"role": "assistant", "content": "In result number $vectaraIdxWord[$foreach.index], the key points are: ${result.getText()}"},
                              #end
                              {"role": "user", "content": "Can you generate a comprehensive summary on 'renewable energy trends' incorporating all the key points discussed?"}
                            ]
                          responseChars: 500
                          modelParams:
                            maxTokens: 1024
                            temperature: 0.6
                            frequencyPenalty: 0.2
                            presencePenalty: 0.1
                          factualConsistencyScore: true
              ChatExample:
                value:
                  query:
                    - query: "What is renewable energy?"
                      queryContext: ""
                      start: 0
                      numResults: 10
                      contextConfig:
                        charsBefore: 0
                        charsAfter: 0
                        startTag: "%START_SNIPPET%"
                        endTag: "%END_SNIPPET%"
                      corpusKey:
                        - corpusId: 12
                          semantics: 0
                          metadataFilter: ""
                      summary:
                        - chat:
                            store: true
                            conversationId: "1d8f0258-3358-475a-b5eb-02a775cee09e"
                          maxSummarizedResults: 5
                          responseLang: "eng"
            schema:
              $ref: '#/components/schemas/servingBatchQueryRequest'
      tags:
        - QueryService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Search for relevant results, highlight relevant snippets, and do
        [Retrieval Augmented Generation](https://docs.vectara.com/docs/learn/grounded-generation/grounded-generation-overview) (RAG).

        Some tips for this API:
        * This operation authenticates with either an API Key or OAuth 2.0 (in a JWT "Bearer Token"). You can find details of how to set up an API key or use OAuth 2.0 [here](https://docs.vectara.com/docs/console-ui/manage-api-access).
        * By default, Vectara only uses its neural/semantic retrieval model, and does not attempt to use keyword matching.  To enable hybrid search with a mix of both keyword and neural results, edit the `lambda` value.  Additional documentation on hybrid search is [here](https://docs.vectara.com/docs/learn/semantic-search/hybrid-search).
        * Vectara can automatically provide a generative summary with the query results for Retrieval Augmented Generation (RAG).  Additional details on RAG in Vectara can be found [here](https://docs.vectara.com/docs/learn/grounded-generation/grounded-generation-overview).
        * The Query API takes an *array* of queries, since you can have Vectara perform more than 1 query in a single API call.  The results that are returned are thus in an array as well, with each element in the response array corresponding to the input query array.
        * Custom dimensions (the `dim` array) is a feature that is only available to [Scale](https://vectara.com/pricing/) accounts.
        * Reranking enhances search accuracy and variety and more details can be found [here](https://docs.vectara.com/docs/api-reference/search-apis/reranking).
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/read-conversations:
    post:
      operationId: ReadConversations
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/chatReadConversationsResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/chatReadConversationsRequest"
        required: true
      tags:
        - ChatService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: "Retrieves detailed information about specific conversations. This information enables developers to analyze the flow of user chats and understand the context of interactions, which helps in refining chatbot responses. You can read up to 100 conversations.        \n\nSome tips for this API:\n* This operation authenticates with either an API Key or OAuth 2.0 (in a JWT \"Bearer Token\"). You can find details of how to set up an API key or use OAuth 2.0 [here](https://docs.vectara.com/docs/console-ui/manage-api-access).\n"
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/read-corpus:
    post:
      operationId: ReadCorpus
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminReadCorpusResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminReadCorpusRequest"
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Displays detailed information about corpora within your account including basic information, metadata, and whether it is enabled or disabled.
        This endpoint can help administrators monitor the amount of quota consumed by tenants.

        Some tips for this API:
        * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).
        * The `filter` feature applies to either the name *or* the description of a corpus.
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/replace-corpus-filter-attrs:
    post:
      operationId: ReplaceCorpusFilterAttrs
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminReplaceCorpusFilterAttrsResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminReplaceCorpusFilterAttrsRequest"
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Updates the filterable metadata fields for the corpus.

        See our documentation on [filterable metadata fields](https://docs.vectara.com/docs/learn/metadata-search-filtering/filter-overview) for more details on how these are used.

        Some tips for this API:
        * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).
        * Each request to replace the corpus filter attributes kicks off a background [job](https://docs.vectara.com/docs/rest-api/list-jobs).  The job ID is returned when you kick off a metadata filter update job so you can track it later.
        * Existing filters will continue to apply until the update job completes.
        * The time that update filter jobs take is roughly proportional to the size of the corpus.  Updates on small corpora generally take a few minutes at most, but updates on large corpora can take many minutes to hours to complete.
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/reset-corpus:
    post:
      operationId: ResetCorpus
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminResetCorpusResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminResetCorpusRequest"
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Resets a corpus by removing all of the documents inside of it.

        Some tips for this API:
        * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).
        * The `filter` feature applies to either the name *or* the description of a corpus.
        * If you want to delete individual documents instead of all documents in the corpus, you can use the [Delete API](https://docs.vectara.com/docs/rest-api/delete).
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/stream-query:
    post:
      operationId: StreamQuery
      responses:
        "200":
          description: A successful response.(streaming responses)
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: "#/components/schemas/servingQueryResponsePart"
                  error:
                    $ref: "#/components/schemas/googlerpcStatus"
                title: Stream result of servingQueryResponsePart
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        $ref: "#/components/requestBodies/servingBatchQueryRequest"
      tags:
        - QueryService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Stream responses as you search for relevant results, highlight relevant snippets, and do
        [Retrieval Augmented Generation](https://docs.vectara.com/docs/learn/grounded-generation/grounded-generation-overview) (RAG).

        Instead of receiving a complete response like with the Standard Query API, you receive partial responses in this order:
        1. Search results.
        2. If summarization is enabled, you get chunks of the summary, like "This", "is", "a", "summary".
        3. If FCS is enabled, then the FCS is the final response.

        Some tips for this API:
        * This operation authenticates with either an API Key or OAuth 2.0 (in a JWT "Bearer Token"). You can find details of how to set up an API key or use OAuth 2.0 [here](https://docs.vectara.com/docs/console-ui/manage-api-access).
        * The Query API takes an *array* of queries, since you can have Vectara perform more than 1 query in a single API call.  The results that are returned are thus in an array as well, with each element in the response array corresponding to the input query array.
        * Custom dimensions (the `dim` array) is a feature that is only available to [Scale](https://vectara.com/pricing/) accounts.
        * Reranking enhances search accuracy and variety and more details can be found [here](https://docs.vectara.com/docs/api-reference/search-apis/reranking).
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/update-corpus-enablement:
    post:
      operationId: UpdateCorpusEnablement
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/adminUpdateCorpusEnablementResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/adminUpdateCorpusEnablementRequest"
        required: true
      tags:
        - AdminService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        Lets you enable or disable a corpus. This is useful when you need to take the corpus offline without having to delete the corpus.

        Some tips for this API:
        * This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/learn/authentication/oauth-2).
        * The `filter` feature applies to either the name *or* the description of a corpus.
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/core/index:
    post:
      operationId: CoreIndex
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/vectaraIndexCoreDocumentResponse"
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/vectaraIndexCoreDocumentRequest"
        description: Request to index a document.
        required: true
      tags:
        - IndexService
      parameters:
        - $ref: '#/components/parameters/customerIdentifier'
        - $ref: '#/components/parameters/timeout'
      description: |
        This API is intended to be used by experts.  It gives you fine-grained control over chunking
        strategies by using the `parts`.  Most users will want to use the [File Upload API](https://docs.vectara.com/docs/rest-api/file-upload) or the "standard" [Index API](https://docs.vectara.com/docs/rest-api/index).

        Some tips for this API:
        * This operation authenticates with either the Personal API Key, Index API Key, or OAuth 2.0 (in a JWT "Bearer Token"). You can find details of how to set up an API key or use OAuth 2.0 [here](https://docs.vectara.com/docs/console-ui/manage-api-access).
        * The `metadataJson` object needs the JSON to be escaped so that it's not confused with other parts of the request JSON.
        * [Custom dimensions](https://docs.vectara.com/docs/learn/semantic-search/add-custom-dimensions) (`customDims`) is a feature that is only available to [Scale](https://vectara.com/pricing/) accounts.
      security:
        - ApiKeyAuth: []
        - oAuth: []
  /v1/upload:
    post:
      description: |
        The File Upload API can be used to index binary files like PDFs, Word Documents, and similar.
        Vectara will attempt to automatically extract the text and any metadata from the document like
        author or title, though you can provide additional metadata as well.

        Some tips for this API:
        * This operation authenticates with either the Personal API Key, Index API Key, or OAuth 2.0 (in a JWT "Bearer Token"). You can find details of how to set up an API key or use OAuth 2.0 [here](https://docs.vectara.com/docs/console-ui/manage-api-access).
        * You can find a full list of supported file formats [here](https://docs.vectara.com/docs/api-reference/indexing-apis/file-upload/file-upload-filetypes).
        * To provide additional metadata, set the `doc_metadata` field.  You can find some additional details [here](https://docs.vectara.com/docs/api-reference/indexing-apis/file-upload/file-upload#attach-additional-metadata)
        * PDFs must contain text: Vectara does not currently support indexing scanned images via OCR.
        * There is a known issue with the OpenAPI plugin where the generated Python script for file uploads incorrectly uses placeholder values for the file path and filename. Manually replace '/path/to/file' and 'file' in the files array with the actual file path and filename.
      operationId: FileUpload
      tags:
        - IndexService
      security:
        - ApiKeyAuth: []
        - oAuth: []
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                doc_metadata:
                  description: A JSON string of any additional metadata you want attached to the file.
                  type: string
                file:
                  description: The file to be indexed into Vectara.
                  type: string
                  format: binary
              required:
                - file
      parameters:
        - in: query
          name: c
          required: true
          description: Customer ID
          schema:
            type: integer
        - in: query
          name: o
          required: true
          description: Corpus ID
          schema:
            type: integer
          example: 1
        - in: query
          name: d
          required: false
          description: If true, the server returns the extracted document that was indexed
          schema:
            type: boolean
      responses:
        "200":
          description: A successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      status:
                        type: object
                      quotaConsumed:
                        type: object
                        properties:
                          numChars:
                            type: string
                            description: The number of characters Vectara indexed from the file uploaded.
                          numMetadataChars:
                            type: string
                            description: The number of metadata characters Vectara indexed from the file uploaded.
        "400":
          description: An invalid request was sent.  e.g. one or more parameters was missing, or the corpus does not exist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  httpCode:
                    type: integer
                    description: Returned HTTP code
        "401":
          description: The request was not authenticated
        "403":
          description: The caller is not authorized to add documents to the corpus
        "409":
          description: |-
            A document already exists in the corpus with the same document ID, yet the contents of the indexed document are different than the file being uploaded.
            Since the indexer is idempotent, the same document (identified by the document ID) can be uploaded multiple times.
            The indexer does not support updates yet, so an error is returned when a different document is uploaded for the same document ID
            Note that when a raw file is uploaded, the file name is used as the document ID.
        "507":
          description: There is no more indexing quota left for the corpus or customer to index more documents.  Upgrade your account, add a credit card, or contact sales.
components:
  requestBodies:
    servingBatchQueryRequest:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/servingBatchQueryRequest"
      required: true
  schemas:
    CorpusKeySemantics:
      type: string
      enum:
        - DEFAULT
        - QUERY
        - RESPONSE
      default: DEFAULT
      description: >-
        Semantics controls the interpretation of the query string by the

        server, and can be used to override the default semantics assigned

        in the corpus definition.











         - DEFAULT: Use corpus-assigned semantics.  This is the most common setting.
         - QUERY: Use query semantics.  This is also common.
         - RESPONSE: Use response semantics.  Usage of this is rare.
    CreateApiKeyRequestApiKeyCorpus:
      type: object
      properties:
        description:
          type: string
          description: Description of the ApiKey.
        apiKeyType:
          $ref: "#/components/schemas/adminApiKeyType"
        corpusId:
          type: array
          items:
            type: integer
            format: int64
          description: List of corpus ids to bind the ApiKey to.
      description: ApiKey data to create the ApiKey bound to one or more corpora.
    CreateApiKeyResponseApiKeyOrStatus:
      type: object
      properties:
        keyId:
          type: string
          description: A valid ApiKey.
        status:
          $ref: "#/components/schemas/comvectaraStatus"
      description: A valid key or Status of the ApiKey creation (in case of failure).
    EnableApiKeyRequestApiKeyEnablement:
      type: object
      properties:
        keyId:
          type: string
          description: ApiKey id to enable or disable.
        enable:
          type: boolean
          title: Enable or disable using this variable
    ListApiKeysResponseKeyAndCorpora:
      type: object
      properties:
        apiKey:
          $ref: "#/components/schemas/adminApiKey"
        corpus:
          type: array
          items:
            $ref: "#/components/schemas/ListApiKeysResponseKeyAndCorporaCorpusInfo"
          description: List of corpora associated with the ApiKey.
      description: A message containing ApiKey and associated corpora.
    ListApiKeysResponseKeyAndCorporaCorpusInfo:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Corpus id.
        name:
          type: string
          description: Corpus name.
      description: Message containing corpus name and id.
    ListDocumentsResponseDocumentInfo:
      type: object
      properties:
        id:
          type: string
          description: The document ID that was used when indexing the document.
        metadata:
          type: array
          items:
            $ref: "#/components/schemas/comvectaraAttribute"
          description: Document metadata.
      description: Document information format of each document in the list.
    ManageUserRequestUserAction:
      type: object
      properties:
        user:
          $ref: "#/components/schemas/adminUser"
        userActionType:
          $ref: "#/components/schemas/adminUserActionType"
      title: User and action to be performed on user
    ManageUserResponseUserResponse:
      type: object
      properties:
        user:
          $ref: "#/components/schemas/adminUser"
        status:
          $ref: "#/components/schemas/comvectaraStatus"
      title: List of users and their status
    QueryRequestContextConfig:
      type: object
      example:
        sentences_before: 3
        sentences_after: 3
        start_tag: <b>
        end_tag: </b>
      properties:
        charsBefore:
          type: integer
          format: int32
          example: 30
          description: >-
            chars_before is used for showing the end user the characters leading up

            to the result snippet.  This can help the end-user understand the

            context of that result. Ignored if sentences_before is set.
        charsAfter:
          type: integer
          format: int32
          example: 30
          description: >-
            chars_after is used for showing the end user the characters after the

            result snippet.  This can help the end-user understand the context of

            that result. Ignored if sentences_before is set.
        sentencesBefore:
          type: integer
          format: int32
          example: 3
          description: >-
            sentences_before is used for showing the end user the sentences leading

            up to the result snippet.  This can help the end-user understand the

            context of that result.
        sentencesAfter:
          type: integer
          format: int32
          example: 3
          description: >-
            sentences_after is used for showing the end user the sentences leading

            up to the result snippet.  This can help the end-user understand the

            context of that result.
        startTag:
          type: string
          example: <b>
          description: >-
            The tag that wraps the snippet at the start. Often this is used to

            provide a start HTML/XML tag or some other delimiter you can use in an

            application to understand where to provide highlighting in your UI and

            understand where the context before ends and the snippet begins.
        endTag:
          type: string
          example: </b>
          description: >-
            The tag that wraps the snippet at the end. Often this is used to provide

            a start HTML/XML tag or some other delimiter you can use in an

            application to understand where to provide highlighting in your UI and

            understand where the snippet ends and the context after begins.
      description: |-
        Allows processing a matched document part text before being returned
        as a search result. Allows a search result to have more of the document
        than just the matched document part.
      required:
        - sentencesBefore
        - sentencesAfter
        - startTag
        - endTag
    QueryRequestRerankingConfig:
      type: object
      properties:
        rerankerId:
          type: integer
          format: int64
          title: |-
            Which reranking model to use if reranking.  Currently, the only IDs
            available are:
            - 272725717, HuggingFace Open Source x-attentional reranker
            - 272725718, Maximum Marginal Relevance Reranker
        mmrConfig:
          $ref: "#/components/schemas/servingMMRConfig"
      description: Configuration options to apply to the reranking.
    SummarizationRequestModelParams:
      type: object
      properties:
        maxTokens:
          type: integer
          format: int64
        temperature:
          type: number
          format: float
          description: >-
            The sampling temperature to use. Higher values make the summary more random, while lower

            values make it more focused and deterministic.
        frequencyPenalty:
          type: number
          format: float
          description: >-
            Higher values penalize new tokens based on their existing frequency in the text so far,

            decreasing the model's likelihood to repeat the same line verbatim.
        presencePenalty:
          type: number
          format: float
          description: >-
            Higher values penalize new tokens based on whether they appear in the text so far,

            increasing the model's likelihood to talk about new topics.
      description: >-
        Parameters for the summarizer model.  These are currently a Scale-only feature.

        See https://vectara.com/pricing/ for more details on becoming a Scale customer.

        WARNING: This is an experimental feature, and breakable at any point with virtually no

        notice. It is meant for experimentation to converge on optimal parameters that can then

        be set in the prompt definitions.
    UsageMetricsRequestMetricType:
      type: string
      enum:
        - METRICTYPE__NONE
        - METRICTYPE__INDEXING
        - METRICTYPE__SERVING
      default: METRICTYPE__NONE
      title: The type of metric to get
    UsageMetricsResponseIntervalValue:
      type: object
      properties:
        indexingValue:
          $ref: "#/components/schemas/adminIndexingMetric"
        servingValue:
          $ref: "#/components/schemas/adminServingMetric"
      title: The response for a single interval
    adminAbsoluteWindow:
      type: object
      properties:
        startEpochSecs:
          type: string
          format: int64
        endEpochSecs:
          type: string
          format: int64
      title: This window is used to specify a time range for metrics
    adminApiKey:
      type: object
      properties:
        id:
          type: string
        description:
          type: string
          description: Description of the ApiKey.
        keyType:
          $ref: "#/components/schemas/adminApiKeyType"
        enabled:
          type: boolean
          description: Whether the ApiKey is enabled.
        tsStart:
          type: string
          format: int64
          description: Seconds sinch Epoch when the ApiKey becomes active.
        tsEnd:
          type: string
          format: int64
          description: Seconds sinch Epoch when the ApiKey becomes inactive.
        status:
          $ref: "#/components/schemas/adminApiKeyStatus"
        publicId:
          type: integer
          format: int64
          description: An id of the key that is not sensitive.
      description: >-
        Represents an ApiKey.

        An ApiKey provides anonymous access to common tasks such as index data, query data, etc.
    adminApiKeyStatus:
      type: string
      enum:
        - UNKNOWN
        - ENABLED
        - DISABLED
        - DELETED
      default: UNKNOWN
      description: Status of ApiKey.
    adminApiKeyType:
      type: string
      enum:
        - API_KEY_TYPE__UNDEFINED
        - API_KEY_TYPE__SERVING
        - API_KEY_TYPE__SERVING_INDEXING
        - API_KEY_TYPE__PERSONAL
      default: API_KEY_TYPE__UNDEFINED
      description: >-
        Types of ApiKey.











         - API_KEY_TYPE__SERVING: ApiKey for serving. Only gives access to query data.
         - API_KEY_TYPE__SERVING_INDEXING: ApiKey for serving and indexing. Gives access to both query and index data.
         - API_KEY_TYPE__PERSONAL: ApiKey for personal access key.
    adminComputeAccountSizeRequest:
      type: object
      description: >-
        Please note that this is an expensive operation, and the requests can be throttled

        by the platform.
    adminComputeAccountSizeResponse:
      type: object
      properties:
        size:
          type: array
          items:
            $ref: "#/components/schemas/adminTextSize"
          description: >-
            One TextSize represents one cluster. The account size is a sum of all the sizes.

            Generally, this will only have one value.
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    adminComputeCorpusSizeRequest:
      type: object
      properties:
        corpusId:
          type: integer
          format: int64
          description: The corpus for which to compute the size.
    adminComputeCorpusSizeResponse:
      type: object
      properties:
        size:
          $ref: "#/components/schemas/adminCorpusSize"
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    adminCorpus:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: |-
            The Corpus ID.
            This value is ignored during Corpus creation.
        name:
          type: string
          description: The name of the corpus.
        description:
          type: string
          description: A description for the corpus.
        dtProvision:
          type: string
          format: int64
          description: |-
            The time at which the corpus was provisioned.
            This value is ignored during Corpus creation.
        enabled:
          type: boolean
          description: |-
            Whether the corpus is enabled for use or not.
            This value is ignored during Corpus creation.
        swapQenc:
          type: boolean
        swapIenc:
          type: boolean
          description: >-
            The default query encoder is designed for normal question-answering types

            of queries when the text contains the answer.  Swapping the index encoder

            is generally rare, but can be used to help directly match questions to

            questions.  This can be useful if you have a FAQ dataset and you want to

            directly match the user question to the question in the FAQ.
        textless:
          type: boolean
          description: >-
            When a corpus is "textless", Vectara does not store the original text.

            Instead, Vectara converts the text to vectors and only retains metadata.
        encrypted:
          type: boolean
          description: Encryption is on by default and cannot be turned off.
        encoderId:
          type: string
          format: uint64
          description: >-
            This is an advanced setting for changing the underlying model type.  The

            default value is "1", which is Vectara's high-performing global model.

            Underlying models may be swapped for some paying customers by contacting

            our support team.
        metadataMaxBytes:
          type: integer
          format: int64
          description: An optional maximum size of the metadata that each document can contain.
        customDimensions:
          type: array
          items:
            $ref: "#/components/schemas/adminDimension"
        filterAttributes:
          type: array
          items:
            $ref: "#/components/schemas/adminFilterAttribute"
    adminCorpusSize:
      type: object
      properties:
        epochSecs:
          type: string
          format: int64
          description: The time at which the size was calculated.
        size:
          type: string
          format: uint64
          description: The size of the corpus.
    adminCreateApiKeyRequest:
      type: object
      properties:
        apiKeyData:
          type: array
          items:
            $ref: "#/components/schemas/CreateApiKeyRequestApiKeyCorpus"
          description: List of ApiKey data to create.
      description: |-
        This request can be used to create one or more ApiKeys.
        Every ApiKey is bound to one or more corpora.
    adminCreateApiKeyResponse:
      type: object
      properties:
        response:
          type: array
          items:
            $ref: "#/components/schemas/CreateApiKeyResponseApiKeyOrStatus"
          description: List of ApiKeyOrStatus corresponding to the list of ApiKey data in request.
      description: Response of the CreateApiKeyRequest.
    adminCreateCorpusRequest:
      type: object
      properties:
        corpus:
          $ref: "#/components/schemas/adminCorpus"
    adminCreateCorpusResponse:
      type: object
      properties:
        corpusId:
          type: integer
          format: int64
          description: The Corpus ID that was created.
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    adminCustomerRole:
      type: string
      enum:
        - CustomerRole_None
        - CustomerRole_Owner
        - CustomerRole_Admin
        - CustomerRole_Billing_Admin
        - CustomerRole_Corpus_Admin
      default: CustomerRole_None
      description: >2-
         - CustomerRole_Owner: The owner is the root user of the account. Only an owner can shut
        down the account completely.
         - CustomerRole_Admin: An account administrator can do things like create corpora, add or remove users etc.
         - CustomerRole_Billing_Admin: View and modify billing-related information for the account.
         - CustomerRole_Corpus_Admin: View and modify corpus-related information for the account.
    adminDeleteApiKeyRequest:
      type: object
      properties:
        keyId:
          type: array
          items:
            type: string
          description: List of ApiKey ids to delete.
    adminDeleteApiKeyResponse:
      type: object
      properties:
        status:
          type: array
          items:
            $ref: "#/components/schemas/comvectaraStatus"
          description: Status of the DeleteApiKeyRequest.
    adminDeleteCorpusRequest:
      type: object
      example:
        corpusId: 1
      properties:
        customerId:
          type: integer
          format: int64
          description: The Customer ID that contains the corpus to be deleted.
        corpusId:
          type: integer
          format: int64
          description: The Corpus ID to be deleted.
          minimum: 1
      required:
        - customerId
        - corpusId
    adminDeleteCorpusResponse:
      type: object
      properties:
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    adminDimension:
      type: object
      properties:
        name:
          type: string
          description: |-
            The name of the custom dimension.  The maximum length of the name is
            8 characters.
        description:
          type: string
          description: A description for the custom dimension.
        servingDefault:
          type: number
          format: double
          description: >-
            The default weight to give this dimension when running queries. A value of

            0.0, for example, gives it no weight at all.
        indexingDefault:
          type: number
          format: double
          description: The default value to give to documents for this custom dimension.
      description: >-
        A custom dimension is additional numeric metadata that you want to affect

        Vectara's scoring.  For example, these could be "number of stars" ratings,

        or other business metrics like a product's margins that you want to use

        to boost where a result is in the list.
    adminEnableApiKeyRequest:
      type: object
      properties:
        keyEnablement:
          type: array
          items:
            $ref: "#/components/schemas/EnableApiKeyRequestApiKeyEnablement"
          description: List of ApiKey ids to enable or disable.
    adminEnableApiKeyResponse:
      type: object
      properties:
        status:
          type: array
          items:
            $ref: "#/components/schemas/comvectaraStatus"
          description: List of Status such as OK, FAILED corresponding to the EnableApiKeyRequest.
    adminFilterAttribute:
      type: object
      properties:
        name:
          type: string
          description: Name of the field, as seen in metadata.
        description:
          type: string
          description: An optional description.
        indexed:
          type: boolean
          description: Whether the field is indexed for maximum query speed.
        type:
          $ref: "#/components/schemas/adminFilterAttributeType"
        level:
          $ref: "#/components/schemas/adminFilterAttributeLevel"
      description: Defines metadata fields that can be used in predicate queries.
    adminFilterAttributeLevel:
      type: string
      enum:
        - FILTER_ATTRIBUTE_LEVEL__UNDEFINED
        - FILTER_ATTRIBUTE_LEVEL__DOCUMENT
        - FILTER_ATTRIBUTE_LEVEL__DOCUMENT_PART
      default: FILTER_ATTRIBUTE_LEVEL__UNDEFINED
      title: |-
        - FILTER_ATTRIBUTE_LEVEL__DOCUMENT: Document-level attribute
         - FILTER_ATTRIBUTE_LEVEL__DOCUMENT_PART: Part-level attribute
    adminFilterAttributeType:
      type: string
      enum:
        - FILTER_ATTRIBUTE_TYPE__UNDEFINED
        - FILTER_ATTRIBUTE_TYPE__INTEGER
        - FILTER_ATTRIBUTE_TYPE__INTEGER_LIST
        - FILTER_ATTRIBUTE_TYPE__REAL
        - FILTER_ATTRIBUTE_TYPE__REAL_LIST
        - FILTER_ATTRIBUTE_TYPE__TEXT
        - FILTER_ATTRIBUTE_TYPE__TEXT_LIST
        - FILTER_ATTRIBUTE_TYPE__BOOLEAN
      default: FILTER_ATTRIBUTE_TYPE__UNDEFINED
    adminIndexingMetric:
      type: object
      properties:
        docCount:
          type: string
          format: uint64
          title: The number of documents indexed
        docPartCount:
          type: string
          format: uint64
          title: The number of document parts indexed
        docPartBytes:
          type: string
          format: uint64
          description: >-
            The number of bytes indexed.

            In case of Upload API, this is the actual bytes extracted from the document and not

            the size of the document.

            In case of Index API, this is the combined size of text in all the sections of the document.
        startEpochSecs:
          type: string
          format: int64
          title: The start time for this metric
      title: Indexing data
    adminJob:
      type: object
      properties:
        id:
          type: string
        type:
          $ref: "#/components/schemas/adminJobType"
        corpusId:
          type: array
          items:
            type: integer
            format: int64
          description: Set if the job belongs to a corpus.
        state:
          $ref: "#/components/schemas/adminJobState"
        tsCreate:
          type: string
          format: int64
          description: Epoch (secs) when the job was created.
        tsStart:
          type: string
          format: int64
          description: |-
            Epoch (secs) when the job was started. Not set if the job
            hasn't started yet.
        tsComplete:
          type: string
          format: int64
          description: |-
            Epoch (secs) when the job completed. Not set if the job
            hasn't completed yet.
        userHandle:
          type: string
          description: Handle of the user that created this job.
      description: >-
        Represents a job in the system.

        A job is typically a long running unit of work for achieving a particular outcome.

        Example job: replace filter attributes of a corpus.
    adminJobState:
      type: string
      enum:
        - JOB_STATE__UNKNOWN
        - JOB_STATE__QUEUED
        - JOB_STATE__STARTED
        - JOB_STATE__COMPLETED
        - JOB_STATE__FAILED
        - JOB_STATE__TRANSIENT_FAILURE_RETRY_IMMINENT
        - JOB_STATE__ABORTED
      default: JOB_STATE__UNKNOWN
      description: The state of a job.
    adminJobType:
      type: string
      enum:
        - JOB__UNKNOWN
        - JOB__CORPUS_REBUILD_VECTOR_INDEX
        - JOB__CORPUS_REPLACE_FILTER_ATTRS
      default: JOB__UNKNOWN
      description: Type of jobs.
    adminListApiKeysRequest:
      type: object
      properties:
        numResults:
          type: integer
          format: int64
          description: Max results to return.
        pageKey:
          type: string
          format: byte
          description: |-
            A key that is passed to retrieve a specific page of results.
            Leave empty to retrieve first page. Subsequent page requests should
            use the page key returned in previous response, and all other
            fields are ignored.
        apiKeyType:
          type: array
          items:
            $ref: "#/components/schemas/adminApiKeyType"
          description: >-
            [Optional] Get API keys of these types.

            Default: If not set, API_KEY_TYPE__SERVING and API_KEY_TYPE__SERVING_INDEXING are returned.
        readCorporaInfo:
          type: boolean
          description: If set, returns corpus name & id associated with api keys.
    adminListApiKeysResponse:
      type: object
      properties:
        keyData:
          type: array
          items:
            $ref: "#/components/schemas/ListApiKeysResponseKeyAndCorpora"
          description: List of ApiKey and associated corpora.
        pageKey:
          type: string
          format: byte
          description: |-
            A key that is passed into a subsequent result in order to
            retrieve the next page of results.
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    adminListCorporaRequest:
      type: object
      example:
        numResults: 10
        filter: "[Tt][Ee][Ss][Tt]"
      properties:
        filter:
          type: string
          example: "[Tt][Ee][Ss][Tt]"
          description: A regex over the names and descriptions to match corpora against.
        numResults:
          type: integer
          format: int64
          description: The maximum results to return.
          minimum: 1
        pageKey:
          type: string
          format: byte
          description: A key that is passed in to retrieve a specific page of results.
      required:
        - numResults
    adminListCorporaResponse:
      type: object
      properties:
        corpus:
          type: array
          items:
            $ref: "#/components/schemas/adminCorpus"
        pageKey:
          type: string
          format: byte
          description: |-
            A key that is passed into a subsequent result in order to
            retrieve the next page of results.
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    adminListJobsRequest:
      type: object
      properties:
        jobId:
          type: string
          description: |-
            Optional filters. If specified, the filters are logically ANDed.

            [Optional] If specified, return the job for this id.
        corpusId:
          type: array
          items:
            type: integer
            format: int64
          description: "[Optional] If specified, return jobs for these corpora only."
        epochSecs:
          type: string
          format: int64
          description: |-
            [Optional] Get jobs that were created since this epoch timestamp.
            Max allowed value is 180 days ago. Default is 180 days.
        state:
          type: array
          items:
            $ref: "#/components/schemas/adminJobState"
          description: >-
            [Optional] Get jobs with these states. If not specified, all job

            states are fetched.

            Default: If not set, JOB_STATE__QUEUED and JOB_STATE__STARTED are returned.
        numResults:
          type: integer
          format: int64
          description: Maximum results to return. Max allowed value is 100.
        pageKey:
          type: string
          format: byte
          description: |-
            A key that is passed in to retrieve a specific page of results.
            Leave empty to retrieve first page. Subsequent page request should
            use the page key returned in previous response, and all other
            fields are ignored.
    adminListJobsResponse:
      type: object
      properties:
        status:
          type: array
          items:
            $ref: "#/components/schemas/comvectaraStatus"
        job:
          type: array
          items:
            $ref: "#/components/schemas/adminJob"
        pageKey:
          type: string
          format: byte
          description: |-
            A key that is passed into a subsequent result in order to
            retrieve the next page of results.
    adminListUsersRequest:
      type: object
      properties:
        listUsersType:
          $ref: "#/components/schemas/adminListUsersType"
        pageKey:
          type: string
          format: byte
          description: |-
            A key that is passed to retrieve a specific page of results.
            Leave empty to retrieve first page. Subsequent page requests should
            use the page key returned in previous response, and all other
            fields are ignored.
        numResults:
          type: integer
          format: int64
          description: Number of results to return.
    adminListUsersResponse:
      type: object
      properties:
        user:
          type: array
          items:
            $ref: "#/components/schemas/adminUser"
          title: List of users
        pageKey:
          type: string
          format: byte
          description: |-
            A key that is passed into a subsequent result in order to
            retrieve the next page of results.
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    adminListUsersType:
      type: string
      enum:
        - LIST_USERS_TYPE__NONE
        - LIST_USERS_TYPE__CUSTOMER
        - LIST_USERS_TYPE__ALL
      default: LIST_USERS_TYPE__NONE
      title: >-
        - LIST_USERS_TYPE__CUSTOMER: Only List users with customer account-level authorizations.










         - LIST_USERS_TYPE__ALL: List All the users
    adminManageUserRequest:
      type: object
      properties:
        userAction:
          type: array
          items:
            $ref: "#/components/schemas/ManageUserRequestUserAction"
          title: List of users and actions to be performed on them
    adminManageUserResponse:
      type: object
      properties:
        response:
          type: array
          items:
            $ref: "#/components/schemas/ManageUserResponseUserResponse"
          description: List of users alongwith relative status such as OK, FAILED etc.
    adminReadCorpusRequest:
      type: object
      properties:
        corpusId:
          type: array
          items:
            type: integer
            format: int64
          description: Corpora IDs to read.
        readBasicInfo:
          type: boolean
          description: >-
            Subset of information to read.

            Set to true to read basic information about the corpus such as id, name,

            description, enabled, etc.
        readSize:
          type: boolean
          description: Set to true to read the size of the corpus.
        readApiKeys:
          type: boolean
          description: Set to true to read the API keys associated with the corpus.
        readCustomDimensions:
          type: boolean
          description: Set to true to read the custom dimensions of the corpus.
        readFilterAttributes:
          type: boolean
          description: Set to true to read the filter attributes of the corpus.
    adminReadCorpusResponse:
      type: object
      properties:
        corpora:
          type: array
          items:
            $ref: "#/components/schemas/adminReadCorpusResponseCorpusInfo"
          description: Information about the requested corpora.
    adminReadCorpusResponseCorpusInfo:
      type: object
      properties:
        corpus:
          $ref: "#/components/schemas/adminCorpus"
        corpusStatus:
          $ref: "#/components/schemas/comvectaraStatus"
        size:
          $ref: "#/components/schemas/adminCorpusSize"
        sizeStatus:
          $ref: "#/components/schemas/comvectaraStatus"
        apiKey:
          type: array
          items:
            $ref: "#/components/schemas/adminApiKey"
          description: API keys associated with the corpus. Only populated if read_api_keys is true.
        apiKeyStatus:
          $ref: "#/components/schemas/comvectaraStatus"
        customDimension:
          type: array
          items:
            $ref: "#/components/schemas/adminDimension"
          description: Custom dimensions of the corpus. Only populated if read_custom_dimensions is true.
        customDimensionStatus:
          $ref: "#/components/schemas/comvectaraStatus"
        filterAttribute:
          type: array
          items:
            $ref: "#/components/schemas/adminFilterAttribute"
          description: Filter attributes of the corpus. Only populated if read_filter_attributes is true.
        filterAttributeStatus:
          $ref: "#/components/schemas/comvectaraStatus"
      description: A Corpus information object containing the requested information.
    adminReplaceCorpusFilterAttrsRequest:
      type: object
      properties:
        corpusId:
          type: integer
          format: int64
          description: The corpus for which to update filters.
        filterAttributes:
          type: array
          items:
            $ref: "#/components/schemas/adminFilterAttribute"
          description: The filters to set. The existing filters are replaced with this list of filters.
    adminReplaceCorpusFilterAttrsResponse:
      type: object
      properties:
        status:
          $ref: "#/components/schemas/comvectaraStatus"
        jobId:
          type: string
          description: >-
            If 'status' represents success, this contains the ID assigned to the job

            for updating the list of filters. This ID can be used to query the status

            of the job.
    adminResetCorpusRequest:
      type: object
      example:
        corpusId: 1
      properties:
        customerId:
          type: integer
          format: int64
          description: The Customer ID that contains the corpus to be reset.
        corpusId:
          type: integer
          format: int64
          description: The Corpus ID to be reset.
          minimum: 1
      required:
        - customerId
        - corpusId
    adminResetCorpusResponse:
      type: object
      properties:
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    adminServingMetric:
      type: object
      properties:
        rowsRead:
          type: string
          format: uint64
          title: The number of rows read
        queryCount:
          type: string
          format: uint64
          title: The number of queries
        startEpochSecs:
          type: string
          format: int64
          title: The start time for this metric
      title: Serving/querying data
    adminTextSize:
      type: object
      properties:
        numChars:
          type: string
          format: uint64
          description: Count of actual characters in the text that will be searched.
        numMetadataChars:
          type: string
          format: uint64
          description: Count of metadata characters such as URL, author, date of creation etc.
      description: A TextSize object represents the size of stored text.
    adminUpdateCorpusEnablementRequest:
      type: object
      properties:
        corpusId:
          type: integer
          format: int64
          description: The corpus to enable or disable.
        enable:
          type: boolean
          description: If true, enable the corpus. Otherwise, disable it.
    adminUpdateCorpusEnablementResponse:
      type: object
      properties:
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    adminUsageMetricsRequest:
      type: object
      properties:
        corpusId:
          type: integer
          format: int64
          description: The corpus for which the metric is requested.
        window:
          $ref: "#/components/schemas/adminAbsoluteWindow"
        type:
          $ref: "#/components/schemas/UsageMetricsRequestMetricType"
        aggregationIntervalSecs:
          type: string
          format: int64
          description: >-
            The response stats will be aggregated by this interval. Minimum aggregation interval is 1 minute.

            Supported granularity units for aggregation are days, hours and minutes.

            For example, If 2.5 days (in seconds) are passed, results will be aggregated by 2 days.

            Similarly, if 7.6 hours (in seconds) are passed, results will be aggregated by 7 hours.
      title: The request type for usage metrics
    adminUsageMetricsResponse:
      type: object
      properties:
        values:
          type: array
          items:
            $ref: "#/components/schemas/UsageMetricsResponseIntervalValue"
          description: >-
            List of IntervalValue containing values for either Indexing or Serving. These are

            aggregated by the interval specified in the request.
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    adminUser:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: >-
            Unique ID for the user. This is required for deleting, enabling, disabling a user

            or to reset their password. This can be retrieved via ListUsers API or it is also

            returned as part of ManageUser API when a new user is created.
        handle:
          type: string
          description: Name of the user. This is required for creating a new user.
        type:
          $ref: "#/components/schemas/adminUserType"
        comment:
          type: string
          title: Comment about the user
        tsCreate:
          type: string
          format: int64
          description: Seconds since epoch when the user was created.
        idCreate:
          type: integer
          format: int64
          description: ID of the user who created this user.
        email:
          type: string
          description: Email address associated with the user. This is required for creating a new user.
        userStatus:
          $ref: "#/components/schemas/adminUserStatus"
        role:
          type: array
          items:
            $ref: "#/components/schemas/adminCustomerRole"
          title: List of customer level roles
      description: |-
        Represents a user in an account.
        A user is a person or an application that has access to the system.
    adminUserActionType:
      type: string
      enum:
        - USER_ACTION_TYPE__NONE
        - USER_ACTION_TYPE__ADD
        - USER_ACTION_TYPE__DELETE
        - USER_ACTION_TYPE__DISABLE
        - USER_ACTION_TYPE__ENABLE
        - USER_ACTION_TYPE__RESET_PASSWORD
      default: USER_ACTION_TYPE__NONE
      title: |-
        - USER_ACTION_TYPE__ADD: Add User
         - USER_ACTION_TYPE__DELETE: Delete User
         - USER_ACTION_TYPE__DISABLE: Disable User
         - USER_ACTION_TYPE__ENABLE: Enable User
         - USER_ACTION_TYPE__RESET_PASSWORD: Reset User Password
    adminUserStatus:
      type: string
      enum:
        - USER_STATUS__NONE
        - USER_STATUS__ACTIVE
        - USER_STATUS__DISABLED
      default: USER_STATUS__NONE
      title: |-
        - USER_STATUS__ACTIVE: User is active
         - USER_STATUS__DISABLED: User is disabled
    adminUserType:
      type: string
      enum:
        - USER_TYPE__NONE
        - USER_TYPE__USER
        - USER_TYPE__FEDERATED_USER
        - USER_TYPE__APP_CLIENT
      default: USER_TYPE__NONE
      description: >2-
         - USER_TYPE__USER: A normal user
         - USER_TYPE__FEDERATED_USER: A user that is authenticated by an external identity provider such as Google etc.
         - USER_TYPE__APP_CLIENT: An application client. Please note that this doesn't work with ManageUser API.
        To create an App Client, use the ManageAppClient API.
    chatConversation:
      type: object
      properties:
        id:
          type: string
          description: The ID of the conversation. This is unique within the chat history corpus.
        turn:
          type: array
          items:
            $ref: "#/components/schemas/chatTurn"
          description: The turns comprising this conversation.
      description: A chat contains several back-and-forth messages called turns.
    chatDeleteConversationsRequest:
      type: object
      properties:
        conversationId:
          type: array
          items:
            type: string
          description: "The IDs of the conversations to delete. Limit: 1000 conversations."
    chatDeleteConversationsResponse:
      type: object
      properties:
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    chatDeleteTurnsRequest:
      type: object
      properties:
        conversationId:
          type: string
          description: The ID of the conversations from which to delete turns.
        turnId:
          type: string
          description: >-
            The ID of the turn to start deletion from. All turns in this conversation starting from this

            turn (inclusive) will be deleted.
    chatDeleteTurnsResponse:
      type: object
      properties:
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    chatDisableTurnsRequest:
      type: object
      properties:
        conversationId:
          type: string
          description: The ID of the conversations from which to disable turns.
        turnId:
          type: string
          description: >-
            The ID of the turn to start disabling from. All turns in this conversation starting from this

            turn will be disabled.
    chatDisableTurnsResponse:
      type: object
      properties:
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    chatListConversationsRequest:
      type: object
      properties:
        numResults:
          type: integer
          format: int64
          description: Maximum number of conversations to return per page.
          example: 0
        pageKey:
          type: string
          format: byte
          description: >-
            A key that is passed in to retrieve a specific page of results.

            Leave empty to retrieve the first page. Subsequent page request should

            use the page key returned in previous response, and all other

            fields are ignored.
          example: ""
          # add required headers
    chatListConversationsResponse:
      type: object
      properties:
        conversation:
          type: array
          items:
            $ref: "#/components/schemas/chatTurn"
          description: >-
            The first turn in each conversation.

            This doesn't comprise all turns in each conversation; only the first turn of each

            conversation is returned.
        status:
          $ref: "#/components/schemas/comvectaraStatus"
        pageKey:
          type: string
          format: byte
          description: >-
            A key that is passed in to retrieve a specific page of results.

            Pass this as is in to the next request to retrieve the next page of results.
    chatReadConversationsRequest:
      type: object
      properties:
        conversationId:
          type: array
          items:
            type: string
          description: "The IDs of the conversations to read. Limit: 10 conversations."
    chatReadConversationsResponse:
      type: object
      properties:
        Conversation:
          type: array
          items:
            $ref: "#/components/schemas/chatConversation"
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    chatTurn:
      type: object
      properties:
        id:
          type: string
          description: >-
            The ID of the turn. The ID of the first turn in a conversation is the same as the

            ID of the conversation. This is unique within the chat history corpus.
        conversationId:
          type: string
          description: >-
            The ID of the conversation this turn belongs to. This is the same as the ID of the

            first turn in the conversation.
        query:
          type: string
          description: The query text.
        answer:
          type: string
          description: The answer text.
        enabled:
          type: boolean
          description: >-
            Whether this turn is enabled. If a turn is disabled, it will not be used when

            generating answers for subsequent queries in the conversation.
        epochSecs:
          type: string
          format: int64
          description: The time at which this turn was created.
      description: |-
        A turn in a conversation is a single exchange of query and answer.
        A conversation is composed of several turns.
    comvectaraAttribute:
      type: object
      properties:
        name:
          type: string
          description: Name of the document metadata attribute.
        value:
          type: string
          description: Value of the document metadata attribute.
      description: A key/value pair representing a document attribute (metadata item).
    comvectaraStatus:
      type: object
      properties:
        code:
          $ref: "#/components/schemas/vectaraStatusCode"
        statusDetail:
          type: string
    googlerpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: "#/components/schemas/protobufAny"
    indexingSection:
      type: object
      properties:
        id:
          type: integer
          format: int32
          description: >-
            Optionally, the unique ID of this section. If set, it will be returned as

            metadata in query results.
        title:
          type: string
          description: Optionally, the title of the section. This may be empty.
        text:
          type: string
          description: The text of the section. This should never be empty.
        metadataJson:
          type: string
          description: >-
            Metadata about this section. This should be a json string. It is passed

            through the system, without being used at indexing time. It can be

            retrieved at query time.
        section:
          type: array
          items:
            $ref: "#/components/schemas/indexingSection"
          description: A list of subsections.
      description: A section within a structured document.
    listsListDocumentsRequest:
      type: object
      properties:
        corpusId:
          type: integer
          format: int64
          description: The Corpus ID.
        numResults:
          type: integer
          format: int64
          description: |-
            Maximum number of results to be returned by the server.
            Max is 1000.
            If the value is larger than 1000, it will be capped to 1000.
        pageKey:
          type: string
          format: byte
          description: >-
            Key of the specific page of the list results to return.

            Null/empty value means the very first page of the results is requested.
        metadataFilter:
          type: string
          description: >-
            Filter on document metadata. If empty, no filtering is done.

            Otherwise, only documents that match all of the specified metadata

            will be returned. The syntax is the same as for QueryRequest.metadata.
      description: Request to list documents in a corpus.
    listsListDocumentsResponse:
      type: object
      properties:
        document:
          type: array
          items:
            $ref: "#/components/schemas/ListDocumentsResponseDocumentInfo"
          description: The list of documents.
        nextPageKey:
          type: string
          format: byte
          description: >-
            Represents the pagination key to retrieve the next page of results.

            If the value is "", it means no further results for the request.

            To retrieve the next page of results, client shall pass the value of next_page_key in the subsequent

            ListDocumentsRequest method call (in the request message's page_key field).
      description: Response of listing documents in a corpus.
    protobufAny:
      type: object
      properties:
        "@type":
          type: string
          description: >-
            A URL/resource name that uniquely identifies the type of the serialized

            protocol buffer message. This string must contain at least

            one "/" character. The last segment of the URL's path must represent

            the fully qualified name of the type (as in

            `path/google.protobuf.Duration`). The name should be in a canonical form

            (e.g., leading "." is not accepted).


            In practice, teams usually precompile into the binary all types that they

            expect it to use in the context of Any. However, for URLs which use the

            scheme `http`, `https`, or no scheme, one can optionally set up a type

            server that maps type URLs to message definitions as follows:


            * If no scheme is provided, `https` is assumed.

            * An HTTP GET on the URL must yield a [google.protobuf.Type][]











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











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

            Note: this functionality is not currently available in the official

            protobuf release, and it is not used for type URLs beginning with

            type.googleapis.com.


            Schemes other than `http`, `https` (or the empty scheme) might be

            used with implementation specific semantics.
      additionalProperties: {}
      description: >-
        `Any` contains an arbitrary serialized protocol buffer message along with a

        URL that describes the type of the serialized message.


        Protobuf library provides support to pack/unpack Any values in the form

        of utility functions or additional generated methods of the Any type.


        Example 1: Pack and unpack a message in C++.












            Foo foo = ...;
            Any any;
            any.PackFrom(foo);
            ...
            if (any.UnpackTo(&foo)) {
              ...
            }

        Example 2: Pack and unpack a message in Java.












            Foo foo = ...;
            Any any = Any.pack(foo);
            ...
            if (any.is(Foo.class)) {
              foo = any.unpack(Foo.class);
            }

        Example 3: Pack and unpack a message in Python.












            foo = Foo(...)
            any = Any()
            any.Pack(foo)
            ...
            if any.Is(Foo.DESCRIPTOR):
              any.Unpack(foo)
              ...

        Example 4: Pack and unpack a message in Go












             foo := &pb.Foo{...}
             any, err := anypb.New(foo)
             if err != nil {
               ...
             }
             ...
             foo := &pb.Foo{}
             if err := any.UnmarshalTo(foo); err != nil {
               ...
             }

        The pack methods provided by protobuf library will by default use

        'type.googleapis.com/full.type.name' as the type URL and the unpack

        methods only use the fully qualified type name after the last '/'

        in the type URL, for example "foo.bar.com/x/y.z" will yield type

        name "y.z".



        JSON


        The JSON representation of an `Any` value uses the regular

        representation of the deserialized, embedded message, with an

        additional field `@type` which contains the type URL. Example:












            package google.profile;
            message Person {
              string first_name = 1;
              string last_name = 2;
            }

            {
              "@type": "type.googleapis.com/google.profile.Person",
              "firstName": <string>,
              "lastName": <string>
            }

        If the embedded message type is well-known and has a custom JSON

        representation, that representation will be embedded adding a field

        `value` which holds the custom JSON in addition to the `@type`

        field. Example (for message [google.protobuf.Duration][]):












            {
              "@type": "type.googleapis.com/google.protobuf.Duration",
              "value": "1.212s"
            }
    servingBatchQueryRequest:
      type: object
      properties:
        query:
          type: array
          items:
            $ref: "#/components/schemas/servingQueryRequest"
          description: >-
            Each request can have multiple queries that result in multiple search results. Each query can search multiple corpora.
      required: ["query"]
      example:
        query:
          - query: "What is the answer to the life, the universe, and everything?"
            start: 0
            numResults: 10
            contextConfig:
              sentencesBefore: 3
              sentencesAfter: 3
              startTag: "<b>"
              endTag: "</b>"
            corpusKey:
              - customerId: 12345
                corpusId: 12
            summary:
              - maxSummarizedResults: 10
                responseLang: "en"
    servingBatchQueryResponse:
      type: object
      properties:
        responseSet:
          type: array
          items:
            $ref: "#/components/schemas/servingResponseSet"
          description: >-
            The response sets for queries within the batch. If using synchronous APIs

            for querying, the response set will be included directly in the response.

            However, if using the streaming APIs for query, the response set messages

            only set the future_id field. Later, as response sets are computed and

            returned over the stream, the future_id within the summary can be used for

            correlation.
        status:
          type: array
          items:
            $ref: "#/components/schemas/comvectaraStatus"
        metrics:
          $ref: "#/components/schemas/servingPerformanceMetrics"
    servingChat:
      type: object
      properties:
        conversationId:
          type: string
          description: The conversation id of the chat.
        turnId:
          type: string
          description: The id assigned to this query and answer.
        status:
          $ref: "#/components/schemas/comvectaraStatus"
      description: Values needed to refer to the chat later.
    servingChatRequest:
      type: object
      properties:
        store:
          type: boolean
          description: Whether to store the query/answer pair.
        conversationId:
          type: string
          description: |-
            The conversation id of the chat.
            If empty, a new conversation will be started.
      description: The chat request.
    servingCitationParams:
      type: object
      properties:
        style:
          $ref: "#/components/schemas/servingCitationStyle"
        urlPattern:
          type: string
          title: |-
            The url pattern if the citation_style is set to HTML or MARKDOWN.
            The pattern can access part and doc fields.
            i.e. https://my.doc/foo/{doc.id}/{part.id}
        textPattern:
          type: string
          title: >-
            The text pattern if the citation_style is set to HTML or MARKDOWN.

            This pattern defaults to N being the index of result if it is not set.

            Final result looks like in this case: [N](https://my.doc/foo)

            It can also be customized to access the part/doc fields by passing

            the field name in curly braces. e.g., {doc.title} or {part.page}

            Final result would look like [Title](https://my.doc/foo/2/1)
      description: Citation parameters for the summary.
    servingCitationStyle:
      type: string
      enum:
        - NUMERIC
        - NONE
        - HTML
        - MARKDOWN
      default: NUMERIC
      description: |-
        The citation style to be used in summary. They are used to reference
        the source of the information from the documents in the summary.

         - NUMERIC: Default style. E.g., [1], [2]
         - NONE: No citations.
         - HTML: HTML E.g. <a href="https://my.doc/foo">[N]</a>
         - MARKDOWN: MARKDOWN E.g. [N](https://my.doc/foo)
    servingCorpusKey:
      type: object
      example:
        corpus_id: 12
      properties:
        customerId:
          type: integer
          format: int64
          description: The Customer ID.
        corpusId:
          type: integer
          format: int64
          description: The Corpus ID.
        semantics:
          $ref: "#/components/schemas/CorpusKeySemantics"
        metadataFilter:
          type: string
          description: >-
            Filter the documents and document parts based on their metadata.

            See https://docs.vectara.com/docs/learn/metadata-search-filtering/filter-overview

            for a detailed explanation on how to create a metadata filter.
        lexicalInterpolationConfig:
          $ref: "#/components/schemas/servingLinearInterpolation"
      description: Object to specify how each corpus in a query is searched.
      required:
        - corpusId
    servingFactualConsistency:
      type: object
      properties:
        score:
          type: number
          format: float
          description: The probability that the summary is factually consistent with the results in the ResponseSet.
        status:
          $ref: "#/components/schemas/comvectaraStatus"
    servingLinearInterpolation:
      type: object
      properties:
        lambda:
          type: number
          format: float
          example: 0.025
          title: >-
            Controls the weight given to lexical matches. The final score, S, is then:










                S = (lambda) * (lexical score) + (1 - lambda) * (dense score)
      description: Configuration for a linear interpolation.
    servingMMRConfig:
      type: object
      properties:
        diversityBias:
          type: number
          format: float
          example: 0.3
          description: The diversity bias. Higher values indicate more diversity.
      description: Configuration for the maximum marginal relevance (MMR) reranker.
    servingPerformanceMetrics:
      type: object
      properties:
        queryEncodeMs:
          type: integer
          format: int64
          description: How long it took to encode the query.
        retrievalMs:
          type: integer
          format: int64
          description: How long it took to retrieve relevant results.
        userdataRetrievalMs:
          type: integer
          format: int64
          description: How long it took to retrieve user data.
        rerankMs:
          type: integer
          format: int64
          description: How long it took to rerank the results.
      description: Basic performance metrics that can be attached to a server response.
    servingQueryRequest:
      type: object
      properties:
        query:
          type: string
          description: "The query text to use from the end user."
        start:
          type: integer
          format: int64
          title: The start position in the result set
          description: "The starting point for the query."
        numResults:
          type: integer
          format: int64
          description: "The number of results to return. Possible values: >= 1"
          minimum: 1
          example: 10
        contextConfig:
          $ref: "#/components/schemas/QueryRequestContextConfig"
          type: object
          description: "Allows processing a matched document part text before being returned as a search result."
          properties:
            charsBefore:
              type: integer
              description: "chars_before is used for showing the end user the characters leading up to the result snippet. Ignored if sentences_before is set."
            charsAfter:
              type: integer
              description: "chars_after is used for showing the end user the characters after the result snippet. Ignored if sentences_before is set."
            sentencesBefore:
              type: integer
              description: "sentences_before is used for showing the end user the sentences leading up to the result snippet."
              example: 3
            sentencesAfter:
              type: integer
              description: "sentences_after is used for showing the end user the sentences leading up to the result snippet."
              example: 3
            startTag:
              type: string
              description: "The tag that wraps the snippet at the start."
              example: "<b>"
            endTag:
              type: string
              description: "The tag that wraps the snippet at the end."
              example: "</b>"
        corpusKey:
          type: array
          items:
            $ref: "#/components/schemas/servingCorpusKey"
            type: object
            properties:
              customerId:
                type: integer
                description: "The Customer ID."
              corpusId:
                type: integer
                description: "The Corpus ID. Possible values: >= 1"
                minimum: 1
                example: 12
              semantics:
                type: string
                description: "Semantics controls the interpretation of the query string by the server."
                enum: ["DEFAULT", "QUERY", "RESPONSE"]
                default: "DEFAULT"
              metadataFilter:
                type: string
                description: "Filter the documents and document parts based on their metadata."
              lexicalInterpolationConfig:
                type: object
                description: "Configuration for a linear interpolation."
                properties:
                  lambda:
                    type: number
                    description: "Linear interpolation parameter."
            required: ["corpusId"]
          description: |-
            The query is run on all these corpora, and the results are merged together in the response, ranked by score.
        summary:
          type: array
          items:
            $ref: "#/components/schemas/servingSummarizationRequest"
            type: object
            properties:
              summarizerPromptName:
                type: string
                description: "The name of the summarizer+prompt combination to use for summarization."
              maxSummarizedResults:
                type: integer
                description: "Maximum number of results to summarize."
                example: 10
              responseLang:
                type: string
                description: "ISO 639-1 or ISO 639-3 language code for the response."
                example: "en"
              promptText:
                type: string
                description: "The prompt_text is in the form of an Apache Velocity template."
              debug:
                type: boolean
                description: "Debugging the generative prompt."
              responseChars:
                type: integer
                description: "Controls the length of the summary."
              modelParams:
                type: object
                description: "Parameters for the summarizer model."
                properties:
                  maxTokens:
                    type: integer
                    description: "Maximum tokens for the summarizer model."
                  temperature:
                    type: number
                    description: "The sampling temperature to use."
                  frequencyPenalty:
                    type: number
                    description: "Higher values penalize new tokens based on their existing frequency in the text so far."
                  presencePenalty:
                    type: number
                    description: "Higher values penalize new tokens based on whether they appear in the text so far."
              citationParams:
                type: object
                description: "Citation parameters for the summary."
                properties:
                  style:
                    type: string
                    description: "The citation style to be used in summary."
                    enum: ["NUMERIC", "NONE", "HTML", "MARKDOWN"]
                    default: "NUMERIC"
                  urlPattern:
                    type: string
                    description: "The URL pattern if the citation_style is set to HTML or MARKDOWN."
                  textPattern:
                    type: string
                    description: "The text pattern if the citation_style is set to HTML or MARKDOWN."
              chat:
                type: object
                description: "The chat request."
                properties:
                  store:
                    type: boolean
                    description: "Whether to store the query/answer pair."
                  conversationId:
                    type: string
                    description: "The conversation ID of the chat. If empty, a new conversation will be started."
                  factualConsistencyScore:
                    type: boolean
                    description: "If unset or true, the response will include the factual consistency score."
            required: ["maxSummarizedResults", "responseLang"]
          description: "Optionally, one or more requests to summarize the results."
      required: ["numResults", "corpusKey"]
    servingQueryResponsePart:
      type: object
      properties:
        batchQueryResponse:
          $ref: "#/components/schemas/servingBatchQueryResponse"
        responseSet:
          $ref: "#/components/schemas/servingResponseSet"
        summary:
          $ref: "#/components/schemas/servingSummary"
        status:
          type: array
          items:
            $ref: "#/components/schemas/comvectaraStatus"
          description: A status code at the level of a BatchQueryResponse.
      description: |-
        This message contains individual partial results that are returned
        asynchronously by the streaming interface.
    servingResponseSet:
      type: object
      properties:
        response:
          type: array
          items:
            $ref: "#/components/schemas/vectaraservingResponse"
          description: Search results for the query.
        status:
          type: array
          items:
            $ref: "#/components/schemas/comvectaraStatus"
          description: Potentially multiple warnings.
        document:
          type: array
          items:
            $ref: "#/components/schemas/servingResponseSetDocument"
          description: Document level metadata for document parts that are in the response.
        summary:
          type: array
          items:
            $ref: "#/components/schemas/servingSummary"
          description: >-
            A summary. If using synchronous APIs for querying, the summary will be

            included directly in this response. However, if using the streaming APIs

            for query, the summary messages only set the future_id field. Later, as

            summary results are computed and returned over the stream, the future_id

            within the summary can be used for correlation.
        futureId:
          type: integer
          format: int32
          description: >-
            Populated for streaming requests only. This id should matched against

            the query response in order to know which query generated this object.
    servingResponseSetDocument:
      type: object
      properties:
        id:
          type: string
          description: The document id.
        metadata:
          type: array
          items:
            $ref: "#/components/schemas/vectaraservingAttribute"
          description: Document level metadata.
    servingSummarizationRequest:
      type: object
      example:
        max_summarized_results: 10
        response_lang: en
      properties:
        summarizerPromptName:
          type: string
          description: The name of the summarizer+prompt combination to use for summarization.
        maxSummarizedResults:
          type: integer
          format: int64
          description: Maximum number of results to summarize.
        responseLang:
          type: string
          description: >-
            ISO 639-1 or ISO 639-3 language code for the response, or "auto" to indicate that

            the auto-detected language of the incoming query should be used.
        promptText:
          type: string
          description: >-
            Vectara manages both system and user roles and prompts for the generative

            LLM out of the box by default.  However, Scale customers can override the

            prompt_text via this variable.  The prompt_text is in the form of an

            Apache Velocity template.  For more details on how to configure the

            prompt_text, see the long-form documentation at

            https://docs.vectara.com/docs/prompts/vectara-prompt-engine

            See https://vectara.com/pricing/ for more details on becoming a Scale customer.
        debug:
          type: boolean
          description: >-
            Debugging the generative prompt is currently a Scale-only feature.

            See https://vectara.com/pricing/ for more details on becoming a Scale customer.
        responseChars:
          type: integer
          format: int64
          description: >-
            Controls the length of the summary.

            This is a rough estimate and not a hard limit: the end summary can be longer or shorter

            than this value.  This is currently a Scale-only feature.

            See https://vectara.com/pricing/ for more details on becoming a Scale customer.
        modelParams:
          $ref: "#/components/schemas/SummarizationRequestModelParams"
        citationParams:
          $ref: "#/components/schemas/servingCitationParams"
        chat:
          $ref: "#/components/schemas/servingChatRequest"
        factualConsistencyScore:
          type: boolean
          description: If unset or true, the response will include the factual consistency score.
      description: How a LLM uses the search results to provide a response to a query.
      required:
        - maxSummarizedResults
        - responseLang
    servingSummary:
      type: object
      properties:
        text:
          type: string
          description: The summary text.
        lang:
          type: string
          description: >-
            ISO 639 language code of the summary. If the requested language was set to "AUTO", the

            summary language is the same as the auto-detected language of the query.
        chat:
          $ref: "#/components/schemas/servingChat"
        factualConsistency:
          $ref: "#/components/schemas/servingFactualConsistency"
        done:
          type: boolean
          description: >-
            Determines if the summary is done.

            `false` if the summary is in-progress for streaming requests, otherwise `true`.

            this only refers to summary text generation, Factual Consistency will come later if requested.
        status:
          type: array
          items:
            $ref: "#/components/schemas/comvectaraStatus"
          description: >-
            Statuses are marked “repeated” for consistency and flexibility. A failed

            summary should bubble up into the status code of the entire ResponseSet.
        futureId:
          type: integer
          format: int32
          description: Populated for streaming requests only.
    vectaraDeleteDocumentRequest:
      type: object
      properties:
        customerId:
          type: string
          format: int64
          description: The Customer ID to issue the request for.
        corpusId:
          type: string
          format: int64
          description: The Corpus ID that contains the document.
          minimum: 1
          example: 1
        documentId:
          type: string
          description: The Document ID to be deleted.
      description: Request to delete a document from an index.
      required: ['customerId', 'corpusId', 'documentId']
    vectaraDeleteDocumentResponse:
      type: object
    vectaraIndexDocumentRequest:
      type: object
      properties:
        customerId:
          type: string
          format: int64
        corpusId:
          type: string
          format: int64
          minimum: 1
          example: 1
        document:
          $ref: "#/components/schemas/vectaraindexingDocument"
      required: ['customerId', 'corpusId', 'document']
    vectaraIndexDocumentResponse:
      type: object
      properties:
        status:
          $ref: "#/components/schemas/comvectaraStatus"
        quotaConsumed:
          $ref: "#/components/schemas/vectaraStorageQuota"
    vectaraStatusCode:
      type: string
      enum:
        - OK
        - FAILURE
        - UNKNOWN
        - INVALID_ARGUMENT
        - DEADLINE_EXCEEDED
        - ALREADY_EXISTS
        - PERMISSION_DENIED
        - RESOURCE_EXHAUSTED
        - FAILED_PRECONDITION
        - ABORTED
        - OUT_OF_RANGE
        - UNIMPLEMENTED
        - INTERNAL
        - UNAVAILABLE
        - DATA_LOSS
        - UNAUTHENTICATED
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - METHOD_NOT_ALLOWED
        - CONFLICT
        - UNSUPPORTED_MEDIA_TYPE
        - TOO_MANY_REQUESTS
        - INTERNAL_SERVER_ERROR
        - NOT_IMPLEMENTED
        - SERVICE_UNAVAILABLE
        - INSUFFICIENT_STORAGE
        - UNPARSEABLE_RESPONSE
        - DISABLED_CUSTOMER
        - INVALID_CUSTOMER_ID
        - DISABLED_CORPUS
        - INVALID_CORPUS_ID
        - DISABLED_API_KEY
        - EXPIRED_API_KEY
        - INVALID_API_KEY
        - CMK_INACCESSIBLE
        - QRY__DISABLED_CORPUS
        - QRY__DOCUMENT_DB_FAILURE
        - QRY__ENCODER_FAILURE
        - QRY__INTERRUPTED
        - QRY__INVALID_CORPUS
        - QRY__INVALID_START
        - QRY__INVALID_NUM_RESULTS
        - QRY__INVALID_CONTEXT
        - QRY__MISSING_QUERY
        - QRY__MISSING_CORPUS
        - QRY__TIMEOUT
        - QRY__TOO_MANY_CORPORA
        - QRY__TOO_MANY_QUERIES
        - QRY__VECTOR_INDEX_FAILURE
        - QRY__INVALID_DIMENSION
        - QRY__INVALID_CLIENTKEY
        - QRY__DECRYPTION_FAILURE
        - QRY__INVALID_RERANKER
        - QRY__PARTIAL_RERANK
        - QRY__RERANK_FAILURE
        - QRY__TOO_MANY_RESULT_ROWS
        - QRY__PARTIAL_RETRIEVAL
        - QRY__SMRY__INVALID_SUMMARIZER_PROMPT
        - QRY__SMRY__INVALID_SUMMARY_LANG
        - QRY__SMRY__UNSUPPORTED_SUMMARY_LANG
        - QRY__SMRY__PARTIAL_SUMMARY
        - QRY__SMRY__NO_QUERY_RESULTS
        - QRY__SMRY__EVAL_UNSUPPORTED_LANG
        - QRY__SMRY__EVAL_FAILURE
        - QRY__GEN__NO_QUERY_RESULTS
        - QRY__GEN__UNPARSEABLE_MODEL_PARAMS
        - CX_SPECS__INVALID_JSON
        - CX_SPECS__UNREGISTERED_TYPE
        - CX_SPECS__MISSING_SPEC
        - CX_SPECS__MISSING_TYPE
        - CX_SPECS__UNPARSEABLE_SPEC
        - ADM__INVALID_CUSTOMER_ID
        - ADM__INVALID_CORPUS_ID
        - ADM__INVALID_ENCODER_ID
        - ADM__INVALID_ROLE_ID
        - ADM__ROLE_ALREADY_EXISTS
        - ADM__ONLY_ONE_OWNER_SUPPORTED
        - ADM__INVALID_PERMISSION
        - ADM__ROLECREATION_FAILURE
        - ADM__USER_EMAIL_NOT_AVAIALBLE
        - ADM__USERNAME_NOT_AVAILABLE
        - ADM__SIGNUP_MISSING_NAME
        - ADM__SIGNUP_MISSING_ORG
        - ADM__SIGNUP_MISSING_EMAIL
        - ADM__SIGNUP_MISSING_PAYMENT
        - ADM__SIGNUP_MISSING_PLAN
        - ADM__SIGNUP_MISSING_PASSWORD
        - ADM__SIGNUP_INVALID_NAME
        - ADM__SIGNUP_INVALID_ORG
        - ADM__SIGNUP_INVALID_EMAIL
        - ADM__SIGNUP_INVALID_PAYMENT
        - ADM__SIGNUP_INVALID_PLAN
        - ADM__SIGNUP_INVALID_PASSWORD
        - ADM__SIGNUP_INVALID_ACCOUNT_ALIAS
        - ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE
        - ADM__SIGNUP_MISSING_COUNTRY_CODE
        - ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE
        - ADM__CUST_MARK_DELETE_FAILED
        - ADM__CUST_FAISS_DEALLOC_FAILED
        - ADM__CUST_ALREADY_ACTIVE
        - ADM__CUST_REACTIVATE_FAILED
        - ADM__CUST_ENABLEMENT_FAILED
        - ADM__CORPUS_LIMIT_REACHED
        - ADM__STRIPE_CARD_DECLINED
        - ADM__STRIPE_PROCESSING_ERROR
        - ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND
        - ADM__EMAIL_NOT_VALIDATED
        - ADM__CHANGE_PLAN__NO_CURRENT_PLAN
        - ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE
        - ADM__CHANGE_PLAN__INVALID_PLAN_ID
        - ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE
        - ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE
        - ADM__CHANGE_PLAN__CONFLICTING_CHANGE
        - SCM__MISCONFIGURED_CONNECTION
        - STATS_DB_READ_FAILURE
        - VDB__TEXT_READ_FAILURE
        - REBUILD__LOW_RECALL
        - REBUILD__INDEX_UPLOAD_FAILURE
        - REBUILD__UPDATE_JOURNAL_FAILURE
        - REBUILD__UPDATE_FAISSPARAMS_FAILURE
        - REBUILD__NO_DATA
        - REBUILD__EVALUATION
        - IDX__TRANSIENT_PARTIAL_DELETION_FAILURE
        - IDX__PERMANENT_PARTIAL_DELETION_FAILURE
        - CALB__INVALID_JSON
        - CALB__INVALID_SPEC
        - CALB__UNREGISTERED_TYPE
        - CALB__MISSING_SPEC
        - CALB__MISSING_TYPE
        - CALB__UNPARSABLE_SPEC
      default: OK
    vectaraStorageQuota:
      type: object
      properties:
        numChars:
          type: string
          format: int64
          description: The number of chars from the document that consumed the storage quota.
        numMetadataChars:
          type: string
          format: int64
          description: >-
            The number of chars in the metadata of the document that consumed the

            storage quota.
      title: |-
        Encapsulates storage quota consumed by indexed documents.
        NextId: 3
    vectaraindexingCustomDimension:
      type: object
      properties:
        name:
          type: string
          description: The name of the dimension.
        value:
          type: number
          format: double
          description: The value of the dimension.
      description: The value of a custom dimension. A valid list of custom dimensions is defined ahead of time for a corpus.
    vectaraindexingDocument:
      type: object
      properties:
        documentId:
          type: string
          description: Client assigned document ID to this document.
        title:
          type: string
          description: The title of the document.
        description:
          type: string
          description: An optional description for the document.
        metadataJson:
          type: string
          description: "Metadata about the document. This is a string containing a JSON\nobject. It can be an arbitrary object except that any keys \nthat match a metadata filter of the corpus must have the\nsame value type as metadata filter's value type.\n\nA query can use this object to filter if the object's key/value pair\nhas been defined as a metadata filter.\n\nThe whole object will be in the query result."
        section:
          type: array
          items:
            $ref: "#/components/schemas/indexingSection"
          description: |-
            The actual content of the document, structured as a repeating list
            of sections.
      description: A document to index.
    vectaraservingAttribute:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
    vectaraservingCustomDimension:
      type: object
      properties:
        name:
          type: string
          description: The name of the custom dimension.
        weight:
          type: number
          format: double
          description: >-
            The weight of the custom dimension on the query side. This gets multipled

            by the matching index custom dimension weight and added to the score.
      description: Defined the weight of a custom dimension at query time.
    vectaraservingResponse:
      type: object
      properties:
        text:
          type: string
          description: The text of the document part after being modified by the context config.
        score:
          type: number
          format: float
          description: The score used for ranking results.  The higher the score, the better the match.
        metadata:
          type: array
          items:
            $ref: "#/components/schemas/vectaraservingAttribute"
          description: Document part level metadata.
        documentIndex:
          type: integer
          format: int64
          description: Use this ID to find the document in the ResponseSet.
        corpusKey:
          $ref: "#/components/schemas/servingCorpusKey"
      description: A document part that matched a query.
    indexingCoreDocument:
      type: object
      properties:
        documentId:
          type: string
          description: A document ID to assign to this document.
        metadataJson:
          type: string
          description: |-
            Metadata about the document. This should be a json string. It can be
            retrieved at query time.
        parts:
          type: array
          items:
            $ref: "#/components/schemas/indexingCoreDocumentPart"
          description: All parts of this document.
        defaultPartContext:
          type: string
          description: >-
            This field provides a way to specify a blanket context for all parts. If

            the context in a part is empty, this context will be used.
        customDims:
          type: array
          items:
            $ref: "#/components/schemas/vectaraindexingCustomDimension"
          description: |-
            A list of custom dimension values that are included in the generated
            representation of all parts.
      description: A document to index.
    indexingCoreDocumentPart:
      type: object
      properties:
        text:
          type: string
          description: A part of the document. e.g., a sentence.
        context:
          type: string
          description: Context of the part.
        metadataJson:
          type: string
          description: >-
            Metadata about this part of the document. This should be a json string.

            It is passed through the system, without being used at indexing time. It

            can be retrieved at query time.
        customDims:
          type: array
          items:
            $ref: "#/components/schemas/vectaraindexingCustomDimension"
          title: >-
            A list of custom dimension values that are included in the generated

            representation of this part.  These are optional and take on the corpus

            default custom dimension value if not explicitly provided for the document
      description: Part of a document. A document consists of several such parts.
    vectaraIndexCoreDocumentRequest:
      type: object
      properties:
        customerId:
          type: string
          format: int64
          description: The Customer ID to issue the request for.
        corpusId:
          type: string
          format: int64
          description: The Corpus ID to index the document into.
        document:
          $ref: "#/components/schemas/indexingCoreDocument"
      description: Request to index a document.
    vectaraIndexCoreDocumentResponse:
      type: object
      properties:
        status:
          $ref: "#/components/schemas/comvectaraStatus"
        quotaConsumed:
          $ref: "#/components/schemas/vectaraStorageQuota"
  securitySchemes:
    oAuth:
      type: oauth2
      description: OAuth2 access to Vectara
      flows:
        clientCredentials:
          tokenUrl: https://vectara-prod-YOUR_VECTARA_CUSTOMER_ID.auth.us-west-2.amazoncognito.com/oauth2/token
          scopes: {}
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      # defaults
  parameters:
    customerIdentifier:
      in: header
      name: customer-id
      required: true
      description: Enter the Customer ID to use for the request.
      schema:
        type: integer
    timeout:
      in: header
      name: timeout
      required: false
      description: (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S.
      schema:
        type: string
        default: "30S"
# add oauth and api key security
security:
  - oAuth: []
# add server endpoint
servers:
  - url: https://api.vectara.io
