# Table of Contents - [The Vectara Platform | Vectara Docs](#the-vectara-platform-vectara-docs) - [Delete Corpus API Definition | Vectara Docs](#delete-corpus-api-definition-vectara-docs) - [Compute Account Size API Definition | Vectara Docs](#compute-account-size-api-definition-vectara-docs) - [Create Corpus API Definition | Vectara Docs](#create-corpus-api-definition-vectara-docs) - [List API Keys API Definition | Vectara Docs](#list-api-keys-api-definition-vectara-docs) - [Reset Corpus API Definition | Vectara Docs](#reset-corpus-api-definition-vectara-docs) - [Enable API Key API Definition | Vectara Docs](#enable-api-key-api-definition-vectara-docs) - [Delete API Key API Definition | Vectara Docs](#delete-api-key-api-definition-vectara-docs) - [API Keys | Vectara Docs](#api-keys-vectara-docs) - [Create API Key API Definition | Vectara Docs](#create-api-key-api-definition-vectara-docs) - [Corpus Administration APIs | Vectara Docs](#corpus-administration-apis-vectara-docs) - [Vectara APIs Overview | Vectara Docs](#vectara-apis-overview-vectara-docs) - [API Recipes | Vectara Docs](#api-recipes-vectara-docs) - [Disable Turns API Definition | Vectara Docs](#disable-turns-api-definition-vectara-docs) - [Chat APIs Overview | Vectara Docs](#chat-apis-overview-vectara-docs) - [Delete Conversations API Definition | Vectara Docs](#delete-conversations-api-definition-vectara-docs) - [Delete Turns API Definition | Vectara Docs](#delete-turns-api-definition-vectara-docs) - [gRPC APIs | Vectara Docs](#grpc-apis-vectara-docs) - [Read Conversations API Definition | Vectara Docs](#read-conversations-api-definition-vectara-docs) - [REST APIs | Vectara Docs](#rest-apis-vectara-docs) - [Rerank Search Results | Vectara Docs](#rerank-search-results-vectara-docs) - [Batch Multiple Queries | Vectara Docs](#batch-multiple-queries-vectara-docs) - [List Conversations API Definition | Vectara Docs](#list-conversations-api-definition-vectara-docs) - [Low-level Indexing API Definition | Vectara Docs](#low-level-indexing-api-definition-vectara-docs) - [Delete Documents API Definition | Vectara Docs](#delete-documents-api-definition-vectara-docs) - [Standard Indexing API Definition | Vectara Docs](#standard-indexing-api-definition-vectara-docs) - [Query API Definition | Vectara Docs](#query-api-definition-vectara-docs) - [Vectara Answer | Vectara Docs](#vectara-answer-vectara-docs) - [Asynchronous Grounded Generation | Vectara Docs](#asynchronous-grounded-generation-vectara-docs) - [Common Use Cases | Vectara Docs](#common-use-cases-vectara-docs) - [Batching Multiple Queries | Vectara Docs](#batching-multiple-queries-vectara-docs) - [Vectara Ingest | Vectara Docs](#vectara-ingest-vectara-docs) - [React-Chatbot | Vectara Docs](#react-chatbot-vectara-docs) - [Stream Query API Definition | Vectara Docs](#stream-query-api-definition-vectara-docs) - [Create-UI | Vectara Docs](#create-ui-vectara-docs) - [Stream-Query-Client | Vectara Docs](#stream-query-client-vectara-docs) - [App Building Tools | Vectara Docs](#app-building-tools-vectara-docs) - [Semantic Search Filtering | Vectara Docs](#semantic-search-filtering-vectara-docs) - [Transport Layer Security (TLS) | Vectara Docs](#transport-layer-security-tls-vectara-docs) - [API Authorization Methods | Vectara Docs](#api-authorization-methods-vectara-docs) - [React-Search | Vectara Docs](#react-search-vectara-docs) - [Semantic Search Highlighting | Vectara Docs](#semantic-search-highlighting-vectara-docs) - [Types of API Keys | Vectara Docs](#types-of-api-keys-vectara-docs) - [Chat with Your Data | Vectara Docs](#chat-with-your-data-vectara-docs) - [Conversations Overview | Vectara Docs](#conversations-overview-vectara-docs) - [App Clients for OAuth | Vectara Docs](#app-clients-for-oauth-vectara-docs) - [Configure Server Access to a Corpus | Vectara Docs](#configure-server-access-to-a-corpus-vectara-docs) - [Personal API Keys | Vectara Docs](#personal-api-keys-vectara-docs) - [Configure Default Read Access to a Corpus | Vectara Docs](#configure-default-read-access-to-a-corpus-vectara-docs) - [Corpus Query Configuration Options | Vectara Docs](#corpus-query-configuration-options-vectara-docs) - [Create a Corpus | Vectara Docs](#create-a-corpus-vectara-docs) - [Index and Query API Keys | Vectara Docs](#index-and-query-api-keys-vectara-docs) - [Manage Documents | Vectara Docs](#manage-documents-vectara-docs) - [Manage Users | Vectara Docs](#manage-users-vectara-docs) - [Reset or Delete a Corpus | Vectara Docs](#reset-or-delete-a-corpus-vectara-docs) - [definitions | Vectara Docs](#definitions-vectara-docs) - [Vectara Chat | Vectara Docs](#vectara-chat-vectara-docs) - [Manage Payments | Vectara Docs](#manage-payments-vectara-docs) - [Vectara Console Overview | Vectara Docs](#vectara-console-overview-vectara-docs) - [deleteCorpus.php | Vectara Docs](#deletecorpus-php-vectara-docs) - [resetCorpus.php | Vectara Docs](#resetcorpus-php-vectara-docs) - [createCorpus.php | Vectara Docs](#createcorpus-php-vectara-docs) - [getJwtToken.php | Vectara Docs](#getjwttoken-php-vectara-docs) - [indexDocument.php | Vectara Docs](#indexdocument-php-vectara-docs) - [JWTFetcher.cs | Vectara Docs](#jwtfetcher-cs-vectara-docs) - [deleteDocument.php | Vectara Docs](#deletedocument-php-vectara-docs) - [queryData.php | Vectara Docs](#querydata-php-vectara-docs) - [JwtFetcher.java | Vectara Docs](#jwtfetcher-java-vectara-docs) - [rest_create_corpus.py | Vectara Docs](#rest-create-corpus-py-vectara-docs) - [rest_delete_corpus.py | Vectara Docs](#rest-delete-corpus-py-vectara-docs) - [rest_delete_document.py | Vectara Docs](#rest-delete-document-py-vectara-docs) - [rest_api_key_queries.py | Vectara Docs](#rest-api-key-queries-py-vectara-docs) - [queryDataApiKey.php | Vectara Docs](#querydataapikey-php-vectara-docs) - [rest_reset_corpus.py | Vectara Docs](#rest-reset-corpus-py-vectara-docs) - [rest_index_document.py | Vectara Docs](#rest-index-document-py-vectara-docs) - [rest_query.py | Vectara Docs](#rest-query-py-vectara-docs) - [rest_upload_file.py | Vectara Docs](#rest-upload-file-py-vectara-docs) - [rest_util.py | Vectara Docs](#rest-util-py-vectara-docs) - [RestCreateCorpus.java | Vectara Docs](#restcreatecorpus-java-vectara-docs) - [RestIndex.java | Vectara Docs](#restindex-java-vectara-docs) - [RestDeleteCorpus.cs | Vectara Docs](#restdeletecorpus-cs-vectara-docs) - [RestApiKeyQueries.java | Vectara Docs](#restapikeyqueries-java-vectara-docs) - [RestApiKeyQueries.cs | Vectara Docs](#restapikeyqueries-cs-vectara-docs) - [RestDeleteDocument.cs | Vectara Docs](#restdeletedocument-cs-vectara-docs) - [RestDeleteDocument.java | Vectara Docs](#restdeletedocument-java-vectara-docs) - [RestUploadFile.java | Vectara Docs](#restuploadfile-java-vectara-docs) - [Role-Based Access Control (RBAC) | Vectara Docs](#role-based-access-control-rbac-vectara-docs) - [API Key Management | Vectara Docs](#api-key-management-vectara-docs) - [Data Ingestion | Vectara Docs](#data-ingestion-vectara-docs) - [RestResetCorpus.cs | Vectara Docs](#restresetcorpus-cs-vectara-docs) - [uploadFile.php | Vectara Docs](#uploadfile-php-vectara-docs) - [Authentication Overview | Vectara Docs](#authentication-overview-vectara-docs) - [RestQueryData.cs | Vectara Docs](#restquerydata-cs-vectara-docs) - [RestQuery.java | Vectara Docs](#restquery-java-vectara-docs) - [OAuth 2.0 Tokens | Vectara Docs](#oauth-2-0-tokens-vectara-docs) - [RestIndexData.cs | Vectara Docs](#restindexdata-cs-vectara-docs) - [Keeping Your Data Private | Vectara Docs](#keeping-your-data-private-vectara-docs) - [Data Encryption | Vectara Docs](#data-encryption-vectara-docs) - [Textless Mode | Vectara Docs](#textless-mode-vectara-docs) - [Response Language Configuration | Vectara Docs](#response-language-configuration-vectara-docs) - [Enable Exact Keyword Text Matching | Vectara Docs](#enable-exact-keyword-text-matching-vectara-docs) - [Document Data Structuring | Vectara Docs](#document-data-structuring-vectara-docs) - [Combine Neural Search and Keyword Search | Vectara Docs](#combine-neural-search-and-keyword-search-vectara-docs) - [Select a Summarizer | Vectara Docs](#select-a-summarizer-vectara-docs) - [Metadata Filters | Vectara Docs](#metadata-filters-vectara-docs) - [Question-Answer Matching System | Vectara Docs](#question-answer-matching-system-vectara-docs) - [Retrieval Augmented Generation (RAG) Overview | Vectara Docs](#retrieval-augmented-generation-rag-overview-vectara-docs) - [Default Metadata Filters | Vectara Docs](#default-metadata-filters-vectara-docs) - [Semantic Search Fundamentals | Vectara Docs](#semantic-search-fundamentals-vectara-docs) - [Vectara Prompt Engine | Vectara Docs](#vectara-prompt-engine-vectara-docs) - [Select the Ideal Indexing API for Your Needs | Vectara Docs](#select-the-ideal-indexing-api-for-your-needs-vectara-docs) - [Relevance Tuning Techniques | Vectara Docs](#relevance-tuning-techniques-vectara-docs) - [Enable Pagination in Search Results | Vectara Docs](#enable-pagination-in-search-results-vectara-docs) - [Recommendation System | Vectara Docs](#recommendation-system-vectara-docs) - [Add Custom Dimensions to Enhance Scoring | Vectara Docs](#add-custom-dimensions-to-enhance-scoring-vectara-docs) - [Custom Prompts with Metadata | Vectara Docs](#custom-prompts-with-metadata-vectara-docs) - [Vectara API | Vectara Docs](#vectara-api-vectara-docs) - [Quick Start | Vectara Docs](#quick-start-vectara-docs) - [AdminService | Vectara Docs](#adminservice-vectara-docs) - [ChatService | Vectara Docs](#chatservice-vectara-docs) - [Delete | Vectara Docs](#delete-vectara-docs) - [ComputeAccountSize | Vectara Docs](#computeaccountsize-vectara-docs) - [ComputeCorpusSize | Vectara Docs](#computecorpussize-vectara-docs) - [DeleteApiKey | Vectara Docs](#deleteapikey-vectara-docs) - [DocumentService | Vectara Docs](#documentservice-vectara-docs) - [CreateApiKey | Vectara Docs](#createapikey-vectara-docs) - [CoreIndex | Vectara Docs](#coreindex-vectara-docs) - [CreateCorpus | Vectara Docs](#createcorpus-vectara-docs) - [DeleteTurns | Vectara Docs](#deleteturns-vectara-docs) - [FileUpload | Vectara Docs](#fileupload-vectara-docs) - [DeleteCorpus | Vectara Docs](#deletecorpus-vectara-docs) - [DeleteConversations | Vectara Docs](#deleteconversations-vectara-docs) - [DisableTurns | Vectara Docs](#disableturns-vectara-docs) - [EnableApiKey | Vectara Docs](#enableapikey-vectara-docs) - [GetUsageMetrics | Vectara Docs](#getusagemetrics-vectara-docs) - [Vectara API | Vectara Docs](#vectara-api-vectara-docs) - [IndexService | Vectara Docs](#indexservice-vectara-docs) - [QueryService | Vectara Docs](#queryservice-vectara-docs) - [ReadConversations | Vectara Docs](#readconversations-vectara-docs) - [ListConversations | Vectara Docs](#listconversations-vectara-docs) - [ListApiKeys | Vectara Docs](#listapikeys-vectara-docs) - [ListCorpora | Vectara Docs](#listcorpora-vectara-docs) - [ListDocuments | Vectara Docs](#listdocuments-vectara-docs) - [ReplaceCorpusFilterAttrs | Vectara Docs](#replacecorpusfilterattrs-vectara-docs) - [Vectara REST API | Vectara Docs](#vectara-rest-api-vectara-docs) - [ResetCorpus | Vectara Docs](#resetcorpus-vectara-docs) - [UpdateCorpusEnablement | Vectara Docs](#updatecorpusenablement-vectara-docs) - [ListJobs | Vectara Docs](#listjobs-vectara-docs) - [ListUsers | Vectara Docs](#listusers-vectara-docs) - [ManageUser | Vectara Docs](#manageuser-vectara-docs) - [ReadCorpus | Vectara Docs](#readcorpus-vectara-docs) --- # The Vectara Platform | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 On this page [API Playground\ \ Try out Vectara's REST APIs directly in your browser.](/docs/1.0/rest-api/vectara-rest-api) [Quick Start tutorial\ \ Use Vectara to ground answers in your data in a few minutes.](/docs/1.0/quickstart) Vectara is an end-to-end platform for product builders to embed powerful generative AI capabilities into applications with extraordinary results. Vectara offers significant improvements over traditional searches by understanding the context and meaning of your data. This revolutionary technology enables Vectara to drive insights and provide more accurate responses to user queries, assisting decision-making processes. User data remains secure because Vectaranever trains on customer data. Welcome to the Answer Engine[​](#welcome-to-the-answer-engine "Direct link to Welcome to the Answer Engine") ------------------------------------------------------------------------------------------------------------- The Vectara team envisions a future where generative AI powers every application to deliver contextually accurate responses and give the right answers and actions. Vectara is built on a solid **hybrid search** core to enable better generative outcomes. Traditional search technologies focus on keywords, which limit their ability to understand complex queries. Vectara deploys advanced **zero-shot** models and **conversational search** capabilities to understand, interpret, and respond to user queries with remarkable precision. Vectara summarizes search results on complex queries while providing factual citations from your data. Vectara provides the best hybrid search core and superior language understanding for ingestion and retrieval. Vectara can become your answer engine. Developer-focused, API-first, Secure[​](#developer-focused-api-first-secure "Direct link to Developer-focused, API-first, Secure") ----------------------------------------------------------------------------------------------------------------------------------- Designed for developers with an API-first approach, Vectara is the optimal choice to **integrate generative AI search** into your applications. This complete end-to-end platform provides easy ingestion and simple APIs. The Vectara Generative AI platform enables developers with the flexibility to build a [wide range of applications](/docs/use-case-exploration) with powerful search experiences. The Vectara platform never trains on customer data which enables businesses to embed generative AI capabilities without the risk of data or privacy violations. Vectara provides support for customer-managed keys, encryption at rest and during transit, client-configurable data retention, and more. ### 🌟 Ready to Dive In? Check Out Our API Playground! 🌟[​](#-ready-to-dive-in-check-out-our-api-playground- "Direct link to 🌟 Ready to Dive In? Check Out Our API Playground! 🌟") If you're ready to dive into our APIs, make your way to our [**API Playground**](/docs/1.0/rest-api/vectara-rest-api) ! This interactive environment allows you to experiment with Vectara's REST APIs directly from your browser! Tailored for developers, the API Playground offers a hands-on experience to understand and demonstrate our capabilities. Solve the Hallucination Problem[​](#solve-the-hallucination-problem "Direct link to Solve the Hallucination Problem") ---------------------------------------------------------------------------------------------------------------------- AI content generators often create **hallucinations** – false information outside of the raw, factual data - they make stuff up. These hallucinations lead to inaccurate and misleading responses Vectara addresses this problem through **Retrieval Augmented Generation (RAG)**, meaning it grounds the search results in the uploaded data. By focusing on facts and reducing hallucinations, Vectara enhances trust in AI-powered decision making. Language Agnostic[​](#language-agnostic "Direct link to Language Agnostic") ---------------------------------------------------------------------------- Use Vectara to search across multiple languages, eliminating language barriers and enabling users to find what they need, regardless of the language they use. This **cross-language** approach provides a seamless search experience for users around the world. The best answer may be written in German but a user asked the question in Spanish. The Vectara platform is more than just an AI product. It is a pioneer in the realm of **neural search**, leading the way to harness the power of your data. Vectara wants to transform the way developers interact with data and unlock a world of insights at their fingertips. Welcome to the future of information interaction! Not sure where to start?[​](#not-sure-where-to-start "Direct link to Not sure where to start?") ------------------------------------------------------------------------------------------------ If you don't have a Vectara account yet, register for one [here](https://console.vectara.com/signup) . Here are some other ideas: * Check out our [Quick Start Tutorial](/docs/1.0/quickstart) and [API Recipes](/docs/1.0/api-recipes) to index and search your first document in just a couple of minutes! * Check out some [Vectara applications, demos, and video tutorials](https://vectara.com/demos/) * View our code samples about how to use the Vectara platform at our [GitHub getting started repository](https://github.com/vectara/getting-started) * Grab the [full protobuf definitions](/docs/1.0/api-reference/protobuf-definitions) and start building using gRPC * Visit our [forums](https://discuss.vectara.com/) to ask any questions or provide any suggestions * [Welcome to the Answer Engine](#welcome-to-the-answer-engine) * [Developer-focused, API-first, Secure](#developer-focused-api-first-secure) * [🌟 Ready to Dive In? Check Out Our API Playground! 🌟](#-ready-to-dive-in-check-out-our-api-playground-) * [Solve the Hallucination Problem](#solve-the-hallucination-problem) * [Language Agnostic](#language-agnostic) * [Not sure where to start?](#not-sure-where-to-start) --- # Delete Corpus API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/admin-apis/delete-corpus) ** (2.0). Version: 1.0 On this page The Delete Corpus API lets you delete a corpus. To delete a corpus, specify the `customer_id` and `corpus_id`. Upon successful completion, space quota consumed by the corpus will be freed, and the corpus will no longer be useable for future indexing or querying. note The corpus\_id assigned to the corpus will not be reused. tip Check out our [**API Playground**](/docs/1.0/rest-api/delete-corpus) that lets you experiment with this REST endpoint to delete corpora. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Delete Corpus REST Endpoint[​](#delete-corpus-rest-endpoint "Direct link to Delete Corpus REST Endpoint") Vectara exposes a REST endpoint at the following URL to delete a corpus: https://api.vectara.io/v1/delete-corpus The API Playground shows the full [Delete Corpus](/docs/1.0/rest-api/delete-corpus) REST definition. gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Delete Corpus gRPC definition at [admin.proto](https://github.com/vectara/protos/blob/main/admin.proto) . * [REST Example](#rest-example) * [Delete Corpus REST Endpoint](#delete-corpus-rest-endpoint) * [gRPC Example](#grpc-example) --- # Compute Account Size API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/admin-apis/compute-account-size) ** (2.0). Version: 1.0 On this page The Compute Account Size API lets you view how much quota you consumed across the entire account. This capability is useful for administrators who want to track and monitor usage of multiple accounts. For example, you manage multiple tenants and notice that your account usage is higher than expected. You use the [Compute Corpus Size API](/docs/1.0/api-reference/admin-apis/corpus/compute-corpus-size) to determine that a tenant is over their quota. You decide to revoke the ability for the tenant to add more data to the corpus or perform more searches by disabling API keys. tip Check out our [**interactive API Playground**](/docs/1.0/rest-api/compute-account-size) that lets you experiment with this endpoint to view the account size. note The request to compute the account size is an expensive operation. This request requires the Customer ID parameter and the response includes a `size` object which is the sum of the number of characters and metadata characters. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Compute Account Size REST Endpoint Address[​](#compute-account-size-rest-endpoint-address "Direct link to Compute Account Size REST Endpoint Address") Vectara exposes a REST endpoint at the following URL to compute the account size: https://api.vectara.io/v1/compute-account-size The API Playground shows the full [Compute Account Size](/docs/1.0/rest-api/compute-account-size) REST definition. gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Compute Account Size gRPC definition at [admin\_account.proto](https://github.com/vectara/protos/blob/main/admin_account.proto) . * [REST Example](#rest-example) * [Compute Account Size REST Endpoint Address](#compute-account-size-rest-endpoint-address) * [gRPC Example](#grpc-example) --- # Create Corpus API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/admin-apis/create-corpus) ** (2.0). Version: 1.0 On this page The Create Corpus API lets you create a corpus that contains specific properties and attributes. tip Check out our [**API Playground**](/docs/1.0/rest-api/create-corpus) that lets you experiment with this REST endpoint to create corpora. Corpus Object[​](#corpus-object "Direct link to Corpus Object") ---------------------------------------------------------------- When you create a `corpus` object, only the `name` and `description` fields are mandatory. The response message returns a unique id, `corpus_id`, by which the corpus can be subsequently referenced. Note that the name needn't be unique within an account. In order to reference metadata in [filter expressions](/docs/1.0/learn/metadata-search-filtering/filter-overview) , the referenceable attributes must be declared at creation time in the **filter attributes**. This list cannot be changed once the corpus is created. For information on **custom dimensions**, a Scale-only feature, please see [Custom Dimensions](/docs/1.0/learn/semantic-search/add-custom-dimensions) . Like filter attributes, custom dimensions cannot be changed after the corpus is created. Filter Attribute[​](#filter-attribute "Direct link to Filter Attribute") ------------------------------------------------------------------------- A filter attribute must specify a **name**, and a **level** which indicates whether it exists in the document or part level metadata. At indexing time, metadata with this name will be extracted and made available for filter expressions to operate on. If **indexed** is true, the system will build an index on the extracted values to further improve the performance of filter expressions involving the attribute. Finally, filter attributes must specify a **type**, which is validated when documents are indexed. The four supported types are **integer**, which stores signed whole-number values up to eight bytes in length; **real**, for storing floating point values in [IEEE 754 8-byte format](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) ; **text** for storing textual strings in [UTF-8 encoding](https://en.wikipedia.org/wiki/UTF-8) , and **boolean** for storing true/false values. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Create Corpus REST Endpoint[​](#create-corpus-rest-endpoint "Direct link to Create Corpus REST Endpoint") Vectara exposes a REST endpoint at the following URL to create a corpus: https://api.vectara.io/v1/create-corpus The API Playground shows the full [Create Corpus](/docs/1.0/rest-api/create-corpus) REST definition. gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Create Corpus gRPC definition at [admin.proto](https://github.com/vectara/protos/blob/main/admin.proto) . The `CreateCorpusRequest` message contains a Corpus message with the name, description, and other customization options. The `CreateCorpusResponse` provides the response with the new Corpus ID and status. * [Corpus Object](#corpus-object) * [Filter Attribute](#filter-attribute) * [REST Example](#rest-example) * [Create Corpus REST Endpoint](#create-corpus-rest-endpoint) * [gRPC Example](#grpc-example) --- # List API Keys API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/api-keys/list-api-keys) ** (2.0). Version: 1.0 On this page The List API Keys API lists all existing API keys for a customer ID. It also shows what corpora are accessed by these keys and with what permissions. This capability can provide insights into key usage and status and help you manage the lifecycle and security of your API keys. Specify `numResults`, the `pageKey`, and `readCorporaInfo` which indicates whether to return the corpus name and `corpus_id` associated with the API keys. The response includes a `keyData` object that shows pairs of `apiKey` and `corpus` objects. tip Check out our [**interactive API Playground**](/docs/1.0/rest-api/list-api-keys) that lets you experiment with this REST endpoint to list API keys in an account. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### List API Keys Endpoint Address[​](#list-api-keys-endpoint-address "Direct link to List API Keys Endpoint Address") Vectara exposes a REST endpoint at the following URL to list API keys: https://api.vectara.io/v1/list-api-keys The API Playground shows the full [List API Keys](/docs/1.0/rest-api/list-api-keys) REST definition. gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full List API Keys gRPC definition at [admin\_apikey.proto](https://github.com/vectara/protos/blob/main/admin_apikey.proto) . * [REST Example](#rest-example) * [List API Keys Endpoint Address](#list-api-keys-endpoint-address) * [gRPC Example](#grpc-example) --- # Reset Corpus API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/admin-apis/reset-corpus) ** (2.0). Version: 1.0 On this page The Reset Corpus API lets you reset a corpus. This operation deletes the contents of a corpus, but it does not delete the corpus itself. To reset a corpus, specify the `customer_id` and `corpus_id`. Upon successful completion, space quota consumed by the corpus will be freed. tip Check out our [**API Playground**](/docs/1.0/rest-api/reset-corpus) that lets you experiment with this REST endpoint to reset corpora. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Reset Corpus REST Endpoint[​](#reset-corpus-rest-endpoint "Direct link to Reset Corpus REST Endpoint") Vectara exposes a REST endpoint at the following URL to reset a corpus: https://api.vectara.io/v1/reset-corpus The API Playground shows the full [Delete Corpus](/docs/1.0/rest-api/delete-corpus) REST definition. gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Reset Corpus gRPC definition at [admin.proto](https://github.com/vectara/protos/blob/main/admin.proto) . * [REST Example](#rest-example) * [Reset Corpus REST Endpoint](#reset-corpus-rest-endpoint) * [gRPC Example](#grpc-example) --- # Enable API Key API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/api-keys/enable-api-key) ** (2.0). Version: 1.0 On this page The Enable API Key API lets you enable or disable specific API keys. You can use this endpoint to temporarily disable access without deleting the key. This capability is useful for scenarios like maintenance windows, or when your team no longer requires access to a specific corpus. keyEnablement Object[​](#keyenablement-object "Direct link to keyEnablement Object") ------------------------------------------------------------------------------------- The `keyEnablement` object contains pairs of a `keyID` with the `enable` status as `true` or `false` for the API key. tip Check out our [**interactive API Playground**](/docs/1.0/rest-api/enable-api-key) that lets you experiment with this REST endpoint to enable and disable API keys. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Enable API Key REST Endpoint Address[​](#enable-api-key-rest-endpoint-address "Direct link to Enable API Key REST Endpoint Address") Vectara exposes a REST endpoint at the following URL to enable API keys: https://api.vectara.io/v1/enable-api-key The API Playground shows the full [Enable API Key](/docs/1.0/rest-api/enable-api-key) REST definition. gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Enable API Key gRPC definition at [admin\_apikey.proto](https://github.com/vectara/protos/blob/main/admin_apikey.proto) . * [keyEnablement Object](#keyenablement-object) * [REST Example](#rest-example) * [Enable API Key REST Endpoint Address](#enable-api-key-rest-endpoint-address) * [gRPC Example](#grpc-example) --- # Delete API Key API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/api-keys/delete-api-key) ** (2.0). Version: 1.0 On this page The Delete API Key API lets you delete one or more existing API keys. This capability is useful for managing the lifecycle and security of API keys such as when they are no longer needed or when a key is compromised. keyID String[​](#keyid-string "Direct link to keyID String") ------------------------------------------------------------- The `keyID` specifies the API key or list of keys that you want to delete. tip Check out our [**interactive API Playground**](/docs/1.0/rest-api/delete-api-key) that lets you experiment with this REST endpoint to delete API keys from an account. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Delete API Key Endpoint Address[​](#delete-api-key-endpoint-address "Direct link to Delete API Key Endpoint Address") Vectara exposes a REST endpoint at the following URL to delete API keys: https://api.vectara.io/v1/delete-api-key The API Playground shows the full [Delete API Key](/docs/1.0/rest-api/delete-api-key) REST definition. gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Delete API Key gRPC definition at [admin\_apikey.proto](https://github.com/vectara/protos/blob/main/admin_apikey.proto) . * [keyID String](#keyid-string) * [REST Example](#rest-example) * [Delete API Key Endpoint Address](#delete-api-key-endpoint-address) * [gRPC Example](#grpc-example) --- # API Keys | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/auth-apis/api-keys) ** (2.0). Version: 1.0 On this page API Keys can be used for querying and indexing operations, but cannot at this time be used for administrative operations such as creating or deleting corpora. Create an API Key[​](#create-an-api-key "Direct link to Create an API Key") ---------------------------------------------------------------------------- Go to [https://console.vectara.com/console/api-keys](https://console.vectara.com/console/api-keys) to create a new API key. API Keys can be scoped either to be query-only or both query and index. It's recommended that you choose the most limited scope you can for your application: it's "cheap" to create multiple API keys, but having an accidental publication of an over-privileged API key is often organizationally "expensive." In general, it's recommended that you use [OAuth 2.0](/docs/1.0/learn/authentication/oauth-2) if/where possible for production applications. danger πŸ”’ Always keep your API Keys and 0Auth tokens private. Do not share them through email, Slack, Discord, forums, or other public channels because it can lead to unauthorized access. Treat these keys with the same confidentiality as your personal credentials. Use an API Key[​](#use-an-api-key "Direct link to Use an API Key") ------------------------------------------------------------------- To use an API key in a request, you need to pass in `x-api-key` as an HTTP header. For example, a REST request using an API key for search would typically look like the following: headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'customer-id': '12345678', 'x-api-key': 'zwt_j839a9v80438nq093fn'}payload = { ... }url = 'https://api.vectara.io/v1/query'response = requests.request("POST", url, headers=headers, data=payload) * [Create an API Key](#create-an-api-key) * [Use an API Key](#use-an-api-key) --- # Create API Key API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/api-keys/create-api-key) ** (2.0). Version: 1.0 On this page The Create API Key API lets you create new API keys, which you can bind to one or multiple corpora. You can also decide whether to designate each key for specific access like personal API keys, only querying (read-only) or both querying and indexing (read-write). This capability is useful in scenarios where you have applications that require different levels of access to corpora data. For example, you might create a read-only API key for an application that only needs to query data. note For more information about the different types of API keys, see [**API Key Management**](/docs/1.0/learn/authentication/api-key-management) . The `apiKeyData` object includes a `description`, `apiKeyType` (query-only, indexing and querying, or personal access key), and `corpusId`. tip Check out our [**interactive API Playground**](/docs/1.0/rest-api/create-api-key) that lets you experiment with this REST endpoint to create API keys for your account. REST API Example[​](#rest-api-example "Direct link to REST API Example") ------------------------------------------------------------------------- ### Create API Key Endpoint Address[​](#create-api-key-endpoint-address "Direct link to Create API Key Endpoint Address") Vectara exposes a REST endpoint at the following URL to create API keys: https://api.vectara.io/v1/create-api-key The API Playground shows the full [Create API Key](/docs/1.0/rest-api/create-api-key) REST definition. gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Create API Key gRPC definition at [admin\_apikey.proto](https://github.com/vectara/protos/blob/main/admin_apikey.proto) . * [REST API Example](#rest-api-example) * [Create API Key Endpoint Address](#create-api-key-endpoint-address) * [gRPC Example](#grpc-example) --- # Corpus Administration APIs | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/admin-apis/admin) ** (2.0). Version: 1.0 On this page The Vectara Console is a good way for you to get started with Vectara. Once you're ready to integrate the platform more deeply into your application, the Corpus Admin APIs allow you to programmatically manipulate corpora and perform many other operations within the system. These APIs enable new workflows for organizations, like tracking usage of accounts and corpora. Check out this [blog post about managing multi-tenancy](https://vectara.com/managing-multi-tenancy-with-vectaras-new-management-apis/) for more details. tip The [**interactive API Playground**](/docs/1.0/rest-api/admin-service) lets you experiment with these API endpoints. Create, Delete, and Reset API Definitions[​](#create-delete-and-reset-api-definitions "Direct link to Create, Delete, and Reset API Definitions") -------------------------------------------------------------------------------------------------------------------------------------------------- The full definitions of the Create, Reset, and Delete gRPC APIs are covered in [admin.proto](https://github.com/vectara/protos/blob/main/admin.proto) . * The **Create API** allows corpora to be created programmatically, up to the limit defined for the account. * The **Reset API** deletes all data from a corpus, without deleting its definition. * The **Delete API** expunges both the data in the corpus and its definition. Corpus Management API Definitions[​](#corpus-management-api-definitions "Direct link to Corpus Management API Definitions") ---------------------------------------------------------------------------------------------------------------------------- The Corpus Management API definitions enable administrators to track usage of their accounts and corpora. * The **Compute Corpus Size API** allows you to understand how much a corpus has consumed. * The **Read Corpus Details API** enables you to read many aspects of a corpus, including the last computed size, associated API keys, and filter attributes. * The **Enable/Disable Corpus API** enables administrators to enable or disable a corpus, such as when you need to take a corpus offline without deleting the corpus. The REST APIs are programmatically derived from these gRPC definitions. See [REST APIs](/docs/1.0/api-reference/rest) for more information on endpoints or expand the specific API in the left navigation sidebar to find REST examples in various programming languages. note For more information on the programmatic conversion, see [**gRPC with REST and Open APIs**](https://grpc.io/blog/coreos/) . It goes into detail about how gRPC services were made available in both gRPC and HTTP REST formats to provide flexibility to users and create a versatile API framework. * [Create, Delete, and Reset API Definitions](#create-delete-and-reset-api-definitions) * [Corpus Management API Definitions](#corpus-management-api-definitions) --- # Vectara APIs Overview | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/api-overview) ** (2.0). Version: 1.0 On this page Everything in Vectara is driven by APIs. This section serves as a roadmap to understanding and using our [gRPC APIs](/docs/1.0/api-reference/protobuf-definitions) and [REST APIs](/docs/1.0/api-reference/rest) for [indexing](/docs/1.0/learn/select-ideal-indexing-api) , [querying](/docs/1.0/api-reference/search-apis/search) , and administrative tasks such as [managing user access](/docs/1.0/api-reference/admin-apis/manage-users/manage-user) and [corpora](/docs/1.0/api-reference/admin-apis/admin) . Before getting into more details, we recommend that you have a basic understanding of API concepts. 🌟 Ready to Dive In? Check Out Our API Playground! 🌟[​](#-ready-to-dive-in-check-out-our-api-playground- "Direct link to 🌟 Ready to Dive In? Check Out Our API Playground! 🌟") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you're ready to dive into our APIs, make your way to our [**API Playground**](/docs/1.0/rest-api/vectara-rest-api) ! This interactive environment allows you to experiment with Vectara's REST APIs directly from your browser! Tailored for developers, the API Playground offers a hands-on experience to understand and demonstrate our capabilities. Fundamental API Concepts[​](#fundamental-api-concepts "Direct link to Fundamental API Concepts") ------------------------------------------------------------------------------------------------- Familiarize yourself with the fundamentals of Application Programming Interfaces (APIs) including what APIs are, how they work, common use cases, and other key concepts: * **gRPC APIs:** Understand the basics of gRPC (Remote Procedure Call) such as the advantages with performance, code generation, and how it uses Protocol Buffers (**.proto** files) for schema defnitions. You can [download the `.proto` files](https://github.com/vectara/protos/tree/main) directly from Github. For example, [`serving.proto`](https://github.com/vectara/protos/blob/main/serving.proto) provides the message definitions for running queries. * **RESTful APIs:** Understand the principles of Representational State Transfer (REST) and why it's commonly used in web services. Make sure to also understand how it differs from gRPC. For example, review the [Java example](/docs/1.0/getting-started-samples/RestIndex.java) for our Standard Indexing API. * **HTTP Methods:** Become familar with HTTP methods like GET, POST, PUT, and DELETE. * **gRPC Methods:** Become familar with gRPC methods like server streaming, client streaming, and bidirectional streaming. * **Authentication:** Become aware of common authentication methods that can be implemented in both gRPC and REST APIs including API Keys and OAuth 2.0 and JWT tokens. Choosing gRPC or REST APIs[​](#choosing-grpc-or-rest-apis "Direct link to Choosing gRPC or REST APIs") ------------------------------------------------------------------------------------------------------- Almost every API has both a [gRPC](https://en.wikipedia.org/wiki/GRPC) and a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) endpoint. The only exception at this time is the [File Upload API](/docs/1.0/api-reference/indexing-apis/file-upload/file-upload) , which is only available via REST. gRPC has several advantages over REST: * It's lower latency than REST * You can get strong typing out of gRPC: essentially "client libraries" for "free" However, we include REST APIs as there's a lot of developer tooling around REST APIs and some organizations still struggle with using HTTP/2.0 due to firewalls. ### REST API[​](#rest-api "Direct link to REST API") If you'd like more details about how to use our REST APIs, including details on our OpenAPI specification and services, a good place to start is the [REST APIs](/docs/1.0/api-reference/rest) page. ### gRPC API[​](#grpc-api "Direct link to gRPC API") If you'd like more details about how to use our gRPC APIs, including details on how to generate strongly typed clients, see our [gRPC APIs](/docs/1.0/api-reference/protobuf-definitions) page. * [🌟 Ready to Dive In? Check Out Our API Playground! 🌟](#-ready-to-dive-in-check-out-our-api-playground-) * [Fundamental API Concepts](#fundamental-api-concepts) * [Choosing gRPC or REST APIs](#choosing-grpc-or-rest-apis) * [REST API](#rest-api) * [gRPC API](#grpc-api) --- # API Recipes | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-recipes) ** (2.0). Version: 1.0 On this page Using our APIs enable application developers and data engineers to seamlessly integrate the Vectara semantic search capabilities into your applications. After you review this section, you can check out our [API Playground](/docs/1.0/rest-api/vectara-rest-api) to experiment with Vectara's REST APIs directly from your browser! The Vectara Console and our APIs work hand-in-hand as part of the app development process. For example, a builder uses this following workflow: * Fine-tune a query's lambda and filters until the answer quality is just right. * Copy the request directly from the Vectara Console and paste it into your IDE. * Copy the customer ID and API key from the Vectara Console to further configure the request. * Test out the software and then verify that requests are hitting your corpus by checking the querying graph on the Overview tab. Let’s get you started with using the Vectara APIs so that you can perform queries on some data. What you will learn[​](#what-you-will-learn "Direct link to What you will learn") ---------------------------------------------------------------------------------- We'll show you several example API recipes that include queries with some values in the parameters, and then display example responses: * [Search for answers in a corpus](/docs/1.0/api-recipes#search-for-answers-in-a-corpus) * [Upload a file to the corpus](/docs/1.0/api-recipes#upload-a-file-to-the-corpus) * [Issue a query and return a specific number of results](/docs/1.0/api-recipes#issue-a-query-and-return-a-specific-number-of-results) * [List all corpora and delete a specific corpus](/docs/1.0/api-recipes#list-all-corpora-and-delete-a-specific-corpus) To issue the types of API calls in these recipes, you typically need the following information that you can get from the Vectara Console UI: * Customer ID * Corpus ID * API Key ### Search for answers in a corpus[​](#search-for-answers-in-a-corpus "Direct link to Search for answers in a corpus") In this example, you have a corpus with uploaded data from an Employee Handbook. Now you want to ask, _β€œHow much PTO is offered to employees each year?”_ To issue the cURL command in the example, you input the following field values: * `customer_id` and `customerId` = 123456789 * `x-api-key` = abc\_12345defg67890hij09876 * `corpus_id` = 1 * `query` = How much PTO is offered to employees each year? #### Example cURL command[​](#example-curl-command "Direct link to Example cURL command") This example queries the corpus with the question about annual PTO. curl -L -X POST 'https://api.vectara.io/v1/query' \-H 'Content-Type: application/json' \-H 'Accept: application/json' \-H 'customer-id: 123456789' \-H 'x-api-key: abc_12345defg67890hij09876' \--data-raw '{ "query": [ { "query": "How much PTO is offered to employees each year?", "start": 0, // 20 results per page "numResults": 20, "contextConfig": { "charsBefore": 30, "charsAfter": 30, "sentencesBefore": 3, "sentencesAfter": 3, "startTag": "", "endTag": "" }, "corpusKey": [ { "customerId": 123456789, "corpusId": 1, "semantics": "DEFAULT", "dim": [], "metadataFilter": "part.lang = '\''eng'\''", "lexicalInterpolationConfig": { // This value lets you balance neural search and keyword search // You can specify 0.0 to 1.0, where 1.0 is exact keyword matching "lambda": 0.1 } } ], "rerankingConfig": { "rerankerId": 272725717 }, "summary": [ { // This value selects the summarizer. In this case it is using // ChatGPT 3.5 Turbo. Scale users can use the 1.3.0 summarizer // which is ChatGPT 4.0 "summarizerPromptName": "vectara-summary-ext-v1.2.0", "responseLang": "en" // This value tell the summarizer to use 5 results // Experiment setting this value from 5-10 "maxSummarizedResults": 5, } ] } ]}' #### Example JSON response[​](#example-json-response "Direct link to Example JSON response") Let’s take a closer look at the first response: { "responseSet": [ { "response": [ { "text": "Employee Handbook PTO is 20 days a year for all new employees. Employees earn more vacation days per year of service up to 5 extra days. Example: Once you begin your 5th year, you now have 25 vacation days.", "score": 4.30505, "metadata": [ { "name": "lang", "value": "eng" }, { "name": "section", "value": "1" }, { "name": "offset", "value": "63" }, { "name": "len", "value": "73" } ], "documentIndex": 0, "corpusKey": { "customerId": 1, "corpusId": 123456789, "semantics": "DEFAULT", "dim": [], "metadataFilter": "", "lexicalInterpolationConfig": null }, "resultOffset": 66, "resultLength": 73 }, // More results....\ \ The example API call provided the following response:\ \ _"Employee Handbook PTO is 20 days a year for all new employees. **Employees earn more vacation days per year of service up to 5 extra days.** Example: Once you begin your 5th year, you now have 25 vacation days."_\ \ The result answers the question and returns additional details about the query, such as the language, section, and offset.\ \ Let's take a look at some other API calls that you can make.\ \ ### Upload a file to the corpus[​](#upload-a-file-to-the-corpus "Direct link to Upload a file to the corpus")\ \ If you want to add a file to an existing corpus, you can upload a new file with a simple command.\ \ You need to input the following information:\ \ * `customer_id`\ * `x-api-key`\ * `corpus_id`\ * File name\ * Path to the file\ \ #### Example cURL command[​](#example-curl-command-1 "Direct link to Example cURL command")\ \ In this example command, you have a local `doc.rtf` file that you want to upload to corpus 1, which is `corpus_id` = 1.\ \ curl -L -X POST 'https://api.vectara.io/v1/upload?c=123456789&o=1&d=true' \-H 'Content-Type: multipart/form-data' \-H 'Accept: application/json' \-H 'x-api-key: abc_12345defg67890hij09876' \-F 'file=@"//Users/username/Documents/tmp/doc.rtf"'\ \ #### Example JSON response[​](#example-json-response-1 "Direct link to Example JSON response")\ \ The file uploads successfully and you get the following response:\ \ {"response":{ "status": { }, "quotaConsumed": { "numChars": "60", "numMetadataChars": "148" } },"document":{ "documentId": "doc.rtf", "metadataJson": "{\"X-TIKA:Parsed-By\":\"org.apache.tika.parser.microsoft.rtf.RTFParser\",\"Content-Type\":\"application/rtf\"}", "section": [{ "id": 1, "text": "Simple test doc\n\nLorem ipsum \nLorem ipsum \nLorem ipsum \n " }] }} \ \ ### Issue a query and return a specific number of results[​](#issue-a-query-and-return-a-specific-number-of-results "Direct link to Issue a query and return a specific number of results")\ \ In this query, you want to search for the term "technology" and then return only the first 5 results.\ \ #### Example cURL command[​](#example-curl-command-2 "Direct link to Example cURL command")\ \ curl -L -X POST 'https://api.vectara.io/v1/query' \-H 'Content-Type: application/json' \-H 'Accept: application/json' \-H 'customer-id: 123456789' \-H 'x-api-key: abc_12345defg67890hij09876' \--data-raw '{ "query": [ { "query": "Technology", "start": 0, "numResults": 5, "corpusKey": [ { "customerId": 123456789, "corpusId": 2, "semantics": "DEFAULT", "dim": [ { "name": "string", "weight": 0 } ], "metadataFilter": "part.lang = '\''eng'\''", "lexicalInterpolationConfig": { "lambda": 0 } } ], "rerankingConfig": { "rerankerId": 272725717 }, "summary": [ { "summarizerPromptName": "vectara-summary-ext-v1.2.0", "responseLang": "en" "maxSummarizedResults": 5, } ] } ]}'\ \ #### Example JSON response with 5 results[​](#example-json-response-with-5-results "Direct link to Example JSON response with 5 results")\ \ { "status": "OK", "results": [ { "text": "The future of technology is AI.", "score": 0.98, "documentIndex": 1 // More results.... }, { "text": "Technology is evolving rapidly.", "score": 0.95, "documentIndex": 2 }, { "text": "Generative AI technology is revolutionary.", "score": 0.92, "documentIndex": 3 }, { "text": "Technology has its pros and cons.", "score": 0.90, "documentIndex": 4 }, { "text": "The role of technology in modern society.", "score": 0.88, "documentIndex": 5 } ]}\ \ ### List all corpora and delete a specific corpus[​](#list-all-corpora-and-delete-a-specific-corpus "Direct link to List all corpora and delete a specific corpus")\ \ In this example, you want to list all corpora that contain the word "handbook" in the name.\ \ 1. Execute the following curl command to list the corpora:\ \ curl -L -X POST 'https://api.vectara.io/v1/list-corpora' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'customer-id: 123456789' \ -H 'Authorization: Bearer zwt_bearer_token' \ --data-raw '{"numResults": 8,"filter": "handbook"}'\ \ You get the following response:\ \ { "corpus": [ { "id": 6, "name": "Employee handbook", "description": "Employee guidelines from HR", "enabled": true, "swapQenc": false, "swapIenc": false, "textless": false, "encrypted": false, "encoderId": "0", "metadataMaxBytes": 0, "faissIndexType": "", "customDimensions": [], "filterAttributes": [] }, { "id": 11, "name": "Employee Handbook", "description": "Pet Policy", "enabled": true, "swapQenc": false, "swapIenc": false, "textless": false, "encrypted": false, "encoderId": "0", "metadataMaxBytes": 0, "faissIndexType": "", "customDimensions": [], "filterAttributes": [] }, { "id": 13, "name": "2022 handbook", "description": "", "enabled": true, "swapQenc": false, "swapIenc": false, "textless": false, "encrypted": false, "encoderId": "0", "metadataMaxBytes": 0, "faissIndexType": "", "customDimensions": [], "filterAttributes": [] }],"pageKey": "","status": null}\ \ 2. Execute the following curl command to delete a specific corpus with `corpus_id` = 13.\ \ curl -L -X POST 'https://api.vectara.io/v1/delete-corpus' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'customer-id: 123456789' \ -H 'Authorization: Bearer zwt_bearer_token' \ --data-raw '{"corpusId": 13}'\ \ You get the following response:\ \ { "status": { "code": "OK", "statusDetail": "Corpus Deleted", "cause": null }}\ \ 3. Execute the curl command from Step 1 again and the corpus you deleted no longer exists.\ \ \ This API recipes section provided a variety of query examples that you can leverage as you start building with Vectara.\ \ * [What you will learn](#what-you-will-learn)\ * [Search for answers in a corpus](#search-for-answers-in-a-corpus)\ \ * [Upload a file to the corpus](#upload-a-file-to-the-corpus)\ \ * [Issue a query and return a specific number of results](#issue-a-query-and-return-a-specific-number-of-results)\ \ * [List all corpora and delete a specific corpus](#list-all-corpora-and-delete-a-specific-corpus) --- # Disable Turns API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/chat-apis/disable-turns) ** (2.0). Version: 1.0 On this page The Disable Turns API disables specific turns from a conversation within the chat history corpus. This enables developers to exclude specific responses from the conversation history. The `conversationId` specifies the conversation ID that contains the turn you want to disable, and the `turnId` specifies the Turn ID that you want to disable. tip Check out our **interactive API Playground** that lets you experiment with this REST endpoint to delete turns in specific chats. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Delete Turns Endpoint Address[​](#delete-turns-endpoint-address "Direct link to Delete Turns Endpoint Address") Vectara exposes an HTTP endpoint at the following URL to disable turns in a chat: https://api.vectara.io/v1/disable-turns The API Playground shows the full [Disable Turns](/docs/1.0/rest-api/disable-turns) REST definition. gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Disable Turns gRPC definition at [chat.proto](https://github.com/vectara/protos/blob/main/chat.proto) . * [REST Example](#rest-example) * [Delete Turns Endpoint Address](#delete-turns-endpoint-address) * [gRPC Example](#grpc-example) --- # Chat APIs Overview | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/chat-apis/chat-apis-overview) ** (2.0). Version: 1.0 On this page Vectara's Chat APIs provide a streamlined solution for integrating chatbot functionalities into domain-specific applications and websites using Retrieval Augmented Generation (RAG). Designed with efficiency in mind, these Chat APIs enable developers to create interactive user experiences and manage data conversations for users. With the unique `conversationId` generated for each chat session, developers can track and manage conversations over time. These Chat APIs enable operations and pagination through the history of a chat, specifically the conversations and their subsequent exchanges, also known as turns. Administrators can gain valuable insights into user behavior by analyzing trends among users, which creates opportunities to identify knowledge gaps for information about products, technical documentation, and FAQs. Vectara Chat provides the following Chat APIs: * [**Query**](/docs/1.0/api-reference/search-apis/search) contains a `chat` object within the `summary` which then has a unique `conversationId`. * [**List Conversations**](/docs/1.0/api-reference/chat-apis/list-conversations) in a chat history corpus and get an an overview of the interactions between chatbots and users. * [**Read Conversations**](/docs/1.0/api-reference/chat-apis/read-conversations) and retrieve detailed information about specific conversations by their IDs from a chat history corpus. * [**Delete Conversations**](/docs/1.0/api-reference/chat-apis/delete-conversations) by their specific Conversation IDs for data management and other purposes. * [**Delete Turns**](/docs/1.0/api-reference/chat-apis/delete-turns) from a conversation starting from a specific Turn ID to manage the content of conversations. * [**Disable Turns**](/docs/1.0/api-reference/chat-apis/disable-turns) to exclude turns from being used in generating responses. Chat Object[​](#chat-object "Direct link to Chat Object") ---------------------------------------------------------- The `summary` within a Query contains the `chat` object which then specifies the `conversationId` and `store` status as `true` or `false`. Chats are set to `false` by default so you must set them to `true` or [enable the chat option](/docs/1.0/console-ui/chat-with-your-data) in the Vectara Console. "chat": { "store": true, "conversationId": "string"} ### Conversation[​](#conversation "Direct link to Conversation") Conversations represent individual chat sessions, and a conversation starts with a chat request to the Query endpoint. A unique `conversationId` is generated at the initiation of the chat session, which serves as the identifier for all subsequent turns within this conversation. { "conversation": [ { "id": "ID of the conversation", "turn": [ { "id": "ID of the turn", "conversation_id": "ID of the conversation", "query": "First query of the turn", "answer": "First answer of the turn", "enabled": true, "epoch_secs": 0 }, ] } ] } ### Turns[​](#turns "Direct link to Turns") Each conversation has a series of `turn` objects, which are the sequence of message and response pairs that make up the dialog. Each `turn` represents a question/answer pair between the user and the chatbot and has a unique `id` that specifies its `conversation_id`. "turn": [ { "id": "ID of the turn", "conversation_id": "ID of the conversation", "query": "First query of the turn", "answer": "First answer of the turn", "enabled": true, "epoch_secs": 0 }, { "id": "ID of the second turn", "conversation_id": "ID of the conversation", "query": "Second query of the turn", "answer": "Second answer of the turn", "enabled": true, "epoch_secs": 0 }, // Additional turn IDs are created for each query and answer pair in the conversation] * [Chat Object](#chat-object) * [Conversation](#conversation) * [Turns](#turns) --- # Delete Conversations API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/chat-apis/delete-conversations) ** (2.0). Version: 1.0 On this page The Delete Conversations API lets you 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. The `conversationId` specifies the IDs of the conversations that you want to delete. The limit is 1000 conversations. tip Check out our **interactive API Playground** that lets you experiment with this REST endpoint to delete conversations in the chat history corpus. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Delete Conversations Endpoint Address[​](#delete-conversations-endpoint-address "Direct link to Delete Conversations Endpoint Address") Vectara exposes an HTTP endpoint at the following URL to delete conversations in the chat history corpus: https://api.vectara.io/v1/delete-conversations The API Playground shows the full [Delete Conversations](/docs/1.0/rest-api/delete-conversations) REST definition. gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Delete Conversations gRPC definition at [chat.proto](https://github.com/vectara/protos/blob/main/chat.proto) . * [REST Example](#rest-example) * [Delete Conversations Endpoint Address](#delete-conversations-endpoint-address) * [gRPC Example](#grpc-example) --- # Delete Turns API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/chat-apis/delete-turns) ** (2.0). Version: 1.0 On this page The Delete Turns API deletes specific turns from a conversation within the chat history corpus. This enables developers to remove inaccurate or inappropriate responses from the conversation history. The `conversationId` specifies the conversation ID that contains the turn you want to delete, and the `turnId` specifies the Turn ID that you want to delete. tip Check out our **interactive API Playground** that lets you experiment with this REST endpoint to delete turns in specific chats. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Delete Turns Endpoint Address[​](#delete-turns-endpoint-address "Direct link to Delete Turns Endpoint Address") Vectara exposes an HTTP endpoint at the following URL to delete turns in a chat: https://api.vectara.io/v1/delete-turns The API Playground shows the full [Delete Turns](/docs/1.0/rest-api/delete-turns) REST definition. gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Delete Turns gRPC definition at [chat.proto](https://github.com/vectara/protos/blob/main/chat.proto) . * [REST Example](#rest-example) * [Delete Turns Endpoint Address](#delete-turns-endpoint-address) * [gRPC Example](#grpc-example) --- # gRPC APIs | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/protobuf-definitions) ** (2.0). Version: 1.0 On this page Vectara implements a [gRPC (Remote Procedure Call) API](https://grpc.io/) to all its core services. gRPC is a high-performance, open-source framework developed by Google that enables different services to communicate with each other. Check out our [API Overview](/docs/1.0/api-reference/api-overview) for more information. Protocol Buffer Definitions[​](#protocol-buffer-definitions "Direct link to Protocol Buffer Definitions") ---------------------------------------------------------------------------------------------------------- You can download the proto files directly from GitHub below. | Protobuf | Description | | --- | --- | | [services.proto](https://github.com/vectara/protos/blob/main/services.proto) | Defines the core services within the platform. | | [serving.proto](https://github.com/vectara/protos/blob/main/serving.proto) | Message definitions for running queries. | | [custom\_dim.proto](https://github.com/vectara/protos/blob/main/custom_dim.proto) | Message definitions for custom dimensions. | | [indexing.proto](https://github.com/vectara/protos/blob/main/indexing.proto) | Message definitions for indexing content. | | [admin.proto](https://github.com/vectara/protos/blob/main/admin.proto) | Message definitions for performing administrative tasks. | | [status.proto](https://github.com/vectara/protos/blob/main/status.proto) | Status return codes. | | [common.proto](https://github.com/vectara/protos/blob/main/common.proto) | Common message definitions. | Download the Auxiliary Protocol Buffers[​](#download-the-auxiliary-protocol-buffers "Direct link to Download the Auxiliary Protocol Buffers") ---------------------------------------------------------------------------------------------------------------------------------------------- The gRPC services also use Google's [annotations.proto](https://github.com/googleapis/googleapis/blob/master/google/api/annotations.proto) and [http.proto](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto) . If you need these `proto` files, the following curl commands download these files into the `ext` subdirectory. You can then reference them in the `protoc` path using `-I ext`. proto $ lsadmin.proto common.proto indexing.proto services.proto serving.proto status.protoproto $ mkdir extproto $ curl -s -o ext/google/api/annotations.proto --create-dirs \ https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/annotations.protoproto $ curl -s -o ext/google/api/http.proto --create-dirs \ https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/http.proto Example Protocol Buffers[​](#example-protocol-buffers "Direct link to Example Protocol Buffers") ------------------------------------------------------------------------------------------------- The [Quickstart Examples](https://github.com/vectara/getting-started) GitHub repository has examples of connecting via gRPC in a variety of languages. Generating Strongly Typed Clients[​](#generating-strongly-typed-clients "Direct link to Generating Strongly Typed Clients") ---------------------------------------------------------------------------------------------------------------------------- One of the advantages of using gRPC is that there is some tooling for generating strongly-typed clients/bindings in many programming languages. These work by converting the protobuf definitions to code. The most up-to-date documentation on how to do this is in the "quick start" sections of [https://grpc.io/docs/languages/](https://grpc.io/docs/languages/) following the "Generate gRPC code" section in the language of your choosing. For example, check out the official documentation for [getting started with gRPC in Python](https://grpc.io/docs/languages/python/quickstart/) . * [Protocol Buffer Definitions](#protocol-buffer-definitions) * [Download the Auxiliary Protocol Buffers](#download-the-auxiliary-protocol-buffers) * [Example Protocol Buffers](#example-protocol-buffers) * [Generating Strongly Typed Clients](#generating-strongly-typed-clients) --- # Read Conversations API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/chat-apis/read-conversations) ** (2.0). Version: 1.0 On this page The Read Conversations API retrieves detailed information about specific conversations and chat interactions. 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. The `conversation_id` specifies the ID of the conversation that you want to read, and it retrieves the `Conversation` object. This object has an `id` and `turn` object which includes the `id` of the turn, `conversationId`, the `query` text, `answer`, and whether the turn is `enabled`. tip Check out our **interactive API Playground** that lets you experiment with this REST endpoint to read conversations in the chat history corpus. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Read Conversations Endpoint Address[​](#read-conversations-endpoint-address "Direct link to Read Conversations Endpoint Address") Vectara exposes an HTTP endpoint at the following URL to read conversations in the chat history corpus: https://api.vectara.io/v1/read-conversations The API Playground shows the full [Read Conversations](/docs/1.0/rest-api/read-conversations) REST definition. gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Read Conversations gRPC definition at [chat.proto](https://github.com/vectara/protos/blob/main/chat.proto) . * [REST Example](#rest-example) * [Read Conversations Endpoint Address](#read-conversations-endpoint-address) * [gRPC Example](#grpc-example) --- # REST APIs | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/rest) ** (2.0). Version: 1.0 On this page While gRPC provides low latency and excellent scalability, REST APISs provide a more traditional and sometimes simpler integration path. REST is often the choice for web-based applications that do not require real-time communication. API Formatting Guidelines[​](#api-formatting-guidelines "Direct link to API Formatting Guidelines") ---------------------------------------------------------------------------------------------------- You can find all of our APIs at https://api.vectara.io// The API endpoints are outlined in the various subsections of this API Reference section. These endpoints are automatically derived from the [protobuf definitions](https://github.com/vectara/protos) and take the same parameters. At a high level, the `api-endpoint` derives from [services.proto](https://github.com/vectara/protos/blob/main/services.proto) specifically, and the API parameters are in other `.proto` files. The translation from the protobuf definitions to REST is: * The only `version` currently available is `v1`. * `api-endpoint` is lowercase and has hyphens. For example, the gRPC call `CreateCorpus` in services.proto is `/create-corpus`. * API parameters can be sent in either `camelCase` or lowercase with `underscores`. For example, you could submit either `numResults` or `num_results` in the Search API. * JSON responses are always returned in `camelCase` form. API Authentication[​](#api-authentication "Direct link to API Authentication") ------------------------------------------------------------------------------- All Vectara APIs are authenticated. Indexing and Search APIs can be authenticated via [API Keys](/docs/1.0/learn/authentication/api-key-management) . However, Admin actions for creating and deleting corpora must be done via [OAuth 2.0](/docs/1.0/learn/authentication/oauth-2) . API Playground and OpenAPI Specifications[​](#api-playground-and-openapi-specifications "Direct link to API Playground and OpenAPI Specifications") ---------------------------------------------------------------------------------------------------------------------------------------------------- You can find up-to-date OpenAPI specifications at [https://docs.vectara.com/vectara-oas.yaml](https://docs.vectara.com/vectara-oas.yaml) . These REST API specifications are automatically derived from the gRPC protobuf definitions as well. You can use these with tools of your choosing like [Insomnia](https://insomnia.rest/) or [Postman](https://www.postman.com/) . 1. Download the OpenAPI YAML file. 2. Import the file into Insomonia or Postman. 3. Start making API calls directly from the tool. Want to try the REST APIs live in your browser? Head over to our our [API Playground](/docs/1.0/rest-api/vectara-rest-api) and make real-time API calls from your browser. * [API Formatting Guidelines](#api-formatting-guidelines) * [API Authentication](#api-authentication) * [API Playground and OpenAPI Specifications](#api-playground-and-openapi-specifications) --- # Rerank Search Results | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/search-apis/reranking) ** (2.0). Version: 1.0 On this page Reranking involves a process of rescoring and refining an initial set of query results to achieve a more precise ranking. It employs a machine learning model that while slower than the rapid retrieval step, offers more accurate results. We currently have two rerankers, the English reranker and the Maximal Marginal Relevance (MMR) reranker. English Cross-attentional Reranker (Scale Only)[​](#english-cross-attentional-reranker-scale-only "Direct link to English Cross-attentional Reranker (Scale Only)") -------------------------------------------------------------------------------------------------------------------------------------------------------------------- The English cross-attentional reranker is only available to Scale users and you enable it by specifying `272725717` as the `reranker_id`. In most scenarios, it makes sense to use the default query `start` value of `0` so that you're reranking all of the best initial results. You can also set `numResults` to the total number of documents you wish to rerank. The default value is `10`. Maximal Marginal Relevance (MMR) Reranker[​](#maximal-marginal-relevance-mmr-reranker "Direct link to Maximal Marginal Relevance (MMR) Reranker") -------------------------------------------------------------------------------------------------------------------------------------------------- The Maximal Marginal Relevance (MMR) reranker enables you to diversify search results to reduce redundancy while maintaining relevance to the query. Search queries often result in a collection of similar documents that, while relevant, may lack variety. MMR addresses this by reranking the results to include documents that are both relevant to your query but also different from the documents already listed in the search results. This approach provides users with a more balanced set of results as they may show different perspectives related to your query. You enable the MMR reranker by specifying the `reranker_id` as `272725718`. Having a diverse set of relevant results has different benefits depending on the use case: * In a pure search scenario, it improves user engagement with results by avoiding repetition. * In a generative AI scenario, it produces more comprehensive summaries. * Diversifying results can potentially represent all points of view in the data or reduce bias. In addition to specifying the `reranker_id` as `272725718` at query time, you also specify a `diversity bias` range between `0.0` and `1.0`. Values closer to `1.0` optimize for the most diverse results. You can also enable the Maximal Marginal Relevance Reranker in the Console UI as follows: 1. Open a corpus from the list and select the **Query** tab. 2. Click **Configure retrieval** and a navigation drawer opens. 3. Enable the **Rerank search results** option. ![Diversity Reranker](/assets/images/diversity_reranker-fdbf0c24bc98f107db12cc886bb042d4.png) 4. Enter a value between `0.0` and `1.0` in the `Diversity factor` field. 5. Close the Configure retrieval drawer and click **Reload results**. By applying the MMR Reranker to queries, users get results that are not just relevant but diverse and comprehensive. * [English Cross-attentional Reranker (Scale Only)](#english-cross-attentional-reranker-scale-only) * [Maximal Marginal Relevance (MMR) Reranker](#maximal-marginal-relevance-mmr-reranker) --- # Batch Multiple Queries | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/search-apis/batched-queries) ** (2.0). Version: 1.0 On this page Some applications may be designed to be powered by different queries in different parts of the UI. In order to decrease the number of network round trips (and thereby the net latency), you may want to batch those multiple queries with a single API call. Query Array in a Request[​](#query-array-in-a-request "Direct link to Query Array in a Request") ------------------------------------------------------------------------------------------------- This pattern can be done in Vectara by sending an array of queries in a single request, as in: { "query": [ { ... Query 1 ... }, { ... Query 2 ... }, ... ]} info When using batched queries, each query within the query array counts as a separate query for billing purposes. Batched Query Responses[​](#batched-query-responses "Direct link to Batched Query Responses") ---------------------------------------------------------------------------------------------- When you query Vectara, you get back an array of results. This array is to assist in using batched queries. { "responseSet": [ { ... Response 1 ... }, { ... Response 2 ... }, ... ]} Each response object within the `responseSet` array is directly associated with the query in the same position as the response. e.g. in this example case, the block in `Response 1` will be the results for `Query 1`. Therefore, it's important you keep track of the order of your queries in order to interpret the responses. * [Query Array in a Request](#query-array-in-a-request) * [Batched Query Responses](#batched-query-responses) --- # List Conversations API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/chat-apis/list-conversations) ** (2.0). Version: 1.0 On this page The List Conversations API lists 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. Conversation Object Definition[​](#conversation-object-definition "Direct link to Conversation Object Definition") ------------------------------------------------------------------------------------------------------------------- The `conversation` object specifies a unique turn `id`, which is the first turn in the conversation. The unique `conversation_id` then specifies the conversation within the chat history corpus. The `num_results` (default 5) specifies the maximum number of conversations to return, and `page_key` retrieves a specific page of results. Leave it blank to get the first page. tip Check out our **interactive API Playground** that lets you experiment with this REST endpoint to list conversations in the chat history corpus. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### List Conversations Endpoint Address[​](#list-conversations-endpoint-address "Direct link to List Conversations Endpoint Address") Vectara exposes an HTTP endpoint at the following URL to list conversations in the chat history corpus: https://api.vectara.io/v1/list-conversations The API Playground shows the full [List Conversations](/docs/1.0/rest-api/list-conversations) REST definition. gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full List Conversations gRPC definition at [chat.proto](https://github.com/vectara/protos/blob/main/chat.proto) . * [Conversation Object Definition](#conversation-object-definition) * [REST Example](#rest-example) * [List Conversations Endpoint Address](#list-conversations-endpoint-address) * [gRPC Example](#grpc-example) --- # Low-level Indexing API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/indexing-apis/core_indexing) ** (2.0). Version: 1.0 On this page The Low-level Indexing API provides low-level access to the semantic indexing capabilities of the Vectara platform. It focuses on document `parts` which allow for specific text and context definitions within a document. This approach differs from the [Standard Indexing API](/docs/1.0/api-reference/indexing-apis/indexing) which organizes documents into sections that have IDs, titles, and descriptions, like traditional, hierarchical document structures. This more granular control over documents enables you to tailor your indexing strategies. The Low-level Indexing API is reserved for advanced use cases and normal users should use the Standard Indexing API. tip Check out our [**interactive API Playground**](/docs/1.0/rest-api/core-index) that lets you experiment with this endpoint to index documents from your browser. ### Low-level Index Document Request and Response[​](#low-level-index-document-request-and-response "Direct link to Low-level Index Document Request and Response") The low-level indexing service accepts individual documents or messages to be indexed. In a short period of time, generally a few minutes, the new content becomes available in the search index. This index request requires the following parameters: * Customer ID * Corpus ID * Document object The response includes a `status` message and a `StorageQuota` message indicating how much quota was consumed. Document Container Definition[​](#document-container-definition "Direct link to Document Container Definition") ---------------------------------------------------------------------------------------------------------------- The `document` object contains the related textual items that are indexed. This object has a `document_id`, which must be unique among all the documents in the same corpus. It may optionally define `metadata_json`. The two fields `default_part_context` and `custom_dims` (Scale only) provide default values for the corresponding sub-document fields, should they fail to define either of these explicitly. ### Parts within a Document[​](#parts-within-a-document "Direct link to Parts within a Document") Most importantly, `parts` defines the actual text items that you want to index. The document _part_ is the atomic unit of Vectara. Every part is added to the index, and when search results are returned, each result is a document part. The `text` field defines the text and should generally be a sentence. It should not be shorter, but may be longer, up to the length of an entire paragraph, although performance may suffer. The `context` defines the context of the text. It may include any additional textual information that helps in disambiguating the meaning. For instance, it may include the preceding or following paragraphs, the chapter title, or the document title. The part metadata, held in `metadata_json`, is returned with the document part in search query results. For example, it can contain information that links the item to records in other systems. For Scale users, `custom_dims` allows you to specify additional factors that can be used at query time to control the ranking of results. The dimensions must be defined ahead of time for the corpus, or else they'll be ignored. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Low-level Indexing REST Endpoint[​](#low-level-indexing-rest-endpoint "Direct link to Low-level Indexing REST Endpoint") Vectara exposes a REST endpoint at the following URL to index content into a corpus: https://api.vectara.io/v1/core-index The API Playground shows the full [Low-level Indexing REST definition](/docs/1.0/rest-api/core-index) . gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Low-level Indexing gRPC definition at [indexing\_core.proto](https://github.com/vectara/protos/blob/main/indexing_core.proto) . A request to add data into a corpus consists of three key pieces of information: the customer ID, the corpus ID, and the data itself, represented as a `CoreDocument` message. The reply from the server consists of nothing yet. Note that the reply does not block. In other words, the information in the request is not yet available in the index when the RPC returns. The full definition also shows the `CoreDocument` container format, which has metadata about the document, and parts within the document as `CoreDocumentPart`. * [Low-level Index Document Request and Response](#low-level-index-document-request-and-response) * [Document Container Definition](#document-container-definition) * [Parts within a Document](#parts-within-a-document) * [REST Example](#rest-example) * [Low-level Indexing REST Endpoint](#low-level-indexing-rest-endpoint) * [gRPC Example](#grpc-example) --- # Delete Documents API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/indexing-apis/deleting-documents) ** (2.0). Version: 1.0 On this page The Delete Documents API lets you delete a document from a corpus. To verify that the document no longer exists in the corpus, use the List Documents endpoint. tip Check out our [**interactive API Playground**](/docs/1.0/rest-api/delete) that enables you to experiment with this REST endpoint. You can delete a file from a corpus directly from your browser or copy the curl for your command line. ### Delete Document Request and Response[​](#delete-document-request-and-response "Direct link to Delete Document Request and Response") A request to delete a document from a corpus consists of three key pieces of information: * `customer_id` * `corpus_id` * `document_id` The reply on successful deletion is `{}`. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Delete Documents Endpoint Address[​](#delete-documents-endpoint-address "Direct link to Delete Documents Endpoint Address") Vectara exposes a REST endpoint at the following URL to delete content from a corpus: https://api.vectara.io/v1/delete-doc The API Playground shows the full [Delete Documents REST definition](/docs/1.0/rest-api/delete) . gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the Delete Document gRPC definition at [common.proto](https://github.com/vectara/protos/blob/main/common.proto) . The reply from the server consists of nothing yet. Note that while the operation is not completely synchronous (the document may still be returned in query results), the platform typically removes the document within a few seconds, though it may take longer for Growth accounts. ### Java and Python Examples[​](#java-and-python-examples "Direct link to Java and Python Examples") The code snippet belows illustrates how to delete a document from a corpus in Java or Python. For information on how to get the call credentials and metadata, please consult [The OAuth 2.0 documentation](/docs/1.0/learn/authentication/oauth-2) . * Java * Python # Create the document deletion request.request = common_pb2.DeleteDocumentRequest()request.customer_id = customer_idrequest.corpus_id = _CORPUS_IDrequest.document_id = "en.wikipedia.org/wiki/California"# Create the gRPC stub.stub = services_pb2_grpc.IndexServiceStub( grpc.secure_channel("indexing.vectara.io:443", grpc.ssl_channel_credentials()))# Send the request to the server.response = stub.Delete(request, credentials=call_credentials, metadata=[('customer-id-bin', packed_customer_id)]) indexingStub.withCallCredentials(credentials(tokenSupplier.get().getOrDie())) .withDeadlineAfter(30, TimeUnit.SECONDS) // Always set a deadline. .delete( DeleteDocumentRequest .newBuilder() .setCustomerId(customerId) .setCorpusId(corpusId) .setDocumentId("en.wikipedia.org/wiki/California") .build()); ### gRPC Status Codes[​](#grpc-status-codes "Direct link to gRPC Status Codes") The server returns the following [gRPC status codes](https://grpc.github.io/grpc/core/md_doc_statuscodes.html) : * `INTERNAL`: An internal error code indicates a failure inside the platform, and an immediate retry may not succeed. * `UNAVAILABLE`: The service is temporarily unavailable, and the operation should be retried, preferably with a backoff. note The deletion operation is idempotent, so it is fine to re-apply. * [Delete Document Request and Response](#delete-document-request-and-response) * [REST Example](#rest-example) * [Delete Documents Endpoint Address](#delete-documents-endpoint-address) * [gRPC Example](#grpc-example) * [Java and Python Examples](#java-and-python-examples) * [gRPC Status Codes](#grpc-status-codes) --- # Standard Indexing API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/indexing-apis/indexing) ** (2.0). Version: 1.0 On this page The first step in using Vectara is to index a set of related documents or content into a corpus. Indexing a document enables you to make data available for search and retrieval more efficiently. The Standard Indexing API is recommended for applications where documents already have a clear and consistent structure. Our Standard Indexing capability transforms this structured data into a format that enables the data to become easily searchable in just a few seconds. We also support a variety of data formats by allowing you to specify multiple document attributes and metadata. tip * Check out our [**interactive API Playground**](/docs/1.0/rest-api/index) that shows the full Index REST definition and lets you experiment with this endpoint to index documents from your browser. * We also provide REST Index examples in [**C#**](/docs/1.0/getting-started-samples/RestIndexData.cs) , [**Java**](/docs/1.0/getting-started-samples/RestIndex.java) , [**NodeJS**](/docs/1.0/getting-started-samples/index_document.js) , [**PHP**](/docs/1.0/getting-started-samples/indexDocument.php) , and [**Python**](/docs/1.0/getting-started-samples/rest_index_document.py) . ### Index Document Request and Response[​](#index-document-request-and-response "Direct link to Index Document Request and Response") The request that adds data into a corpus provides essential information about the document you want to index. A document is a piece of coherent textual matter. This index request requires the following parameters: * Customer ID * Corpus ID * Document object The response includes a `status` message and a `StorageQuota` message indicating how much quota was consumed. An `ALREADY_EXISTS` status code indicates how much quota would have been consumed. note The storage quota object returns the number of characters consumed and the number of metadata characters consumed. The total quota consumed is simply the sum of both values. Document Object Definition[​](#document-object-definition "Direct link to Document Object Definition") ------------------------------------------------------------------------------------------------------- A `document` object encapsulates the information about the data that you want to index. A **document** in Vectara is very flexible because it represent a short tweet or book with thousands of pages. This object has a `document_id` which must be unique among all the documents in the same corpus. The document may optionally speciify a `title`, `description`, and `metadata`. The core of the document is also structured in `sections` that can include unique identifiers, titles, strings, metadata, and so on. The `custom_dims` field (Scale only) provides default values for the corresponding section fields, should they fail to define them explicitly. Most importantly, `section` defines the actual textual matter. Documents can also have multiple sections. ### Section within a Document[​](#section-within-a-document "Direct link to Section within a Document") A section represents an organizational subunit within a document. Its definition is recursive, since a section can be composed of further `sections`. The actual textual content, which is at least a single sentence, but might span several paragraphs or more, is stored in `text`. Like a document, it may optionally specify a `title`, which semantically corresponds to a section header or chapter title. Sections provide flexibility, and it's possible that a section specifies a title, but relegates the text to subsections. For instance, consider the following simple document excerpt from Wikipedia: > History[​](#history "Direct link to History") > > ---------------------------------------------- > > ### First inhabitants[​](#first-inhabitants "Direct link to First inhabitants") > > Settled by successive waves of arrivals during at least the last 13,000 years,\[41\] California was one of the most culturally and linguistically diverse areas in pre-Columbian North America. Various estimates of the native population range from 100,000 to 300,000.\[42\] The indigenous peoples of California included more than 70 distinct ethnic groups of Native Americans, ranging from large, settled populations living on the coast to groups in the interior. California groups also were diverse in their political organization with bands, tribes, villages, and on the resource-rich coasts, large chiefdoms, such as the Chumash, Pomo and Salinan. Trade, intermarriage and military alliances fostered many social and economic relationships among the diverse groups. > > ### Spanish rule[​](#spanish-rule "Direct link to Spanish rule") > > The first Europeans to explore the California coast were the members of a Spanish sailing expedition led by Portuguese captain Juan RodrΓ­guez Cabrillo; they entered San Diego Bay on September 28, 1542, and reached at least as far north as San Miguel Island. Privateer and explorer Francis Drake explored and claimed an undefined portion of the California coast in 1579, landing north of the future city of San Francisco. The first Asians to set foot on what would be the United States occurred in 1587, when Filipino sailors arrived in Spanish ships at Morro Bay. SebastiΓ‘n VizcaΓ­no explored and mapped the coast of California in 1602 for New Spain, sailing as far north as Cape Mendocino. This could be represented as a top-level section titled "History" and no text. It would contain two sections, "First inhabitants" and "Spanish rule" that both specify text. The part metadata, held in `metadata_json`, is returned in search query results. It can contain, for example, information that links the item to records in other systems. For Scale only users, `custom_dims` allows you to specify additional factors that can be used at query time to control the ranking of results. The custom dimensions must be defined ahead of time for the corpus, or else they'll be ignored. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Standard Indexing REST Endpoint[​](#standard-indexing-rest-endpoint "Direct link to Standard Indexing REST Endpoint") Vectara exposes a REST endpoint at the following URL to index content into a corpus: https://api.vectara.io/v1/index The API Playground shows the full [Standard Indexing REST definition](/docs/1.0/rest-api/index) . gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Standard Indexing gRPC definition at [indexing.proto](https://github.com/vectara/protos/blob/main/indexing.proto) . For `IndexDocumentRequest`, the reply does not block. The information in the request is not necessarily available in the index when the RPC returns. In most cases, it becomes available within a second. The full definition also shows the `Document` format, and a `Section` within the document, including metadata about the section. ### Custom Dimensions Use Cases (Scale only)[​](#custom-dimensions-use-cases-scale-only "Direct link to Custom Dimensions Use Cases (Scale only)") Custom dimensions are a powerful Vectara capability for our Scale users. Custom dimensions enable you to attach numeric factors to every item in the index, which affect its final ranking during searches. Some example use cases include: 1. Define the authoritativeness of the content. For example, content with 100 upvotes can be ranked higher than content with no upvotes and 10 downvotes. 2. Indicate the source of the content. If there are N sources, this is usually done by defining N custom dimensions, and treating them as boolean 0-1 fields. This allows weighting results based on source, or even excluding certain sources altogether. For example, content from a government FAQ would be rated higher than content from a user forum. 3. Define the geography in which content is relevant. 4. Indicate the publication date which makes it easy to weight more recent results higher. For more information on how to use custom dimensions, refer to the [Custom Dimensions Usage Documentation](/docs/1.0/learn/semantic-search/add-custom-dimensions) * [Index Document Request and Response](#index-document-request-and-response) * [Document Object Definition](#document-object-definition) * [Section within a Document](#section-within-a-document) * [REST Example](#rest-example) * [Standard Indexing REST Endpoint](#standard-indexing-rest-endpoint) * [gRPC Example](#grpc-example) * [Custom Dimensions Use Cases (Scale only)](#custom-dimensions-use-cases-scale-only) --- # Query API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/api-reference/search-apis/search) ** (2.0). Version: 1.0 On this page The Query API lets you perform a query while defining its parameters that specify the query text, pagination details, metadata filters, and other search settings that enable application builders to tailor their queries to specific use cases. After you index data into one or more corpora, you can run queries and display the results. This page provides a detailed reference for how to run queries and also describes some of Vectara's capabilities in metadata filtering, reranking, Retrieval Augmented Generation (RAG), and hybrid search. tip Check out our [**interactive API Playground**](/docs/1.0/rest-api/query) that lets you experiment with this REST endpoint to send queries. Query Request Body and Response[​](#query-request-body-and-response "Direct link to Query Request Body and Response") ---------------------------------------------------------------------------------------------------------------------- The Query request body specifies different parameters that ask questions about the data within corpora. The Query request requires the following parameters: * `query` - Contains your question and number of results to return. * `corpusKey` - Specifies which corpora to run the query The query response message encapsulates a single query result. It is a subdocument provided at indexing time. The `text` is the subdocument text, the `score` indicates how well the text answers the query (higher scores are better). The `metadata` list holds any subdocument-level metadata that was stored with the item at indexing time. The `corpus_key` indicates which corpus the result came from: recall that a single query can execute against multiple corpora. Finally, the `document_index` points at a specific document within the enclosing response set's `document` array. This is useful for retrieving the document id and document-level metadata. Query Definition[​](#query-definition "Direct link to Query Definition") ------------------------------------------------------------------------- A single query consists of a **query**, which is specified in plain text. For example, _"Where can I buy the latest iPhone?"_. Optionally, the **query context** provides additional information that the system may use to refine the results. For example, _"The Apple store near my house is closed due to Covid."_ The `start` field controls the starting position within the list of results, while `num_results` dictates how many results are returned. Thus, setting `start=5` and `num_results=20` would return twenty results beginning at position five. These fields are mainly used to provide pagination. The `corpusKey` specifies a list of corpora against which to run the query. While it's most often the case that a query is run against a single corpus, it's sometimes useful to run against several in parallel. Finally, the **reranking configuration** enables reranking of results, to further increase relevance in certain scenarios. For details about our English cross-attentional (Scale only) and Maximal Marginal Relevance (MMR) rerankers, see [Reranking](/docs/1.0/api-reference/search-apis/reranking) . Corpus Key Definition[​](#corpus-key-definition "Direct link to Corpus Key Definition") ---------------------------------------------------------------------------------------- The `corpusKey` specifies the ID of the corpus being searched. The `metadata_filter` allows specifying a predicate expression that restricts the search to a part of the corpus. The filter is written in a simplified SQL dialect and can reference metadata that was marked as filterable during corpus creation. note See the [**Filter Expressions Overview**](/docs/1.0/learn/metadata-search-filtering/filter-overview) for a description of their syntax, and [**Corpus Administration**](/docs/1.0/api-reference/admin-apis/admin) to learn how referenceable metadata is specified during corpus creation. By default, Vectara only uses its neural/semantic retrieval model, and does not attempt to use keyword matching. To enable [hybrid search](/docs/1.0/learn/hybrid-search) with a mix of both keyword and neural results, edit the `lambda` value. If the corpus specifies custom dimensions (Scale only), weights can be assigned to each dimension as well. Finally, it's possible to override the semantic interpretation of the query string. Usually, the default settings for the corpus are sufficient. In more advanced scenarios, it's desirable to force it to be treated as a query, or, more rarely, as a response. Query Summarization Request - Retrieval Augmented Generation[​](#query-summarization-request---retrieval-augmented-generation "Direct link to Query Summarization Request - Retrieval Augmented Generation") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To use Retrieval Augmented Generation (RAG), which Vectara also refers to as "Grounded Generation" -- our groundbreaking way of producing generative summaries on top of your own data -- you can submit a `SummarizationRequest` alongside your query. This produces a `summary` that attempts to answer the end-user's question, citing the results as references. For more information, read about [Retrieval Augmented Generation](/docs/1.0/learn/grounded-generation/grounded-generation-overview) . The `summary` object enables you to tailor the results of the query summarization. Growth users can specify the `maxSummarizedResults` and `responseLang`. Factual Consistency Score[​](#factual-consistency-score "Direct link to Factual Consistency Score") ---------------------------------------------------------------------------------------------------- The Factual Consistency Score, based on a more advanced version of [Hughes Hallucination Evaluation Model (HHEM)](https://huggingface.co/vectara/hallucination_evaluation_model) , enables you to evaluate the likelihood of an AI-generated summary being factually correct based on search results. This calibrated score can range from `0.0` to `1.0`. A higher scores indicates a greater probability of being factually accurate, while a lower score indicates a greater probability of hallucinations. In your summarization request, set the `factual_consistency_score` field to `true`. The Factual Consistency Score returns a calibrated value in the `factual_consistency` field of the summary message. The score field contains the value between `0.0` and `1.0`. For example, a score of `0.95` suggests a 95% likelihood that the summary is free of hallucinations and would align with the original content. A lower score of `0.40` indicates a 40% chance which would be probably much less factually accurate. We suggest starting with a setting of `0.5` as an initial guideline for cutoffs between good and bad. Advanced Summarization Customization Options[​](#advanced-summarization-customization-options "Direct link to Advanced Summarization Customization Options") ------------------------------------------------------------------------------------------------------------------------------------------------------------- [Scale users](https://vectara.com/pricing/) have access to more powerful summarization capabilities, which present a powerful toolkit for tailoring summarizations to specific application and user needs. The `summarizerPromptName` allows you to specify one of our [available summarizers](/docs/1.0/learn/grounded-generation/select-a-summarizer) . Use `promptText` to override the default prompt text with a [custom prompt](/docs/1.0/prompts/vectara-prompt-engine) . Your use case might require a chatbot to be more human like, so you decide to create a custom response format that behaves more playfully in a conversation or summary. The `debug` option lets you view detailed logs to help in troubleshooting and optimization. The `responseChars` lets you control the length of the summary, but note that it is **not a hard limit** like with the `maxTokens` parameter. The `modelParams` object provides even more fine-grained controls for the summarizer model: * `maxToken` specifies a hard limit on the number of characters in a response. This value supercedes the `responseChars` parameter in the `summary` object. * `temperature` indicates whether you want the summarization to not be creative at all `0.0`, or for the summarization to take more creative liberties as you approach the maximium value of `1.0`. * `frequencyPenalty` provides even more granular control to help ensure that the summarization decreases the likelihood of repeating words. The values range from `0.0` to `1.0` * `presencePenalty` provides more control over whether you want the summary to include new topics. The values also range from `0.0` to `1.0`. By leveraging these advanced capabilities, application builders can fine-tune the behavior and output style of the summarizer to align with your unique application requirements. ### Chat Conversation Located within the Summary[​](#chat-conversation-located-within-the-summary "Direct link to Chat Conversation Located within the Summary") If you enabled chat on the corpus, the `summary` object contains a conversation from [Vectara Chat](/docs/1.0/api-reference/chat-apis/chat-apis-overview) which includes a `conversationId`. You enable Vectara Chat by setting the `store` value to `true`. The [Vectara Chat APIs](/docs/1.0/api-reference/chat-apis/chat-apis-overview) have more details about conversations. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Query API Endpoint Address[​](#query-api-endpoint-address "Direct link to Query API Endpoint Address") Vectara exposes a REST endpoint at the following URL to search content from a corpus: https://api.vectara.io/v1/query The API Playground shows the full [Query REST definition](/docs/1.0/rest-api/query) . gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Query gRPC definition at [serving.proto](https://github.com/vectara/protos/blob/main/serving.proto) . ### Query Service and Request[​](#query-service-and-request "Direct link to Query Service and Request") The definition shows details about the `query` service. The system accepts a `query` and returns a response, which contains a list of results. For efficiency, one or more queries can be batched into a single request. `query` contains the search terms that the system needs to match against the data. Then `ContextConfig` specifies the amount of text or number of sentences before and after the result snippet. #### Corpus Key[​](#corpus-key "Direct link to Corpus Key") The `corpus_key` allows the query to be executed across multiple corpora. The `CorpusKey` identifies a specific corpus or corpora to include in the query. Specifying the `customer_id` is optional, since it defaults to the customer attached to the gRPC request. #### Summarization Request Example[​](#summarization-request-example "Direct link to Summarization Request Example") The full Query definition provides the detailed summary request. When Vectara responds with the list of results that most semantically answer the user, it will also then produce a summary of the results with its sources cited. For more details on Retrieval Augmented Generation, have a look at the [chatbots and grounded generation overview](/docs/1.0/learn/grounded-generation/grounded-generation-overview) . The summary comes back in a format where the `text` contains a summary of the relevant results to the given search with those relevant results included as cited sources. Vectara cites these by `[number]` format. For example, if the 1st result is in the summary, it is cited as `[1]`. #### ResponseSet[​](#responseset "Direct link to ResponseSet") The response set groups a list of responses, sorted in order of score, together with a list of `statuses` and enclosing `documents`. Since it's possible for several results to come from the same document, the length of the document list may be less than the length of the response list. #### Attribute[​](#attribute "Direct link to Attribute") Attribute represents a named piece of metadata. Both the `name` and its `value` are string typed. message Attribute { string name = 5; string value = 10;} #### Batch Query and Response[​](#batch-query-and-response "Direct link to Batch Query and Response") The batch query request and response messages simply aggregate several individual queries and response sets, respectively. The response sets will match the queries in both number and order. For example, the third response set in the batch response will correspond with the third query in the batch request. message BatchQueryRequest { repeated QueryRequest query = 5;}message BatchQueryResponse { repeated ResponseSet response_set = 5; repeated Status status = 1000;} Advanced Scenarios[​](#advanced-scenarios "Direct link to Advanced Scenarios") ------------------------------------------------------------------------------- ### Search Multiple Corpora[​](#search-multiple-corpora "Direct link to Search Multiple Corpora") There are situations where searching multiple corpora simultaneously can be beneficial. To do this effectively, you need two things: 1. **Proper Permissions:** Setting up an API Key that grants access to all corpora that you intend to search. 2. **Query Body Adjustment:** Specific modifications to the query body as outlined below. The query body modification that's necessary is that `corpusKey` can take an array of objects. #### Search a Single Corpus Example[​](#search-a-single-corpus-example "Direct link to Search a Single Corpus Example") So if you're currently searching 1 corpus as follows: ..."corpusKey": [ { "customerId": 1234, "corpusId": 5678, "semantics": 0, "metadataFilter": "", "dim": [] }]... #### Search Multiple Corpora Example[​](#search-multiple-corpora-example "Direct link to Search Multiple Corpora Example") As long as your API key has permissions to each of these corpora, you can search multiple corpora at once as follows: ..."corpusKey": [ { "customerId": 1234, "corpusId": 5678, "semantics": 0, "metadataFilter": "", "dim": [] }, { "customerId": 1234, "corpusId": 9876, "semantics": 0, "metadataFilter": "", "dim": [] }]... In this example, the `query` returns results across the queried corpora. The `corpusKey` is returned in the response for each document if you need to use it in your application. * [Query Request Body and Response](#query-request-body-and-response) * [Query Definition](#query-definition) * [Corpus Key Definition](#corpus-key-definition) * [Query Summarization Request - Retrieval Augmented Generation](#query-summarization-request---retrieval-augmented-generation) * [Factual Consistency Score](#factual-consistency-score) * [Advanced Summarization Customization Options](#advanced-summarization-customization-options) * [Chat Conversation Located within the Summary](#chat-conversation-located-within-the-summary) * [REST Example](#rest-example) * [Query API Endpoint Address](#query-api-endpoint-address) * [gRPC Example](#grpc-example) * [Query Service and Request](#query-service-and-request) * [Advanced Scenarios](#advanced-scenarios) * [Search Multiple Corpora](#search-multiple-corpora) --- # Vectara Answer | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/build-apps/vectara-answer) ** (2.0). Version: 1.0 Vectara Answer provides a configurable sample UI that you can use as a starting point. This UI enables users to create custom conversational search applications, such as chatbots, semantic search, and workplace search by connecting to your ingested data. This project provides example code for a modern user-interface for Vectara GenAI conversational search. [Go to the code repository](https://github.com/vectara/vectara-answer) for information about how to use Vectara Answer. --- # Asynchronous Grounded Generation | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/common-use-cases/chatbots-grounded-generation/async-generative) ** (2.0). Version: 1.0 Generating summaries is an operation which is heavily time-consuming: often taking on the order of a few seconds. In many applications, it can be advantageous to return the result list first while waiting for the summary to be completed. In order to support fast response times for the initial result list in addition to the slower generative summary, supports an asynchronous interface for requesting the summary. Today, this interface is _only_ available in gRPC requests. In the future, we plan on releasing a similar feature for REST users via an alternative mechanism. To use asynchronous summarization over gRPC, you can use 's `future_id`s. When you first send a request that includes a generative summary, the immediate response will include a `future_id`. You can then look for a future `QueryResponsePart` for associated messages of the given `future_id` to look for `Summary` response parts that matched the given query. --- # Common Use Cases | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/common-use-cases/filtering-by-metadata/filter-common-use-cases) ** (2.0). Version: 1.0 In addition to the [built in metadata that you can filter on](/docs/learn/metadata-search-filtering/ootb-metadata-filters) in Vectara, there are several common use cases that can be handled via metadata: Date filtering (before/after) ============================= Often, documents will have dates associated with them: the creation date, last modified, date, or ingest date that can prove useful to filter by. To use these in Vectara, first convert the dates to epoch seconds and then use an [integer](/docs/api-reference/search-apis/sql/data-types) Indexing checkpoints ==================== A frequent use case is --- # Batching Multiple Queries | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/common-use-cases/batched-queries) ** (2.0). Version: 1.0 On this page Some applications may be designed to be powered by different queries in different parts of the UI. In order to decrease the number of network round trips (and thereby the net latency), you may want to issue those multiple queries to the system with a single API call. This pattern can be done in Vectara by sending an array of queries in a single request, as in: { "query": [ { ... Query 1 ... }, { ... Query 2 ... }, ... ]} info When using batched queries, each query within the query array counts as a separate query for billing purposes. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- When you a query Vectara, you get back an array of results This is to assist in using a [Batched Query](/docs/api-reference/search-apis/batched-queries) , { "responseSet": [ { ... Response 1 ... }, { ... Response 2 ... }, ... ]} Each response object within the `responseSet` array is directly associated with the query in the same position as the response. e.g. in this example case, the block in `Response 1` will be the results for `Query 1`. Therefore, it's important you keep track of the order of your queries in order to interpret the responses. * [Responses](#responses) --- # Vectara Ingest | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/build-apps/vectara-ingest) ** (2.0). Version: 1.0 Vectara Ingest crawls datasets from pre-built crawlers (websites, RSS feeds, Jira, Notion, Docusaurus) and ingests them into Vectara. This sample ingestion framework includes preconfigured templates for pulling data from many popular data sources. [Go to the code repository](https://github.com/vectara/vectara-ingest) for information about how to use Vectara Ingest. --- # React-Chatbot | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/build-apps/react-chatbot) ** (2.0). Version: 1.0 ![Screenshot of React-Chatbot chat interface](/assets/images/react_chatbot-887133d08ecc0048e923a6cde66422ac.jpg) React-Chatbot is a UI widget for adding Vectara-powered chatbot to your React apps with a few lines of code. [Interact with the demo](https://vectara.github.io/react-chatbot/) to see how it works. [Go to the code repository](https://github.com/vectara/react-chatbot) for information about how to use React-Chatbot. --- # Stream Query API Definition | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 On this page The Stream Query API enables continuous streamed responses as data becomes available, improving responsiveness and reducing latency. Instead of receiving a complete response like with the [Standard Query API](/docs/1.0/api-reference/search-apis/search) , consumers receive partial responses in this order: 1. Search results. 2. If summarization is enabled, chunks of the summary, like "This", "is", "a", "summary". 3. If the [Factual Consistency Score (FCS)](#factual-consistency-score) is enabled, then the FCS is the final response. This streaming approach is beneficial when generating summaries using LLMs like GPT-4, which can have significant latencies of 5-10 seconds. The Standard Query API makes users wait for the full summarization process before receiving any results. Streaming processes the summary request with near-zero latency, significantly enhancing the user experience. tip Check out our [**interactive API Playground**](/docs/1.0/rest-api/stream-query) that lets you experiment with this REST endpoint to stream query responses. Stream Query Request Body[​](#stream-query-request-body "Direct link to Stream Query Request Body") ---------------------------------------------------------------------------------------------------- The Stream Query API has the same request parameters as the [Standard Query API](/docs/1.0/api-reference/search-apis/search) . The `stream-query` endpoint enables streaming. Use this endpoint instead of the standard `query` endpoint. The Stream Query request body specifies different parameters that ask questions about the data within corpora. The Stream Query request requires the following parameters: * `query` - Contains your question and number of results to return. * `corpusKey` - Specifies which corpora to run the query The query response message encapsulates a single query result. It is a subdocument provided at indexing time. The `text` is the subdocument text, the `score` indicates how well the text answers the query (higher scores are better). The `metadata` list holds any subdocument-level metadata that was stored with the item at indexing time. The `corpus_key` indicates which corpus the result came from: recall that a single query can execute against multiple corpora. Finally, the `document_index` points at a specific document within the enclosing response set's `document` array. This is useful for retrieving the document id and document-level metadata. Stream Query Response Types[​](#stream-query-response-types "Direct link to Stream Query Response Types") ---------------------------------------------------------------------------------------------------------- Each streamed chunk contains a portion of the summary text, identified by a unique `future_id`. Once the full summary is streamed, you receive a final response with the `done` field set to `true`, allowing flexible handling and processing of results. If you enabled the Factual Consistency Score, this value appears after the summary shows `done` as `true`. The Stream Query API request has three different types of responses: ### Preamble Response[​](#preamble-response "Direct link to Preamble Response") This initial response serves as a preamble, like a "heads up." It contains the `batchQueryResponse` with placeholders for different parts of the response, such as search results or the summary. These placeholders help you correlate the subsequent streamed chunks with their respective parts. ### Search Results Response[​](#search-results-response "Direct link to Search Results Response") This second response type contains the search results as the `batchQueryResponse` populates with these results in real time. ### Streamed Parts of the Summary Response[​](#streamed-parts-of-the-summary-response "Direct link to Streamed Parts of the Summary Response") The third response type, which streams until you get the final `done` value, returns the subsequent streamed chunks of the summary. Each response has a `batchQueryResponse` that contains a portion of the `summary` text. Combining the Streamed Summary Response[​](#combining-the-streamed-summary-response "Direct link to Combining the Streamed Summary Response") ---------------------------------------------------------------------------------------------------------------------------------------------- The consuming code must combine the stream's chunks as it receives them. The best method for doing so will depend on the language being used. ### JavaScript[​](#javascript "Direct link to JavaScript") If the consuming code is JavaScript, we recommend using our [Stream-Query-Client](https://www.npmjs.com/package/@vectara/stream-query-client) to mediate requests to the Stream Query API. It will handle the complexity of combining the streamed chunks for you. To refer to how this is done, see the [Stream-Query-Client source code](https://github.com/vectara/stream-query-client) . Query Definition[​](#query-definition "Direct link to Query Definition") ------------------------------------------------------------------------- A single query consists of a **query**, which is specified in plain text. For example, _"Where can I buy the latest iPhone?"_. Optionally, the **query context** provides additional information that the system may use to refine the results. For example, _"The Apple store near my house is closed due to Covid."_ The `start` field controls the starting position within the list of results, while `num_results` dictates how many results are returned. Thus, setting `start=5` and `num_results=20` would return twenty results beginning at position five. These fields are mainly used to provide pagination. The `corpusKey` specifies a list of corpora against which to run the query. While it's most often the case that a query is run against a single corpus, it's sometimes useful to run against several in parallel. Finally, the **reranking configuration** enables reranking of results, to further increase relevance in certain scenarios. For details about our English cross-attentional (Scale only) and Maximal Marginal Relevance (MMR) rerankers, see [Reranking](/docs/api-reference/search-apis/reranking) . Corpus Key Definition[​](#corpus-key-definition "Direct link to Corpus Key Definition") ---------------------------------------------------------------------------------------- The `corpusKey` specifies the ID of the corpus being searched. The `metadata_filter` allows specifying a predicate expression that restricts the search to a part of the corpus. The filter is written in a simplified SQL dialect and can reference metadata that was marked as filterable during corpus creation. note See the [**Filter Expressions Overview**](/docs/1.0/learn/metadata-search-filtering/filter-overview) for a description of their syntax, and [**Corpus Administration**](/docs/1.0/api-reference/admin-apis/admin) to learn how referenceable metadata is specified during corpus creation. By default, Vectara only uses its neural/semantic retrieval model, and does not attempt to use keyword matching. To enable [hybrid search](/docs/1.0/learn/hybrid-search) with a mix of both keyword and neural results, edit the `lambda` value. If the corpus specifies custom dimensions (Scale only), weights can be assigned to each dimension as well. Finally, it's possible to override the semantic interpretation of the query string. Usually, the default settings for the corpus are sufficient. In more advanced scenarios, it's desirable to force it to be treated as a query, or, more rarely, as a response. Query Summarization Request - Retrieval Augmented Generation[​](#query-summarization-request---retrieval-augmented-generation "Direct link to Query Summarization Request - Retrieval Augmented Generation") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To use Retrieval Augmented Generation (RAG), which Vectara also refers to as "Grounded Generation" -- our groundbreaking way of producing generative summaries on top of your own data -- you can submit a `SummarizationRequest` alongside your query. This produces a `summary` that attempts to answer the end-user's question, citing the results as references. For more information, read about [Retrieval Augmented Generation](/docs/1.0/learn/grounded-generation/grounded-generation-overview) . The `summary` object enables you to tailor the results of the query summarization. Growth users can specify the `maxSummarizedResults` and `responseLang`. Factual Consistency Score[​](#factual-consistency-score "Direct link to Factual Consistency Score") ---------------------------------------------------------------------------------------------------- The Factual Consistency Score, based on a more advanced version of [Hughes Hallucination Evaluation Model (HHEM)](https://huggingface.co/vectara/hallucination_evaluation_model) , enables you to evaluate the likelihood of an AI-generated summary being factually correct based on search results. This calibrated score can range from `0.0` to `1.0`. A higher scores indicates a greater probability of being factually accurate, while a lower score indicates a greater probability of hallucinations. In your summarization request, set the `factual_consistency_score` field to `true`. The Factual Consistency Score returns a calibrated value in the `factual_consistency` field of the summary message. The score field contains the value between `0.0` and `1.0`. For example, a score of `0.95` suggests a 95% likelihood that the summary is free of hallucinations and would align with the original content. A lower score of `0.40` indicates a 40% chance which would be probably much less factually accurate. We suggest starting with a setting of `0.5` as an initial guideline for cutoffs between good and bad. Advanced Summarization Customization Options[​](#advanced-summarization-customization-options "Direct link to Advanced Summarization Customization Options") ------------------------------------------------------------------------------------------------------------------------------------------------------------- [Scale users](https://vectara.com/pricing/) have access to more powerful summarization capabilities, which present a powerful toolkit for tailoring summarizations to specific application and user needs. The `summarizerPromptName` allows you to specify one of our [available summarizers](/docs/1.0/learn/grounded-generation/select-a-summarizer) . Use `promptText` to override the default prompt text with a [custom prompt](/docs/1.0/prompts/vectara-prompt-engine) . Your use case might require a chatbot to be more human like, so you decide to create a custom response format that behaves more playfully in a conversation or summary. The `debug` option lets you view detailed logs to help in troubleshooting and optimization. The `responseChars` lets you control the length of the summary, but note that it is **not a hard limit** like with the `maxTokens` parameter. The `modelParams` object provides even more fine-grained controls for the summarizer model: * `maxToken` specifies a hard limit on the number of characters in a response. This value supercedes the `responseChars` parameter in the `summary` object. * `temperature` indicates whether you want the summarization to not be creative at all `0.0`, or for the summarization to take more creative liberties as you approach the maximium value of `1.0`. * `frequencyPenalty` provides even more granular control to help ensure that the summarization decreases the likelihood of repeating words. The values range from `0.0` to `1.0` * `presencePenalty` provides more control over whether you want the summary to include new topics. The values also range from `0.0` to `1.0`. By leveraging these advanced capabilities, application builders can fine-tune the behavior and output style of the summarizer to align with your unique application requirements. ### Chat Conversation Located within the Summary[​](#chat-conversation-located-within-the-summary "Direct link to Chat Conversation Located within the Summary") If you enabled chat on the corpus, the `summary` object contains a conversation from [Vectara Chat](/docs/1.0/api-reference/chat-apis/chat-apis-overview) which includes a `conversationId`. You enable Vectara Chat by setting the `store` value to `true`. The [Vectara Chat APIs](/docs/1.0/api-reference/chat-apis/chat-apis-overview) have more details about conversations. REST Example[​](#rest-example "Direct link to REST Example") ------------------------------------------------------------- ### Stream Query API Endpoint Address[​](#stream-query-api-endpoint-address "Direct link to Stream Query API Endpoint Address") Vectara exposes a REST endpoint at the following URL to search content from a corpus: https://api.vectara.io/v1/stream-query The API Playground shows the full [Stream Query REST definition](/docs/1.0/rest-api/stream-query) . gRPC Example[​](#grpc-example "Direct link to gRPC Example") ------------------------------------------------------------- You can find the full Stream Query gRPC definition at [serving.proto](https://github.com/vectara/protos/blob/main/serving.proto) . * [Stream Query Request Body](#stream-query-request-body) * [Stream Query Response Types](#stream-query-response-types) * [Preamble Response](#preamble-response) * [Search Results Response](#search-results-response) * [Streamed Parts of the Summary Response](#streamed-parts-of-the-summary-response) * [Combining the Streamed Summary Response](#combining-the-streamed-summary-response) * [JavaScript](#javascript) * [Query Definition](#query-definition) * [Corpus Key Definition](#corpus-key-definition) * [Query Summarization Request - Retrieval Augmented Generation](#query-summarization-request---retrieval-augmented-generation) * [Factual Consistency Score](#factual-consistency-score) * [Advanced Summarization Customization Options](#advanced-summarization-customization-options) * [Chat Conversation Located within the Summary](#chat-conversation-located-within-the-summary) * [REST Example](#rest-example) * [Stream Query API Endpoint Address](#stream-query-api-endpoint-address) * [gRPC Example](#grpc-example) --- # Create-UI | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/build-apps/create-ui) ** (2.0). Version: 1.0 ![Create-UI command line interface](/assets/images/create_ui-3127e6b8f7336985bb6384a69fa79bad.jpg) Use the Create-UI code generator to create a working React codebase for a range of generative and semantic search UIs. [Interact with the demo](https://vectara.github.io/create-ui/) to see how it works. [Go to the code repository](https://github.com/vectara/create-ui) for information about how to use Create-UI. --- # Stream-Query-Client | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/build-apps/stream-query-client) ** (2.0). Version: 1.0 Stream-Query-Client is the easiest way to use Vectara's Stream Query API in your JavaScript applications. Simply provide a query configuration and a callback to instantly receive stream updates. [Go to the code repository](https://github.com/vectara/stream-query-client) for information about how to use Vectara Answer. --- # App Building Tools | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/build-apps/app-building) ** (2.0). Version: 1.0 On this page Vectara empowers developers with advanced capabilities in document indexing, neural retrieval, and Retrieval Augmented Generation (RAG) enhancement. Our tools can help you realize the full potential of AI-driven search and retrieval functionality for your generative AI applications. note These app building tools are not officially supported by Vectara. Users may need to seek community support or external resources for assistance and updates. Data ingestion[​](#data-ingestion "Direct link to Data ingestion") ------------------------------------------------------------------- ### [Vectara Ingest](/docs/build-apps/vectara-ingest) [​](#vectara-ingest "Direct link to vectara-ingest") Sample templates and crawlers for pulling data from many popular data sources. Clients[​](#clients "Direct link to Clients") ---------------------------------------------- ### [Stream-Query-Client](/docs/build-apps/stream-query-client) [​](#stream-query-client "Direct link to stream-query-client") JavaScript client for accessing the Stream Query API. User interface[​](#user-interface "Direct link to User interface") ------------------------------------------------------------------- ### [React-Chatbot](/docs/build-apps/react-chatbot) [​](#react-chatbot "Direct link to react-chatbot") UI widget for adding a chatbot to your React UI in just a few lines of code. ### [React-Search](/docs/build-apps/react-search) [​](#react-search "Direct link to react-search") UI widget for adding semantic search to your React UI in just a few lines of code. ### [Create-UI](/docs/build-apps/create-ui) [​](#create-ui "Direct link to create-ui") The fastest way to generate a working React codebase for a range of generative and semantic search UIs. ### [Vectara Answer](/docs/build-apps/vectara-answer) [​](#vectara-answer "Direct link to vectara-answer") Demo app for Summarized Semantic Search with advanced configuration options. * [Data ingestion](#data-ingestion) * [Vectara Ingest](#vectara-ingest) * [Clients](#clients) * [Stream-Query-Client](#stream-query-client) * [User interface](#user-interface) * [React-Chatbot](#react-chatbot) * [React-Search](#react-search) * [Create-UI](#create-ui) * [Vectara Answer](#vectara-answer) --- # Semantic Search Filtering | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/common-use-cases/semantic-search/semantic-search-filtering) ** (2.0). Version: 1.0 --- # Transport Layer Security (TLS) | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/common-use-cases/keeping-your-data-private/tls) ** (2.0). Version: 1.0 All communication to and from the API endpoints take place using an encrypted communication channel (TLS). gRPC handles configuration of the TLS channel using [channel credentials](https://grpc.io/docs/guides/auth/#credential-types) , and you should refer to their documentation. The code snippets below show how to configure channel credentials using the default set of root certificates installed on your system, which is usually sufficient. * Java * Python * PHP $channel_creds = Grpc\ChannelCredentials::createSsl(); # Allow the gRPC runtime to load root certificates from the default location.# This is sufficient for most cases.channel_creds = grpc.ssl_channel_credentials()grpc.secure_channel("serving.vectara.io:443", channel_creds) NettyChannelBuilder .forAddress("serving.vectara.io", 443) .sslContext(GrpcSslContexts.forClient() .trustManager(null) // load root certificates from the default location .build()) .build(); --- # API Authorization Methods | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/api-access-overview) ** (2.0). Version: 1.0 On this page Vectara provides a comprehensive authorization system that accommodates a wide range of use cases and caters to different development environments. Your Generative AI journey may be in the early stages of exploration and prototyping, or a more advanced production deployment. Our authentication methods include the Personal API Key, Index API Keys, Query API Keys, and OAuth 2.0 Tokens. The Authorization page lets you manage Personal, Index, and Query API Keys, and OAuth App clients. The [Authentication Overview section](/docs/learn/authentication/auth-overview) provides more details about how to [manage OAuth 2.0 tokens](/docs/learn/authentication/oauth-2) and [use API Keys](/docs/learn/authentication/api-key-management) . Personal API Key[​](#personal-api-key "Direct link to Personal API Key") ------------------------------------------------------------------------- The Personal API Key lets you perform administrative tasks including creating, deleting, and listing corpora, managing API keys for accessible corpora, reading usage data, updating corpora filters, executing queries, and indexing. note A Personal API Key inherits the permissions of its associated user account. Query API Keys[​](#query-api-keys "Direct link to Query API Keys") ------------------------------------------------------------------- Query API Keys are recommended for read-only querying operations and are designed for embedding in code that runs in potentially insecure environments like web browsers or mobile apps. Query API Keys provide the least amount of risk because they have a limited scope and do not modify account data. Index API Keys[​](#index-api-keys "Direct link to Index API Keys") ------------------------------------------------------------------- Index API Keys offer a practical solution for development and testing phases for when you need read and write access. Because they also provide write access, Index API Keys are more powerful than Query API Keys and should be treated like passwords and used with caution in production environments. OAuth 2.0 Tokens[​](#oauth-20-tokens "Direct link to OAuth 2.0 Tokens") ------------------------------------------------------------------------ OAuth 2.0 provides the most secure authentication method for production environments. Capabilities like automated token expiration provide inherent benefits over API Keys. Identify API Key by Prefixes[​](#identify-api-key-by-prefixes "Direct link to Identify API Key by Prefixes") ------------------------------------------------------------------------------------------------------------- For ease of identification, the API Key types each have a specific prefix: * Personal API Keys begin with `zut_` * Query API Keys begin with `zqt_` * Index API Keys begin with `zwt_` * [Personal API Key](#personal-api-key) * [Query API Keys](#query-api-keys) * [Index API Keys](#index-api-keys) * [OAuth 2.0 Tokens](#oauth-20-tokens) * [Identify API Key by Prefixes](#identify-api-key-by-prefixes) --- # React-Search | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/build-apps/react-search) ** (2.0). Version: 1.0 ![Screenshot of React-Search search box](/assets/images/react_search-554097762fae0ad204c48b7bcff3eef1.jpg) The React-Search component queries your Vectara data and adds semantic search to your React apps with a few lines of code. [Interact with the demo](https://vectara.github.io/react-search/) to see how it works. [Go to the code repository](https://github.com/vectara/react-search) for information about how to use React-Search. --- # Semantic Search Highlighting | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/common-use-cases/semantic-search/semantic-search-highlighting) ** (2.0). Version: 1.0 --- # Types of API Keys | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/api-access-overview-old) ** (2.0). Version: 1.0 On this page Vectara provides a comprehensive authorization system that accommodates a wide range of use cases and caters to different development and deployment environments. Your Generative AI journey may be in the early stages of exploration and prototyping, or a more advanced production deployment. Our advanced authentication system includes Personal API Keys, Index and Query API Keys, and OAuth 2.0 Tokens. Personal API Keys[​](#personal-api-keys "Direct link to Personal API Keys") ---------------------------------------------------------------------------- Personal API Keys help developers in early stages of exploration and prototyping with Vectara. This method provides a straightforward getting started experience for integrating accounts with external applications without the complexity of OAuth authentication. You can use Personal API Keys when putting together a quick prototype or if you are working on an integration that does not yet support OAuth 2.0. Personal API Keys let you perform tasks including creating, deleting, and listing corpora, managing API keys for accessible corpora, reading usage data, updating corpora filters, executing queries, and indexing. caution A Personal API Key inherits the permissions of the user account it is associated with. For instance, a key generated by a billing admin will possess only billing admin-related permissions. Because of their broad access, treat Personal API Keys with the same caution as passwords. Query API Keys[​](#query-api-keys "Direct link to Query API Keys") ------------------------------------------------------------------- Query API Keys are recommended for read-only querying operations and are designed for embedding in code that runs in potentially insecure environments like web browsers or mobile apps. Query API Keys provide the least amount of risk because they have a limited scope and do not modify account data. Index API Keys[​](#index-api-keys "Direct link to Index API Keys") ------------------------------------------------------------------- Index API Keys offer a practical solution for development and testing phases for when you need read and write access. Because they also provide write access, Index API Keys are more powerful than Query API Keys and should be treated like passwords and used with caution in production environments. OAuth 2.0 Tokens[​](#oauth-20-tokens "Direct link to OAuth 2.0 Tokens") ------------------------------------------------------------------------ OAuth 2.0 provides the most secure authentication method for production environments. Capabilities like automated token expiration provide inherent benefits over API Keys. API Key Prefixes[​](#api-key-prefixes "Direct link to API Key Prefixes") ------------------------------------------------------------------------- For ease of identification, the API Key types each have a specific prefix: * Personal API Keys begin with `zut_` * Query API Keys begin with `zqt_` * Index API Keys begin with `zwt_` * [Personal API Keys](#personal-api-keys) * [Query API Keys](#query-api-keys) * [Index API Keys](#index-api-keys) * [OAuth 2.0 Tokens](#oauth-20-tokens) * [API Key Prefixes](#api-key-prefixes) --- # Chat with Your Data | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/chat-with-your-data) ** (2.0). Version: 1.0 The Query tab of a corpus lets you enable chat with your corpus data. 1. Open a corpus from the Data page where you enabled chat. 2. Select the **Query** tab. 3. Select the **Chat** option if it is not enabled. 4. Let's ask a question. ![Chat with Your Data](/assets/images/chat_with_data-fdc035a3bb53acee626223e7c5ff5af4.png) Here is a detailed answer which also provide 4 facts from the updated data: ![View a Chat Answer](/assets/images/view_chat_answer-b44a735b133404498e9cb6da3332d1bd.png) --- # Conversations Overview | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/conversations-overview) ** (2.0). Version: 1.0 The Query tab le --- # App Clients for OAuth | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/app-clients) ** (2.0). Version: 1.0 On this page App clients provide the necessary pieces of information to [generate a JWT token](/docs/learn/authentication/oauth-2#generate-a-jwt-token) that developers need for OAuth 2.0 authentication. These pieces include the authorization URL, Client ID, and Client Secret. Create an App Client[​](#create-an-app-client "Direct link to Create an App Client") ------------------------------------------------------------------------------------- Visit the **API access** page in the Console or go to [https://console.vectara.com/console/apiAccess/appClients](https://console.vectara.com/console/apiAccess/appClients) to create a new application client. Applications will use the `client credentials` grant when they generate the JWT token. 1. Click **Create app client**. 2. Enter a **Name** and **Description** for the app client. 3. Select the appropriate roles for the client. 4. Click **Create** and the new app client appears in the list. **Authentication URL** Access your authentication by clicking the copy icon for the "OAuth 2.0 authentication URL." ![Copy the Authentication URL](/assets/images/copy_authentication_url-827dc0a1bf757ec80541326513fc5dbc.png) The URL has the following format: `https://vectara-prod-.auth.us-west-2.amazoncognito.com/oauth2/token` **Client ID** Access the `client_id` by clicking the copy icon next to your app client's ID. ![Copy the Client ID](/assets/images/copy_client_id-0bf8a45ee0e6e000dff3a14473adbcb2.png) **Client secret** Access the `client_secret` by clicking the drop-down to the right of your app client and selecting **Copy secret.** ![Copy the Client Secret](/assets/images/copy_client_secret-63918dc0ff23e96abae28dd9e6ae59b8.png) Now that you have values for the authentication URL, `client_id`, and `client_secret`, you can [generate a JWT token](/docs/learn/authentication/oauth-2#generate-a-jwt-token) with a `client-credentials` grant. * [Create an App Client](#create-an-app-client) --- # Configure Server Access to a Corpus | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/configure-server-access-to-corpus) ** (2.0). Version: 1.0 Follow the steps below to configure server access to a corpus. This access is commonly needed when your systems will be indexing data into the corpus or running queries against it. 1. Make sure that you have an \[app client\] for your server already created. 2. Navigate to your desired corpus by either clicking its name in the left sidebar or through the **Corpora** page. 3. Click the **Authorization** tab. note If you don't see an Authorization tab, you lack sufficient privileges. Ask your Account or Corpus Admin to grant you privileges on this corpus. ![Corpus Authorization](/assets/images/corpus_authorization_tab-3d559d63d46da8b5888963c59871b9a2.png) 1. Click **Create user role**. 2. Select a user in the Name dropdown, select the desired role(s) and add an optional description. Usually, the appropriate roles will be indexing (IDX), or querying (QRY), or both. ![Authorize User](/assets/images/authorization_create_user_role-c50b9c741167ad559a7eb3c9cfbee17b.gif) 3. Click **Create**. This will create a new role for your user. Congratulations. You have successfully authorized a server to access the corpus. --- # Personal API Keys | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/personal-api-key) ** (2.0). Version: 1.0 On this page The **Personal API Key** provides a broad range of functionality related to user and corpus administration, including creating and listing corpora, reading usage data, executing queries, indexing, and more. Your Personal API Key inherits the permissions of your associated user account. The Authorization page lets you view the Personal API key that automatically generated with your new Vectara account. ![View the Personal API Key](/assets/images/view_personal_api_key-741335f9f0ee55453c3abfbecd65e493.png) 1. Select the **Personal API Key** tab. 2. Click the copy icon. 3. Paste your Personal API key in a secure location. It is as private and sensitive as a password. 4. Use this Personal API Key for the `x-api-key` parameter within your API requests. Disable or Regenerate a Personal API Key[​](#disable-or-regenerate-a-personal-api-key "Direct link to Disable or Regenerate a Personal API Key") ------------------------------------------------------------------------------------------------------------------------------------------------- The Actions menu lets you disable or regenerate your Personal API key. ![View the Personal API Key](/assets/images/personal_api_key_actions-d84718b30e49eeb5ddc0165697450900.png) Personal API Key Limitations[​](#personal-api-key-limitations "Direct link to Personal API Key Limitations") ------------------------------------------------------------------------------------------------------------- While Personal API Keys offer a wide range of functionality, they have some limitations and **do not** let you perform the following tasks: * Delete a Vectara account * Validate a Vectara account registration * Transfer account ownership * Read or set any sensitive billing data such as payment method and addresses * Create and delete users OAuth 2.0 remains the required method for these operations due to its advanced security features. This distinction ensures that more sensitive actions are safeguarded by a higher level of authentication and authorization. * [Disable or Regenerate a Personal API Key](#disable-or-regenerate-a-personal-api-key) * [Personal API Key Limitations](#personal-api-key-limitations) --- # Configure Default Read Access to a Corpus | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/corpus-default-read-access) ** (2.0). Version: 1.0 Sometimes, you’ll want to make a corpus searchable by any authenticated user. This guide explains how to accomplish this by setting default read access on the corpus. 1. Make sure that you are logged in with a user having sufficient privileges to modify corpus authorizations. Any of the roles **Corpus Admin**, **Account Admin**, or **Account Owner** suffice. 2. Navigate to your desired corpus by either clicking its name in the left sidebar or through the **Corpora** page. 3. Click the **Authorization** tab in the right side window. ![Corpus Authorization](/assets/images/corpus_authorization_tab-3d559d63d46da8b5888963c59871b9a2.png) If you do not see an Authorization tab, you may not have sufficient privileges. Log in with an account that has rights. 1. Click on the **Create Default Role** button and create a Query Role for the corpus. ![Create Default Role](/assets/images/create_default_role-4f3949f1d6a406348f23e41b9aae9b3f.gif) 2. You will get a notification indicating successful creation of role. Congratulations. You have successfully setup default read access on the corpus for any authenticated user. Allow up to 5 minutes for the new permissions to propagate. --- # Corpus Query Configuration Options | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 On this page The Query tab lets you experiement with different search, summarization, and chat options. Whether you want to retrieve relevant information, generate summaries grounded in facts with Retrieval-Augmented Generation (RAG), or engage in conversational interactions, the Query tab offers a range of options. Explore these options and configurations to find the approach that best suits your needs. Search Your Data[​](#search-your-data "Direct link to Search Your Data") ------------------------------------------------------------------------- One of the primary uses for the Query tab is to search and retrieve relevant information from your corpus and you have two options. 1. **Semantic Search**: This option allows you to perform semantic searches based on natural language queries. Vectara's advanced algorithms understand the meaning and context of your queries, enabling accurate and relevant search results. 2. **Summarized Semantic Search**: Extending the Semantic Search functionality, this option uses Retrieval-Augmented Generation (RAG) to provide concise summaries in response to your queries. This can be particularly useful when you need a overview of the relevant information within your data. Both search options provide various configuration settings to fine-tune the search experience Engage in Conversations with Your Data[​](#engage-in-conversations-with-your-data "Direct link to Engage in Conversations with Your Data") ------------------------------------------------------------------------------------------------------------------------------------------- The Chat option allows you to engage in conversational interactions with your data. This can be particularly useful when you need to ask follow-up questions, clarify information, or explore your data in a more interactive manner. Chat leverages the same underlying search and summarization capabilities as the other options, but presents the results in a conversational format, making it easier to maintain context and engage in multi-turn interactions. Customize the Retrieval Experience[​](#customize-the-retrieval-experience "Direct link to Customize the Retrieval Experience") ------------------------------------------------------------------------------------------------------------------------------- Vectara provides various configuration settings to tailor the experience to your specific needs: ### Configure retrieval[​](#configure-retrieval "Direct link to Configure retrieval") The retrieval configuration lets you enable hybrid search by adjusting the `lambda` value, which is a balance between neural search and keyword search. The reranking option lets you rerank orders of search results and Scale users can use the Maximum Marginal Relevance (MMR) Reranker with a diversity factor to reduce bias. ![Configure retrieval drawer](/assets/images/configure_retrieval-8af3c23d450b118cdbe264e3cf29afa8.png) ### Configure search filters[​](#configure-search-filters "Direct link to Configure search filters") Select Filters to enter a filter expression or select filter attributes to further refine your search results. We provide some syntax examples in the drawer. ![Configure search filters](/assets/images/configure_filters_drawer-d51c5fc2f6d1e28261b7165c08595e2f.png) ### Configure evaluation[​](#configure-evaluation "Direct link to Configure evaluation") The Factual Consistency Score automatically evaluates and detects hallucinations in generated output. This calibrated score can range from `0.0` to `1.0`. A higher score indicates a greater probability of being factually accurate, while a lower score indicates a greater probability of hallucinations. ![Configure evaluation](/assets/images/configure_evaluation-e205c2bd082fac4ffaffd0b89f58dde2.png) ### Show API Request and Response[​](#show-api-request-and-response "Direct link to Show API Request and Response") While you experiment with these different search options and configurations, you can click **Show API request** to see the underlying API request and response. * [Search Your Data](#search-your-data) * [Engage in Conversations with Your Data](#engage-in-conversations-with-your-data) * [Customize the Retrieval Experience](#customize-the-retrieval-experience) * [Configure retrieval](#configure-retrieval) * [Configure search filters](#configure-search-filters) * [Configure evaluation](#configure-evaluation) * [Show API Request and Response](#show-api-request-and-response) --- # Create a Corpus | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/creating-a-corpus) ** (2.0). Version: 1.0 On this page To begin searching your data, you first have to create a corpus. A corpus is a container where you upload all your data to be ingested and grouped together in a single location for querying. 1. To get started, navigate to the [Console Overview](https://console.vectara.com/overview) . 2. On the left sidebar, click **Corpora**. This will open an overview of the corpora you have created. It will be empty if this is your first time accessing the console. 3. Click **Create corpus** and a dialog box appears. 4. Enter the name and description of the corpus. 5. Select an Embedding Model, such as Boomerang. 6. Specify any Filter Attributes. 7. (Optional) Click **Inspect** and the request inspector appears. You can now optionally create this corpus by copying and pasting the application code in NodeJS, JavaScript, Linux, or Windows. ![Create Corpus Request Inspector](/assets/images/create_corpus_request_inspector-adc7809eee4772146e5846874115d355.png) 8. Click **Create**. ![Create Corpus](/assets/images/create_corpus-48c6a33977d851ab94157d4e73f9e9ec.png) The corpus is created and a confirmation message appears. It is now ready to receive your data. View the Corpus ID[​](#view-the-corpus-id "Direct link to View the Corpus ID") ------------------------------------------------------------------------------- Vectara API requests against a corpus require the corpus ID. Find the corpus ID in the top-left corner of the corpus view, near the corpus name. ![View Corpus ID](/assets/images/view_corpus_id-76bdbc3337a9ab2de23ae499c418cdfd.png) When you create a corpus, the following tabs appear: Data[​](#data "Direct link to Data") ------------------------------------- The Data tab provides a link to the API documentation and drag-and-drop file uploader. Click **Upload files** and then select your text, HTML, PDF, Word files, and more. It is the quickest way to ingest your data to ask some questions. The Data tab also lets you take a Vectara test drive by loading sample data from an employee handbook PDF. Query[​](#query "Direct link to Query") ---------------------------------------- The [Query tab](/docs/1.0/console-ui/corpus-query-configuration) lets you ask questions about your data. You can also use Advanced options and show the API request to copy and paste queries in your application code and view responses. Analytics[​](#analytics "Direct link to Analytics") ---------------------------------------------------- The Analytics tab provides usage statistics about the corpus and you can download this data in `.SVG`, `.PNG`, or `.CSV` format. Access Control[​](#access-control "Direct link to Access Control") ------------------------------------------------------------------- The Access control tab defines the users and roles that have access to the corpus. You can also [create new user roles](/docs/1.0/learn/authentication/role-based-access-control) , a default role, and [API keys](/docs/1.0/console-ui/api-access-overview) associated with this corpus. Configuration[​](#configuration "Direct link to Configuration") ---------------------------------------------------------------- The Configuration tab lets you view the embedding model and filter attributes for the corpus. You can also Edit filter attributes from this page. * [View the Corpus ID](#view-the-corpus-id) * [Data](#data) * [Query](#query) * [Analytics](#analytics) * [Access Control](#access-control) * [Configuration](#configuration) --- # Index and Query API Keys | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/index-and-query-api-keys) ** (2.0). Version: 1.0 On this page Index API Keys and Query API Keys enable user-facing applications to either index and query or only query data. The Authorization page lets you view and manage the Index API Keys and Query API keys associated with your account. Query API Keys[​](#query-api-keys "Direct link to Query API Keys") ------------------------------------------------------------------- Use Query API Keys for read-only querying operations in potentially insecure environments like web browsers or mobile apps. Query API Keys provide the least amount of risk because they have a limited scope and do not modify account data. Index API Keys[​](#index-api-keys "Direct link to Index API Keys") ------------------------------------------------------------------- Use Index API Keys when you need both read and write access. Because they also provide write access, Index API Keys are more powerful than Query API Keys and you should treat Index API Keys like passwords and use them with caution in production environments. screenshot of key list Create an Index or Query API Key[​](#create-an-index-or-query-api-key "Direct link to Create an Index or Query API Key") ------------------------------------------------------------------------------------------------------------------------- If you have the necessary permissions, an `Authorization` option appears in the sidebar. 1. Click `Authorization` and then select the **Index and Query API Keys** tab. ![View API Keys](/assets/images/view_api_keys-012a06b9f79ae9ddd13db55752c55843.png) 2. Click **Create Index and Query API Key** and a dialog appears. 3. Enter the name of the key and select the corpora you want to be able to query. ![Create API Key](/assets/images/create_api_key-7da49e3099ef20abbee666934446ddb3.png) 4. Click **Create**. You can now start [using the API key](/docs/1.0/learn/authentication/api-key-management#use-an-api-key) for your Index or Query operations. * [Query API Keys](#query-api-keys) * [Index API Keys](#index-api-keys) * [Create an Index or Query API Key](#create-an-index-or-query-api-key) --- # Manage Documents | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/manage-documents) ** (2.0). Version: 1.0 On this page The List Documents view provides information about each document ingested into the corpus, including the Document ID, title, size, date added, and metadata. This data helps you better manage the lifecycle of your documents by providing a quick way to check which documents are already in the index: * Utilize the metadata to build custom search and filtering capabilities into applications * Gather Documentation IDs that you can reference for future purposes such as deletion for audit and compliance reasons. * Delete documents from the corpus so that the data no longer appears in queries. ![List Documents](/assets/images/list_documents-03d6c2fd9f664af2a41532479cdef477.png) The list shows the first 10 documents and you can paginate with the next and previous buttons if you have more documents in the corpus. View Document Details[​](#view-document-details "Direct link to View Document Details") ---------------------------------------------------------------------------------------- Click a Document ID from the list to open the Document details panel. This shows the fields associated with the document and also a JSON string that you can copy. You can also delete the document permanently. ![List Documents](/assets/images/list_document_details-7653ab9d42a36d5efdf1ac0dda153ae1.png) * [View Document Details](#view-document-details) --- # Manage Users | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/manage-user) ** (2.0). Version: 1.0 On this page This section lets you add team members and manage the access levels of these users. For example, you can adjust account and corpus level authorizations. Create User[​](#create-user "Direct link to Create User") ---------------------------------------------------------- The Account Admin can create users. After login, navigate to the **Teams** tab to create new users and manage existing ones. 1. Click **Create User** 2. Enter the user's details including the user name, email, and a description. 3. Select a role or multiple roles to assign with this user: Account Admin, Corpus Admin, or Billing Admin. A user without assigned roles at the account level can still be given corpus-level roles. ![Add user](/assets/images/new_user-e8323b1915d34148204f75748500f2ed.png) 4. Click Create and the new user appears on the Team page. Edit User[​](#edit-user "Direct link to Edit User") ---------------------------------------------------- The Team page also lets you modify users directly from the user list by clicking the drop-down on the right side of the row. This includes changing role assignments, password resets, enabling and disabling the user, and transferring ownership of the account to a new owner. ![Edit user](/assets/images/edit_user-38236b3fb1fb589994c005c3f8ef3841.png) * [Create User](#create-user) * [Edit User](#edit-user) --- # Reset or Delete a Corpus | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/reset-or-delete-corpus) ** (2.0). Version: 1.0 On this page If you decide to stop using a corpus you have three options. 1. **Disable**: Disables query or indexing requests. A disabled corpus can be reenabled at any time. 2. **Reset**: Purge all the data within the corpus, but leave the corpus definition intact. 3. **Delete**: Purge all the data within the corpus and delete the corpus. All your connected services to the corpus will also cease to function. caution The **Reset** and **Delete** operations are irreversable. You can view these options in the actions menu in the upper-right corner of the page: ![Create operations](/assets/images/corpus_operations-ef3e65ec5546c056349738f9ee2c7125.png) Disable a Corpus[​](#disable-a-corpus "Direct link to Disable a Corpus") ------------------------------------------------------------------------- To disable a corpus: 1. Select **Disable corpus** from the Actions menu. A warning message appears. 2. Click Disable. You can enable the corpus again from the same menu. Reset a Corpus[​](#reset-a-corpus "Direct link to Reset a Corpus") ------------------------------------------------------------------- To reset a corpus: 1. Select **Clear corpus data** from the Actions menu. A warning message appears. 2. Enter the full name of the corpus for confirmation (case insensitive). 3. Click **Reset** and wait for the confirmation message. That's it, all the data within the corpus has been purged. Delete a Corpus[​](#delete-a-corpus "Direct link to Delete a Corpus") ---------------------------------------------------------------------- To permanently delete a corpus: 1. Select **Delete corpus** from the Actions menu. A warning message appears. 2. Enter the full name of the corpus for confirmation (case insensitive). 3. Click **Delete** and wait for the confirmation message. That's it, the corpus has been deleted. * [Disable a Corpus](#disable-a-corpus) * [Reset a Corpus](#reset-a-corpus) * [Delete a Corpus](#delete-a-corpus) --- # definitions | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/definitions) ** (2.0). Version: 1.0 --- # Vectara Chat | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/vectara-chat-overview) ** (2.0). Version: 1.0 On this page Vectara Chat provides an interactive user experience that enables you to build domain-specific chatbots using RAG. Vectara Chat remembers chat histories and leads to more relevant responses in different scenarios like customer support. Every Vectara account has a unique Chat History Corpus which stores all chat histories. You can chat with your data directly from the Vectara Console from within the Query tab of a corpus. Enable Chat[​](#enable-chat "Direct link to Enable Chat") ---------------------------------------------------------- You enable chat in the Query tab of a specific corpus. 1. Click **Data** and select a corpus from the list. 2. Select the **Query** tab. 3. Select **Chat** and a navigation drawer appears. ![Chat Option on the Query Tab](/assets/images/chat_query_tab-adfd202f0288854a9249d3d1c45491c1.png) 4. Enable the Chat toggle: ![Enable Chat Toggle Option](/assets/images/enable_chat-d8c1e7c3f326d45657d103b4158138c4.png) 5. Now you can [chat with your data](/docs/1.0/console-ui/chat-with-your-data) ! Manage Conversations[​](#manage-conversations "Direct link to Manage Conversations") ------------------------------------------------------------------------------------- The Conversations page lists the conversations in your chat history corpus: ![View the Conversation Page](/assets/images/view_conversations-5ff1c4235c65e4198ad47b29cc5c1c8e.png) View a Specific Conversation[​](#view-a-specific-conversation "Direct link to View a Specific Conversation") ------------------------------------------------------------------------------------------------------------- To view a specific conversation and all the turns in the chat, select a `Conversation ID` from the list. ![View a Specific Conversation](/assets/images/view_specific_conversation-aca7384c3672a4268a93300a54e245d8.png) Click **Delete** to remove the chat from the conversation history. * [Enable Chat](#enable-chat) * [Manage Conversations](#manage-conversations) * [View a Specific Conversation](#view-a-specific-conversation) --- # Manage Payments | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/update-credit-card) ** (2.0). Version: 1.0 Follow the steps below to update the payment information for your account. 1. Make sure that you are logged in as user having either the **Billing Admin** or **Account Owner** role. To learn how to assign a specific role to a user, see the guide for [managing users](/docs/1.0/console-ui/manage-user) . 2. Click **Billing** in the left navigation window. If you do not see this option, then you do not have sufficient privileges. Ask your account owner to make you a billing administrator. ![Billing](/assets/images/main_billing_page-a5b3fa030a5c505ea3f5198c1c4ecae3.png) 3. Click **Add credit card** to update your payment information. ![Edit Payment Method](/assets/images/edit_payment_method-303a9210c3f06f528d6aa662a89117dd.png) 4. Enter your payment details, and click **Update**. A confirmation pop up message indicates that the payment method has been updated. Congratulations. You have successfully updated the payment method and your payments going forward will be processed with it. --- # Vectara Console Overview | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/console-ui/vectara-console-overview) ** (2.0). Version: 1.0 On this page The Vectara Console enables you to create corpora, manage data and API access, add team members, build API requests, and manage your Vectara account: * πŸš€ **Five-Minute Walkthrough:** Let Vectara show you [how to build a simple GenAI application](https://console.vectara.com/console/walkthrough) in just a few minutes! * πŸƒβ€β™‚οΈ **Get Started Quickly:** View our [Quick Start guide](/docs/1.0/quickstart) and search the Vectara Employee Handbook PDF. * πŸ’Ύ **Manage Corpora:** [Create and manage your corpora data](/docs/1.0/console-ui/creating-a-corpus) , which serve as storage for data that you want to search. * πŸ“’ **Manage Data:** Manage the data in your account. * πŸ” **Manage API Access:** Users can define API access credentials, including [API Keys](/docs/1.0/learn/authentication/api-key-management) and [OAuth app clients](/docs/1.0/learn/authentication/oauth-2) . * πŸ‘₯ **Invite Team Members:** [Add users to your team](/docs/1.0/console-ui/manage-user) and assign specific permissions for each user. * πŸ”§ **Build API Requests:** Create API requests within the console and copy-paste into your code. * πŸ’° **Manage Billing Details:** View account usage information and [payment details](/docs/console-ui/update-credit-card) to ensure uninterrupted service. * 🌐 **Vectara Platform Overview:** Learn about the Vectara Platform and view interactive parts of our documentation like the [API Playground](/docs/1.0/rest-api/vectara-rest-api) . Vectara Console Home Page[​](#vectara-console-home-page "Direct link to Vectara Console Home Page") ---------------------------------------------------------------------------------------------------- The Vectara Console Overview home page also provides helpful links to get you started with our plaltform: ![Vectara Console Overview](/assets/images/console_overview-2f1139b326bb6404a91b0758d1909442.png) View the Customer ID[​](#view-the-customer-id "Direct link to View the Customer ID") ------------------------------------------------------------------------------------- Click your name in the upper-right corner to view your Customer ID, email, account size, and more. You need the Customer ID for many API requests. You can also copy the Customer ID value for those API requests and paste them into the [API Playground](/docs/1.0/rest-api/) to experiment with our endpoints live in your browser. ![Customer ID](/assets/images/customer_id-7080733378f12373e7f6cd5fddabf8ca.png) * [Vectara Console Home Page](#vectara-console-home-page) * [View the Customer ID](#view-the-customer-id) --- # deleteCorpus.php | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/deleteCorpus.php) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [php/rest/deleteCorpus.php](https://github.com/vectara/getting-started/tree/main/language-examples/php/rest/deleteCorpus.php) php/rest/deleteCorpus.php $customer_id, 'corpus_id' => $_POST['corpus_id'],];$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $url);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type:application/json', 'Authorization: Bearer ' . $jwt_token, 'customer-id: ' . strval($customer_id),]);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($corpus_data));curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);//execute post$result = curl_exec($ch);curl_close($ch);echo $result;?> --- # resetCorpus.php | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/resetCorpus.php) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [php/rest/resetCorpus.php](https://github.com/vectara/getting-started/tree/main/language-examples/php/rest/resetCorpus.php) php/rest/resetCorpus.php $customer_id, 'corpus_id' => $_POST['corpus_id'],];$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $url);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type:application/json', 'Authorization: Bearer ' . $jwt_token, 'customer-id: ' . strval($customer_id),]);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($corpus_data));curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);//execute post$result = curl_exec($ch);curl_close($ch);echo $result;?> --- # createCorpus.php | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/createCorpus.php) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [php/rest/createCorpus.php](https://github.com/vectara/getting-started/tree/main/language-examples/php/rest/createCorpus.php) php/rest/createCorpus.php 'Test Corpus via PHP', 'description' => 'Test Description',];$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $url);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type:application/json', 'Authorization: Bearer ' . $jwt_token, 'customer-id: ' . strval($customer_id),]);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['corpus' => $corpus_data]));curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);//execute post$result = curl_exec($ch);curl_close($ch);echo $result;?> --- # getJwtToken.php | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/getJwtToken.php) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [php/rest/getJwtToken.php](https://github.com/vectara/getting-started/tree/main/language-examples/php/rest/getJwtToken.php) php/rest/getJwtToken.php 'client_credentials', 'client_id' => $client_id, 'client_secret' => $client_secret ]; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($fields)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $result = curl_exec($ch); curl_close($ch); $data = json_decode($result); return $data->access_token;}?> --- # indexDocument.php | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/indexDocument.php) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [php/rest/indexDocument.php](https://github.com/vectara/getting-started/tree/main/language-examples/php/rest/indexDocument.php) php/rest/indexDocument.php $customer_id, 'corpus_id' => $_POST['corpus_id'], 'document' => [ 'document_id' => 'doc-id-1', 'title' => 'My document title', 'metadata_json' => json_encode([ 'book-name' => 'Example title', 'collection' => 'Mathematics', 'author' => 'Example Author' ]), 'section' => array([ 'text' => 'This is a test document' ]) ],];/** * Note that both documents and sections can contain titles and * metadata_json. These are optional for both levels. */$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $url);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type:application/json', 'Authorization: Bearer ' . $jwt_token, 'customer-id: ' . strval($customer_id),]);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($index_data));curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);//execute post$result = curl_exec($ch);curl_close($ch);echo $result;?> --- # JWTFetcher.cs | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/JWTFetcher.cs) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [csharp/common/JWTFetcher.cs](https://github.com/vectara/getting-started/tree/main/language-examples/csharp/common/JWTFetcher.cs) csharp/common/JWTFetcher.cs namespace VectaraExampleCommon;using System.Text.Json;/// /// A class that makes an HTTP POST call to obtain a JWT Token based on authentication URL,/// client ID and client secret./// public class JWTFetcher{ public String authDomain { get; set; } public String clientId { get; set; } public String clientSecret { get; set; } private string Base64Encode(String clientId, String clientSecret) { String text = clientId + ":" + clientSecret; var plainTextBytes = System.Text.Encoding.UTF8.GetBytes(text); return System.Convert.ToBase64String(plainTextBytes); } /// /// Fetches a client_credentials JWT Token based on authentication URL, client ID and /// client secret. /// public String? FetchClientCredentials() { if (String.IsNullOrEmpty(authDomain) || String.IsNullOrEmpty(clientId) || String.IsNullOrEmpty(clientSecret)) { return null; } if (!authDomain.EndsWith("/oauth2/token")) { if (!authDomain.EndsWith("/")) { authDomain += "/"; } authDomain += "oauth2/token"; } using (var client = new HttpClient()) { var request = new HttpRequestMessage { RequestUri = new Uri(authDomain), Method = HttpMethod.Post, Content = new FormUrlEncodedContent( new Dictionary { {"grant_type", "client_credentials"}, {"client_id", clientId} }) }; request.Headers.Add("Authorization", "Basic " + Base64Encode(clientId, clientSecret)); request.Content.Headers.Remove("Content-Type"); request.Content.Headers.Add("Content-Type", "application/x-www-form-urlencoded"); try { HttpResponseMessage res = client.Send(request); String result = res.Content.ReadAsStringAsync().Result; var values = JsonSerializer.Deserialize>(result); if (!values.ContainsKey("access_token")) { Console.WriteLine("Could not retrieve JWT Token."); return null; } return values["access_token"].ToString(); } catch (Exception ex) { Console.WriteLine(ex.Message); return null; } } }} --- # deleteDocument.php | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/deleteDocument.php) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [php/rest/deleteDocument.php](https://github.com/vectara/getting-started/tree/main/language-examples/php/rest/deleteDocument.php) php/rest/deleteDocument.php $customer_id, 'corpus_id' => $corpus_id, 'document_id' => $document_id,];$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $url);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type:application/json', 'Authorization: Bearer ' . $jwt_token, 'customer-id: ' . strval($customer_id),]);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($delete_request));curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);//execute post$result = curl_exec($ch);curl_close($ch);echo $result;?> --- # queryData.php | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/queryData.php) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [php/rest/queryData.php](https://github.com/vectara/getting-started/tree/main/language-examples/php/rest/queryData.php) php/rest/queryData.php $query, 'numResults' => 10, 'corpusKey' => [ [ 'customerId' => $customer_id, 'corpusId' => $corpus_id, ], ],];$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $url);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type:application/json', 'Authorization: Bearer ' . $jwt_token, 'customer-id: ' . strval($customer_id),]);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['query' => [$query_data]]));curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);$result = curl_exec($ch);curl_close($ch);echo $result;?> --- # JwtFetcher.java | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/JwtFetcher.java) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [java/auth/src/main/java/com/vectara/auth/JwtFetcher.java](https://github.com/vectara/getting-started/tree/main/language-examples/java/auth/src/main/java/com/vectara/auth/JwtFetcher.java) java/auth/src/main/java/com/vectara/auth/JwtFetcher.java package com.vectara.auth;import com.google.gson.Gson;import java.io.IOException;import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpClient.Redirect;import java.net.http.HttpClient.Version;import java.net.http.HttpRequest;import java.net.http.HttpRequest.BodyPublishers;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;import java.util.Base64;import java.util.Map;import java.util.logging.Level;import java.util.logging.Logger;import javax.annotation.Nullable;/** * A helper that retrieves a JSON Web Token from an authorization code grant. Most of the details * for how to format the HTTP request can be found at: * *

https://aws.amazon.com/blogs/mobile/understanding-amazon-cognito-user-pool-oauth-2-0-grants/ */public class JwtFetcher { private static final Logger LOGGER = Logger.getLogger(JwtFetcher.class.getName()); private URI tokenEndpoint; private URI redirectUri; private String clientId; private String clientSecret; private HttpClient httpClient; /** * Construct a JWT fetcher for machine-to-machine authentication (also known as "client * credentials"). */ public JwtFetcher(URI authDomain, String clientId, String clientSecret) { init(authDomain, null, clientId, clientSecret); } /** * Initializes a new HTTPClient object * @param authDomain Vectara auth domain such as https://vectara.auth.us-west-2.amazoncognito.com * @param redirectUri Redirect URI where caller will be redirected after successful * authentication. Can be null. * @param clientId Vectara client ID such as "259xxxxxxxxxxxxxxxxxxxxxxxxxx9p" * @param clientSecret Vectara client secret such as "2vxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxt" */ private void init( URI authDomain, @Nullable URI redirectUri, String clientId, String clientSecret) { String strAuthDomain = authDomain.toASCIIString(); if (strAuthDomain.endsWith("/oauth2/token")) { tokenEndpoint = asUrl(strAuthDomain); } else { if (!strAuthDomain.endsWith("/")) { strAuthDomain += "/"; } tokenEndpoint = asUrl(strAuthDomain + "oauth2/token"); } this.redirectUri = redirectUri; this.clientId = clientId; this.clientSecret = clientSecret; httpClient = HttpClient.newBuilder() .version(Version.HTTP_2) .followRedirects(Redirect.NORMAL) .connectTimeout(Duration.ofSeconds(20)) .build(); } private URI asUrl(String url) { return URI.create(url); } public String fetchClientCredentialsJwt() { HttpRequest.Builder builder = HttpRequest.newBuilder() .uri(tokenEndpoint) .header("Content-Type", "application/x-www-form-urlencoded") .POST( BodyPublishers.ofString( String.format( "grant_type=%s&client_id=%s&redirect_uri=%s", "client_credentials", clientId, redirectUri))); builder.header( "Authorization", "Basic " + Base64.getEncoder().encodeToString((clientId + ":" + clientSecret).getBytes())); HttpRequest request = builder.build(); try { HttpResponse response = httpClient.send(request, BodyHandlers.ofString()); Map map = new Gson().fromJson(response.body(), Map.class); if (map.containsKey("error")) { LOGGER.log( Level.SEVERE, String.format( "Error while retrieving JWT Token: %s", String.valueOf(map.get("error")))); return null; } if (map.containsKey("access_token")) { return String.valueOf(map.get("access_token")); } return null; } catch (IOException | InterruptedException e) { LOGGER.log(Level.SEVERE, String.format("Error while retrieving JWT Token: %s", e)); return null; } }} --- # rest_create_corpus.py | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/rest_create_corpus.py) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [python/vectara-rest/rest\_create\_corpus.py](https://github.com/vectara/getting-started/tree/main/language-examples/python/vectara-rest/rest_create_corpus.py) python/vectara-rest/rest\_create\_corpus.py """Simple example of using the Vectara REST API for creating a corpus."""import jsonimport loggingimport requestsdef _get_create_corpus_json(): """ Returns a create corpus json. """ corpus = {} corpus["name"] = "Vectara Test Corpus(Python)" corpus["description"] = "An example corpus generated via REST API from Python code." return json.dumps({"corpus":corpus})def create_corpus(customer_id: int, admin_address: str, jwt_token: str): """Create a corpus. Args: customer_id: Unique customer ID in vectara platform. admin_address: Address of the admin server. e.g., api.vectara.io jwt_token: A valid Auth token. Returns: (response, True) in case of success and returns (error, False) in case of failure. """ post_headers = { "customer-id": f"{customer_id}", "Authorization": f"Bearer {jwt_token}" } response = requests.post( f"https://{admin_address}/v1/create-corpus", data=_get_create_corpus_json(), verify=True, headers=post_headers) if response.status_code != 200: logging.error("Create Corpus failed with code %d, reason %s, text %s", response.status_code, response.reason, response.text) return response, False message = response.json() if message["status"] and message["status"]["code"] != "OK": logging.error("Create Corpus failed with status: %s", message["status"]) return message["status"], False return message, True --- # rest_delete_corpus.py | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/rest_delete_corpus.py) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [python/vectara-rest/rest\_delete\_corpus.py](https://github.com/vectara/getting-started/tree/main/language-examples/python/vectara-rest/rest_delete_corpus.py) python/vectara-rest/rest\_delete\_corpus.py """Simple example of using the Vectara REST API for deleting a corpus."""import jsonimport loggingimport requestsdef _get_delete_corpus_json(customer_id: int, corpus_id: int): """Returns a delete corpus JSON.""" corpus = { "customer_id": customer_id, "corpus_id": corpus_id, } return json.dumps(corpus)def delete_corpus(customer_id: int, corpus_id: int, admin_address: str, jwt_token: str): """Deletes a corpus. Args: customer_id: Unique customer ID in vectara platform. corpus_id: Corpus ID in vectara platform. admin_address: Address of the admin server. e.g., api.vectara.io jwt_token: A valid Auth token. Returns: (response, True) in case of success and returns (error, False) in case of failure. """ post_headers = { "customer-id": f"{customer_id}", "Authorization": f"Bearer {jwt_token}" } response = requests.post( f"https://{admin_address}/v1/delete-corpus", data=_get_delete_corpus_json(customer_id, corpus_id), verify=True, headers=post_headers) if response.status_code != 200: logging.error("Delete Corpus failed with code %d, reason %s, text %s", response.status_code, response.reason, response.text) return response, False message = response.json() if message["status"] and message["status"]["code"] != "OK": logging.error("Delete Corpus failed with status: %s", message.status) return message.status, False return message, True --- # rest_delete_document.py | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/rest_delete_document.py) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [python/vectara-rest/rest\_delete\_document.py](https://github.com/vectara/getting-started/tree/main/language-examples/python/vectara-rest/rest_delete_document.py) python/vectara-rest/rest\_delete\_document.py """Simple example of using the Vectara REST API for deleting a document."""import jsonimport loggingimport requestsdef _get_delete_request_json(customer_id: int, corpus_id: int, doc_id: str): """Returns a JSON delete request.""" request = { "customer_id": customer_id, "corpus_id": corpus_id, "document_id": doc_id, } return json.dumps(request)def delete_document( customer_id: int, corpus_id: int, idx_address: str, jwt_token: str, doc_id: str): """Deletes document from the corpus. Args: customer_id: Unique customer ID in vectara platform. corpus_id: ID of the corpus from which document willb e deleted. idx_address: Address of the indexing server. e.g., api.vectara.io jwt_token: A valid Auth token. doc_id: Id of the document to be deleted. Returns: (response, True) in case of success and returns (response, False) in case of failure. """ post_headers = { "Authorization": f"Bearer {jwt_token}", "customer-id": f"{customer_id}" } response = requests.post( f"https://{idx_address}/v1/delete-doc", data=_get_delete_request_json(customer_id, corpus_id, doc_id), verify=True, headers=post_headers) if response.status_code != 200: logging.error("REST delete document failed with code %d, reason %s, text %s", response.status_code, response.reason, response.text) return response, False return response.json(), True --- # rest_api_key_queries.py | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/rest_api_key_queries.py) ** (2.0). Version: 1.0 This is a complete example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [python/vectara-rest/rest\_api\_key\_queries.py](https://github.com/vectara/getting-started/tree/main/language-examples/python/vectara-rest/rest_api_key_queries.py) python/vectara-rest/rest\_api\_key\_queries.py """An example of calling the Vectara API via Python using HTTP/REST."""import argparseimport jsonimport loggingimport sysimport requestsdef _get_query_json(customer_id: int, corpus_id: int, query_value: str): """Returns a query JSON.""" query = { "query": [ { "query": query_value, "num_results": 10, "corpus_key": [{"customer_id": customer_id, "corpus_id": corpus_id}], }, ], } return json.dumps(query)def query(customer_id: int, corpus_id: int, query_address: str, api_key: str, query: str): """Queries the data. Args: customer_id: Unique customer ID in vectara platform. corpus_id: ID of the corpus to which data needs to be indexed. query_address: Address of the querying server. e.g., api.vectara.io api_key: A valid API key with query access on the corpus. Returns: (response, True) in case of success and returns (error, False) in case of failure. """ post_headers = { "customer-id": f"{customer_id}", "x-api-key": api_key } response = requests.post( f"https://{query_address}/v1/query", data=_get_query_json(customer_id, corpus_id, query), verify=True, headers=post_headers) if response.status_code != 200: logging.error("Query failed with code %d, reason %s, text %s", response.status_code, response.reason, response.text) return response, False message = response.json() if (message["status"] and any(status["code"] != "OK" for status in message["status"])): logging.error("Query failed with status: %s", message["status"]) return message["status"], False for response_set in message["responseSet"]: for status in response_set["status"]: if status["code"] != "OK": return status, False return message, Trueif __name__ == "__main__": logging.basicConfig( format="%(asctime)s %(levelname)-8s %(message)s", level=logging.INFO) parser = argparse.ArgumentParser( description="Vectara rest example (With API Key authentication.") parser.add_argument("--customer-id", type=int, help="Unique customer ID in Vectara platform.") parser.add_argument("--corpus-id", type=int, help="Corpus ID to which data will be indexed and queried from.") parser.add_argument("--serving-endpoint", help="The endpoint of querying server.", default="api.vectara.io") parser.add_argument("--api-key", help="API key retrieved from Vectara console.") parser.add_argument("--query", help="Query to run against the corpus.", default="Test query") args = parser.parse_args() if args: response, status = query(args.customer_id, args.corpus_id, args.serving_endpoint, args.api_key, args.query) logging.info("Query response: %s", response) if not status: sys.exit(1) --- # queryDataApiKey.php | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/queryDataApiKey.php) ** (2.0). Version: 1.0 This is a complete example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [php/rest/queryDataApiKey.php](https://github.com/vectara/getting-started/tree/main/language-examples/php/rest/queryDataApiKey.php) php/rest/queryDataApiKey.php $query, 'numResults' => 10, 'corpusKey' => [ [ 'customerId' => $customer_id, 'corpusId' => $corpus_id, ], ],];$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $url);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type:application/json', 'x-api-key:' . strval($api_key), 'customer-id: ' . strval($customer_id),]);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['query' => [$query_data]]));curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);$result = curl_exec($ch);curl_close($ch);echo $result;?> --- # rest_reset_corpus.py | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/rest_reset_corpus.py) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [python/vectara-rest/rest\_reset\_corpus.py](https://github.com/vectara/getting-started/tree/main/language-examples/python/vectara-rest/rest_reset_corpus.py) python/vectara-rest/rest\_reset\_corpus.py """Simple example of using the Vectara REST API for resetting a corpus."""import jsonimport loggingimport requestsdef _get_reset_corpus_json(customer_id: int, corpus_id: int): """ Returns a reset corpus json. """ corpus = { "customer_id": customer_id, "corpus_id": corpus_id, } return json.dumps(corpus)def reset_corpus(customer_id: int, corpus_id: int, admin_address: str, jwt_token: str): """Reset a corpus. Args: customer_id: Unique customer ID in vectara platform. corpus_id: Corpus ID in vectara platform. admin_address: Address of the admin server. e.g., api.vectara.io jwt_token: A valid Auth token. Returns: (response, True) in case of success and returns (error, False) in case of failure. """ post_headers = { "customer-id": f"{customer_id}", "Authorization": f"Bearer {jwt_token}" } response = requests.post( f"https://{admin_address}/v1/reset-corpus", data=_get_reset_corpus_json(customer_id, corpus_id), verify=True, headers=post_headers) if response.status_code != 200: logging.error("Reset Corpus failed with code %d, reason %s, text %s", response.status_code, response.reason, response.text) return response, False message = response.json() if message["status"] and message["status"]["code"] != "OK": logging.error("Delete Corpus failed with status: %s", message.status) return message.status, False return message, True --- # rest_index_document.py | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/rest_index_document.py) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [python/vectara-rest/rest\_index\_document.py](https://github.com/vectara/getting-started/tree/main/language-examples/python/vectara-rest/rest_index_document.py) python/vectara-rest/rest\_index\_document.py """Simple example of using the Vectara REST API for indexing."""import jsonimport loggingimport requestsdef _get_index_request_json(customer_id: int, corpus_id: int): """Returns some example data to index.""" document = { # Note that the document ID must be unique for a given corpus. "document_id": "doc-id-2", "title": "Another example Title", "metadata_json": json.dumps( { "book-name": "Another example title", "collection": "Mathematics", "author": "Example Author", } ), "section": [ {"text": ("The answer to the ultimate question " "of life, the universe, and everything is 42.")}, ], } request = { "customer_id": customer_id, "corpus_id": corpus_id, "document": document, } return json.dumps(request)def index_document(customer_id: int, corpus_id: int, idx_address: str, jwt_token: str): """Indexes content to the corpus. Args: customer_id: Unique customer ID in vectara platform. corpus_id: ID of the corpus to which data needs to be indexed. idx_address: Address of the indexing server. e.g., api.vectara.io jwt_token: A valid Auth token. Returns: (response, True) in case of success and returns (error, False) in case of failure. """ post_headers = { "Authorization": f"Bearer {jwt_token}", "customer-id": f"{customer_id}" } response = requests.post( f"https://{idx_address}/v1/index", data=_get_index_request_json(customer_id, corpus_id), verify=True, headers=post_headers) if response.status_code != 200: logging.error("REST upload failed with code %d, reason %s, text %s", response.status_code, response.reason, response.text) return response, False message = response.json() if message["status"] and message["status"]["code"] not in ("OK", "ALREADY_EXISTS"): logging.error("REST upload failed with status: %s", message["status"]) return message["status"], False return message, True --- # rest_query.py | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/rest_query.py) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [python/vectara-rest/rest\_query.py](https://github.com/vectara/getting-started/tree/main/language-examples/python/vectara-rest/rest_query.py) python/vectara-rest/rest\_query.py """Simple example of using the Vectara REST API for searching a corpus."""import jsonimport loggingimport requestsdef _get_query_json(customer_id: int, corpus_id: int, query_value: str): """Returns a query JSON.""" query = { "query": [ { "query": query_value, "num_results": 10, "corpus_key": [{"customer_id": customer_id, "corpus_id": corpus_id}], }, ], } return json.dumps(query)def query(customer_id: int, corpus_id: int, query_address: str, jwt_token: str, query: str): """Queries the data. Args: customer_id: Unique customer ID in vectara platform. corpus_id: ID of the corpus to which data needs to be indexed. query_address: Address of the querying server. e.g., api.vectara.io jwt_token: A valid Auth token. Returns: (response, True) in case of success and returns (error, False) in case of failure. """ post_headers = { "customer-id": f"{customer_id}", "Authorization": f"Bearer {jwt_token}" } response = requests.post( f"https://{query_address}/v1/query", data=_get_query_json(customer_id, corpus_id, query), verify=True, headers=post_headers) if response.status_code != 200: logging.error("Query failed with code %d, reason %s, text %s", response.status_code, response.reason, response.text) return response, False message = response.json() if (message["status"] and any(status["code"] != "OK" for status in message["status"])): logging.error("Query failed with status: %s", message["status"]) return message["status"], False for response_set in message["responseSet"]: for status in response_set["status"]: if status["code"] != "OK": return status, False return message, True --- # rest_upload_file.py | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/rest_upload_file.py) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [python/vectara-rest/rest\_upload\_file.py](https://github.com/vectara/getting-started/tree/main/language-examples/python/vectara-rest/rest_upload_file.py) python/vectara-rest/rest\_upload\_file.py """Simple example of using the Vectara REST API for uploading files."""import jsonimport loggingimport requestsdef _get_upload_file_json(): """Returns some example JSON file upload data.""" document = { # Note that the document ID must be unique for a given corpus. "document_id": "doc-id-1", "title": "An example Title", "metadata_json": json.dumps( { "book-name": "An example title", "collection": "Philosophy", "author": "Example Author", } ), "section": [ {"text": "An example text that needs to be indexed."}, ], } return json.dumps(document)def upload_file(customer_id: int, corpus_id: int, idx_address: str, jwt_token: str): """Uploads a file to the corpus. Args: customer_id: Unique customer ID in vectara platform. corpus_id: ID of the corpus to which data needs to be indexed. idx_address: Address of the indexing server. e.g., api.vectara.io jwt_token: A valid Auth token. Returns: (response, True) in case of success and returns (error, False) in case of failure. """ post_headers = { "Authorization": f"Bearer {jwt_token}" } response = requests.post( f"https://{idx_address}/v1/upload?c={customer_id}&o={corpus_id}", files={"file": ("test.json", _get_upload_file_json(), "application/json")}, verify=True, headers=post_headers) if response.status_code != 200: logging.error("REST upload failed with code %d, reason %s, text %s", response.status_code, response.reason, response.text) return response, False message = response.json()["response"] # An empty status indicates success. if message["status"] and message["status"]["code"] not in ("OK", "ALREADY_EXISTS"): logging.error("REST upload failed with status: %s", message["status"]) return message["status"], False return message, True --- # rest_util.py | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/rest_util.py) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [python/vectara-rest/rest\_util.py](https://github.com/vectara/getting-started/tree/main/language-examples/python/vectara-rest/rest_util.py) python/vectara-rest/rest\_util.py """Utility functions for interacting with Vectara over REST."""from authlib.integrations import requests_clientdef get_jwt_token(auth_url: str, app_client_id: str, app_client_secret: str): """Connects to the server and returns a JWT token.""" token_endpoint = f"{auth_url}" session = requests_client.OAuth2Session( app_client_id, app_client_secret, scope="") token = session.fetch_token(token_endpoint, grant_type="client_credentials") return token["access_token"] --- # RestCreateCorpus.java | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/RestCreateCorpus.java) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [java/rest/src/main/java/com/vectara/examples/rest/RestCreateCorpus.java](https://github.com/vectara/getting-started/tree/main/language-examples/java/rest/src/main/java/com/vectara/examples/rest/RestCreateCorpus.java) java/rest/src/main/java/com/vectara/examples/rest/RestCreateCorpus.java package com.vectara.examples.rest;import java.net.URI;import java.net.http.HttpRequest;import java.net.http.HttpRequest.BodyPublishers;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;public class RestCreateCorpus { /** * Calls Vectara Admin platform to create a corpus. * * @param jwtToken A valid JWT token. * @param adminUrl Admin URL at which gRPC endpoints are available. * @param corpusName The name of the corpus to be created. * @param customerId The unique customer ID in Vectara platform. * @return success or failure. */ public static boolean createCorpus( String jwtToken, String adminUrl, String corpusName, long customerId) { String corpusJson = "{" + "\"corpus\":" + "{" + "\"name\":\"" + corpusName + "\"," + "\"description\":\"Dummy description\"" + "}" + "}"; try { HttpRequest.Builder builder = HttpRequest.newBuilder() .uri(URI.create(String.format("https://%s/v1/create-corpus", adminUrl))) .headers( "Content-Type", "application/json", "customer-id", String.valueOf(customerId)) .POST(BodyPublishers.ofString(corpusJson)); builder.header("Authorization", "Bearer " + jwtToken); HttpRequest request = builder.build(); HttpResponse response = RestUtil.newHttpClient().send(request, BodyHandlers.ofString()); /** * Here is how a successful JSON response sample: * { * "corpusId": 1, * "status": { * "code": "OK", * "statusDetail": "Corpus Created" * } * } */ System.out.printf("Create Corpus response: %s", response.toString()); return true; } catch (Exception e) { e.printStackTrace(); return false; } }} --- # RestIndex.java | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/RestIndex.java) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [java/rest/src/main/java/com/vectara/examples/rest/RestIndex.java](https://github.com/vectara/getting-started/tree/main/language-examples/java/rest/src/main/java/com/vectara/examples/rest/RestIndex.java) java/rest/src/main/java/com/vectara/examples/rest/RestIndex.java package com.vectara.examples.rest;import com.fasterxml.jackson.databind.JsonNode;import com.fasterxml.jackson.databind.ObjectMapper;import java.net.URI;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.util.*;public class RestIndex { /** * Indexes a document with a single section and a title. *

* Document can have one or more sections. Sections can be nested. * Title is not required but if provided, it will also get indexed. * * @param jwtToken A valid JWT token. * @param indexingUrl Indexing URL at which gRPC endpoints are available. * @param docTitle document title * @param docText document text to index * @param docId document id * @param customerId The unique customer ID in the Vectara platform. * @param corpusId The unique corpus ID. * @return success or failure. */ public static boolean indexDocument( String jwtToken, String indexingUrl, String docTitle, String docText, String docId, long customerId, long corpusId) { try { ObjectMapper mapper = new ObjectMapper(); Map writeRequest = new HashMap<>(); writeRequest.put("customerId", customerId); writeRequest.put("corpusId", corpusId); Map doc = new HashMap<>(); doc.put("documentId", docId); doc.put("title", docTitle); // optional // let's add some metadata to our document (optional) Map metadata = new HashMap<>(); metadata.put("author", "vectara"); metadata.put("date", new Date().toString()); // metadata has to be added as a json text doc.put("metadataJson", mapper.writer().writeValueAsString(metadata)); // optional List> section = new LinkedList<>(); Map singleSection = new HashMap<>(); singleSection.put("text", docText); // each section can have its own metadata also section.add(singleSection); doc.put("section", section); writeRequest.put("document", doc); String indexJsonRequest = mapper.writer().writeValueAsString(writeRequest); System.out.println(indexJsonRequest); HttpRequest.Builder builder = HttpRequest.newBuilder() .uri(URI.create(String.format("https://%s/v1/index", indexingUrl))) .headers("Content-Type", "application/json", "customer-id", String.valueOf(customerId)) .POST(HttpRequest.BodyPublishers.ofString(indexJsonRequest)); builder.header("Authorization", "Bearer " + jwtToken); HttpRequest httpRequest = builder.build(); HttpResponse response = RestUtil.newHttpClient().send(httpRequest, BodyHandlers.ofString()); System.out.printf("Index response: %s%n", response.toString()); JsonNode responseNode = new ObjectMapper().readTree(response.body()); JsonNode status = responseNode.get("status"); String statusCode = status.get("code").asText(); System.out.println(statusCode); return "OK".equals(statusCode); } catch (Exception e) { e.printStackTrace(); return false; } }} --- # RestDeleteCorpus.cs | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/RestDeleteCorpus.cs) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [csharp/rest/RestDeleteCorpus.cs](https://github.com/vectara/getting-started/tree/main/language-examples/csharp/rest/RestDeleteCorpus.cs) csharp/rest/RestDeleteCorpus.cs using System.Text.Json;class RestDeleteCorpus{ ///

/// Calls Vectara platform to delete a corpus. /// /// The unique customer ID in Vectara platform. /// The unique ID of the corpus to be deleted. /// A valid authentication token. /// Exception if Delete operation fails. public static void DeleteCorpus(long customerId, long corpusId, string jwtToken) { using (var client = new HttpClient()) { try { var request = new HttpRequestMessage { RequestUri = new Uri($"https://{ServerEndpoints.commonEndpoint}/v1/delete-corpus"), Method = HttpMethod.Post, }; Dictionary data = new() { { "customer_id", customerId }, { "corpus_id", corpusId } }; string jsonData = JsonSerializer.Serialize(data); request.Content = new StringContent(jsonData); request.Content.Headers.Remove("Content-Type"); request.Content.Headers.Add("Content-Type", "application/json"); request.Headers.Add("Authorization", $"Bearer {jwtToken}"); request.Headers.Add("customer-id", customerId.ToString()); HttpResponseMessage response = client.Send(request); string result = response.Content.ReadAsStringAsync().Result; Console.WriteLine(result); } catch (Exception) { throw; } } }} --- # RestApiKeyQueries.java | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/RestApiKeyQueries.java) ** (2.0). Version: 1.0 This is a complete example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [java/rest/src/main/java/com/vectara/examples/rest/RestApiKeyQueries.java](https://github.com/vectara/getting-started/tree/main/language-examples/java/rest/src/main/java/com/vectara/examples/rest/RestApiKeyQueries.java) java/rest/src/main/java/com/vectara/examples/rest/RestApiKeyQueries.java package com.vectara.examples.rest;import com.beust.jcommander.JCommander;import java.io.IOException;import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpClient.Redirect;import java.net.http.HttpClient.Version;import java.net.http.HttpRequest;import java.net.http.HttpRequest.BodyPublishers;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;import java.util.logging.Level;import java.util.logging.Logger;/** * A class that demonstrates how Vectara Serving API can be called using REST and an * API Key for authentication. */public class RestApiKeyQueries { private static final Logger LOGGER = Logger.getLogger(RestBasicOperations.class.getName()); public static void main(String[] argv) { RestArgs args = new RestArgs(); JCommander.newBuilder().addObject(args).build().parse(argv); if (args.apiKey == null) { LOGGER.log(Level.SEVERE, "Please provide an API Key to run this example."); System.exit(1); } String apiKey = args.apiKey; var result = queryData(apiKey, args.servingEndpoint, args.query, args.customerId, args.corpusId); if (!result) { LOGGER.log(Level.SEVERE, "Querying failed. Please see previous logs for details."); System.exit(1); } } private static boolean queryData(String apiKey, String servingUrl, String query, Long customerId, Long corpusId) { try { String queryJson = String.format( "{\"query\":" + "[" + "{" + "\"query\":\"%s\"," + "\"numResults\":10," + "\"corpusKey\":" + "[" + "{" + "\"customerId\":%d," + "\"corpusId\":%d," + "\"dim\":[]" + "}" + "]" + "}" + "]" + "}", query, customerId, corpusId); var httpClient = HttpClient.newBuilder() .version(Version.HTTP_2) .followRedirects(Redirect.NORMAL) .connectTimeout(Duration.ofSeconds(20)) .build(); HttpRequest.Builder builder = HttpRequest.newBuilder() .uri(URI.create(String.format("https://%s/v1/query", servingUrl))) .headers( "Content-Type", "application/json", "customer-id", String.valueOf(customerId)) .POST(BodyPublishers.ofString(queryJson)); builder.header("x-api-key", apiKey); HttpRequest request = builder.build(); HttpResponse response = httpClient.send(request, BodyHandlers.ofString()); LOGGER.info(String.format("Querying response: %s", response.toString())); return true; } catch (IOException | InterruptedException e) { LOGGER.log(Level.SEVERE, String.format("Error while indexing data: %s", e)); return false; } }} --- # RestApiKeyQueries.cs | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/RestApiKeyQueries.cs) ** (2.0). Version: 1.0 This is a complete example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [csharp/rest/RestApiKeyQueries.cs](https://github.com/vectara/getting-started/tree/main/language-examples/csharp/rest/RestApiKeyQueries.cs) csharp/rest/RestApiKeyQueries.cs using CommandLine;using Newtonsoft.Json.Linq;using System.Text.Json;using VectaraExampleCommon;namespace VectaraExampleRest{ /// /// A class containing examples about how to use Vectara API using REST and API Key. /// class RestApiKeyQueries { static void Main(string[] args) { _ = Parser.Default.ParseArguments(args) .WithParsed((args) => { try { Query(args.CustomerId, args.CorpusId, "Test Query.", args.ApiKey); } catch (Exception ex) { Console.Error.WriteLine(ex.Message); return; } }) .WithNotParsed((errs) => { foreach (Error err in errs) { Console.Error.WriteLine(err.ToString()); } }); } /// /// Queries a Vectara corpus. /// /// The unique customer ID in Vectara platform. /// The corpus that needs to be queried. /// The query text. /// A valid API Key. /// Exception if no results are found. private static void Query(long customerId, long corpusId, string query, string apiKey) { using (var client = new HttpClient()) { try { var request = new HttpRequestMessage { RequestUri = new Uri($"https://{ServerEndpoints.commonEndpoint}/v1/query"), Method = HttpMethod.Post, }; Dictionary queryData = new(); List queryList = new(); List corpusList = new() { new Dictionary() { {"customerId", customerId}, {"corpusId", corpusId} } }; queryList.Add(new Dictionary() { {"query", query}, {"numResults", 10}, {"corpusKey", corpusList} }); queryData.Add("query", queryList); string jsonData = JsonSerializer.Serialize(queryData); request.Content = new StringContent(jsonData); request.Content.Headers.Remove("Content-Type"); request.Content.Headers.Add("Content-Type", "application/json"); request.Headers.Add("x-api-key", apiKey); request.Headers.Add("customer-id", customerId.ToString()); HttpResponseMessage response = client.Send(request); string result = response.Content.ReadAsStringAsync().Result; JObject resultObj = JObject.Parse(result); JToken? statusArray = resultObj["status"]; if (statusArray == null) { throw new Exception("No results found"); } foreach (var status in statusArray) { JObject statusObj = JObject.Parse(status.ToString()); if (statusObj["code"].ToString() != "OK") { Console.Error.WriteLine(string.Format("Failure status on query: {0}", statusObj["statusDetail"])); } } JToken? responseSetArray = resultObj["responseSet"]; if (responseSetArray == null) { throw new Exception("No results found"); } foreach (var responseSet in responseSetArray) { JObject responseSetObj = JObject.Parse(responseSet.ToString()); JToken? documents = responseSetObj["document"]; foreach (JToken docSection in responseSetObj["response"]) { string text = docSection["text"].ToString(); double score = double.Parse(docSection["score"].ToString()); // doc that this section belongs to int documentIndex = int.Parse(docSection["documentIndex"].ToString()); JToken doc = documents.ElementAt(documentIndex); string docId = doc["id"].ToString(); Console.WriteLine("[score:{0:N2}] [docId:{1}] [text:{2}]", score, docId, text); } } Console.WriteLine(result); } catch (Exception) { throw; } } } }} --- # RestDeleteDocument.cs | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/RestDeleteDocument.cs) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [csharp/rest/RestDeleteDocument.cs](https://github.com/vectara/getting-started/tree/main/language-examples/csharp/rest/RestDeleteDocument.cs) csharp/rest/RestDeleteDocument.cs using System.Text.Json;class RestDeleteDocuement{ /// /// Deletes a document from a corpus using delete-doc API. /// /// The unique customer ID in Vectara platform. /// The corpus ID to which data will be indexed. /// A valid authentication token. /// Id of the document that needs to be deleted. public static void DeleteDocument(long customerId, long corpusId, string jwtToken, string docId) { using (var client = new HttpClient()) { try { var request = new HttpRequestMessage { RequestUri = new Uri($"https://{ServerEndpoints.commonEndpoint}/v1/delete-doc"), Method = HttpMethod.Post, }; Dictionary deleteRequest = new() { { "customerId", customerId }, { "corpusId", corpusId }, { "documentId", docId } }; string jsonData = JsonSerializer.Serialize(deleteRequest); request.Content = new StringContent(jsonData); request.Content.Headers.Remove("Content-Type"); request.Content.Headers.Add("Content-Type", "application/json"); request.Headers.Add("customer-id", customerId.ToString()); request.Headers.Add("Authorization", $"Bearer {jwtToken}"); HttpResponseMessage response = client.Send(request); string result = response.Content.ReadAsStringAsync().Result; Console.WriteLine(result); } catch (Exception) { throw; } } }} --- # RestDeleteDocument.java | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/RestDeleteDocument.java) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [java/rest/src/main/java/com/vectara/examples/rest/RestDeleteDocument.java](https://github.com/vectara/getting-started/tree/main/language-examples/java/rest/src/main/java/com/vectara/examples/rest/RestDeleteDocument.java) java/rest/src/main/java/com/vectara/examples/rest/RestDeleteDocument.java package com.vectara.examples.rest;import com.fasterxml.jackson.databind.JsonNode;import com.fasterxml.jackson.databind.ObjectMapper;import java.net.URI;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.util.HashMap;import java.util.Map;public class RestDeleteDocument { /** * Deletes a document from a corpus. * * @param jwtToken A valid JWT token. * @param indexingUrl Indexing URL at which gRPC endpoints are available. * @param docId document id * @param customerId The unique customer ID in the Vectara platform. * @param corpusId The unique corpus ID. * @return success or failure. */ public static boolean deleteDocument( String jwtToken, String indexingUrl, String docId, long customerId, long corpusId) { try { ObjectMapper mapper = new ObjectMapper(); Map writeRequest = new HashMap<>(); writeRequest.put("customerId", customerId); writeRequest.put("corpusId", corpusId); writeRequest.put("documentId", docId); String deleteJsonRequest = mapper.writer().writeValueAsString(writeRequest); System.out.println(deleteJsonRequest); HttpRequest.Builder builder = HttpRequest.newBuilder() .uri(URI.create(String.format("https://%s/v1/delete-doc", indexingUrl))) .headers("Content-Type", "application/json", "customer-id", String.valueOf(customerId)) .POST(HttpRequest.BodyPublishers.ofString(deleteJsonRequest)); builder.header("Authorization", "Bearer " + jwtToken); HttpRequest httpRequest = builder.build(); HttpResponse response = RestUtil.newHttpClient().send(httpRequest, HttpResponse.BodyHandlers.ofString()); System.out.printf("Delete document response: %s%n", response.toString()); return true; } catch (Exception e) { e.printStackTrace(); return false; } }} --- # RestUploadFile.java | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/RestUploadFile.java) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [java/rest/src/main/java/com/vectara/examples/rest/RestUploadFile.java](https://github.com/vectara/getting-started/tree/main/language-examples/java/rest/src/main/java/com/vectara/examples/rest/RestUploadFile.java) java/rest/src/main/java/com/vectara/examples/rest/RestUploadFile.java package com.vectara.examples.rest;import java.io.File;import java.io.FileOutputStream;import java.io.InputStream;import java.math.BigInteger;import java.net.URI;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.nio.file.Paths;import java.util.LinkedHashMap;import java.util.Map;import java.util.Random;public class RestUploadFile { /** * Indexes some dummy data to a pre-created corpus in a customer account. * * @param jwtToken A valid JWT token. * @param indexingUrl Indexing URL at which gRPC endpoints are available. * @param customerId The unique customer ID in the Vectara platform. * @param corpusId The unique corpus ID. * @return success or failure. */ public static boolean indexFile( String jwtToken, String indexingUrl, long customerId, long corpusId) { Map data = new LinkedHashMap<>(); data.put("c", customerId); data.put("o", corpusId); String filePath = loadFileFromResources(); if (filePath == null) { return false; } data.put("file", Paths.get(filePath)); // Random 256 length string is used as multipart boundary String boundary = new BigInteger(256, new Random()).toString(); try { HttpRequest.Builder builder = HttpRequest.newBuilder() .uri(URI.create(String.format("https://%s/v1/upload", indexingUrl))) .header("Content-Type", "multipart/form-data;boundary=" + boundary) .POST(BodyPublisherHelper.ofMultipartData(data, boundary)); builder.header("Authorization", "Bearer " + jwtToken); HttpRequest request = builder.build(); HttpResponse response = RestUtil.newHttpClient().send(request, BodyHandlers.ofString()); System.out.printf("Index response: %s%n", response.toString()); return true; } catch (Exception e) { e.printStackTrace(); return false; } } private static String loadFileFromResources() { try { InputStream in = RestUploadFile.class.getResourceAsStream("/upload.pdf"); File tempFile = File.createTempFile("temp", ".pdf"); in.transferTo(new FileOutputStream(tempFile)); return tempFile.getAbsolutePath(); } catch (Exception e) { e.printStackTrace(); return null; } }} --- # Role-Based Access Control (RBAC) | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/authentication/role-based-access-control) ** (2.0). Version: 1.0 On this page Authorization refers to the role-based access control policies in Vectara that define what actions an authenticated entity may perform. In this system, **permissions** are specific actions, like running a query against a specific corpus, or resetting its contents. These permissions are grouped together into **roles**, and authenticated entites may be assigned one or more roles. In this context, an **authenticated entity** refers to a user or an app client able to attest its identity by presenting a valid JWT token. Even entities that lack explicit roles may still be able to perform operations on the platform through the use of **default permissions**. RBAC Roles[​](#rbac-roles "Direct link to RBAC Roles") ------------------------------------------------------- This section explains these concepts in further detail: ### Account Level Roles[​](#account-level-roles "Direct link to Account Level Roles") * **Owner** is initially granted to whoever created the account. It grants all the permissions of the admin roles, below, as well as the ability to delete the account. * **Account Administrators** can perform all actions on a account, except managing billing activity. These actions include managing users, API keys, managing corpora etc. * **Corpus Administrators** can perform all corpus related actions within the account. This includes authorizing user roles on an account, deleting a corpus, creating corpora, and transferring ownership of a corpus. * **Billing Administrators** can view and edit account billing activity. ### Corpus Level Roles[​](#corpus-level-roles "Direct link to Corpus Level Roles") Users can also be authorized to perform various actions per corpus. You can assign roles in the Authorization tab on the Corpus page. ![Edit user](/assets/images/corpus_auth-ce1e1ff929be74006c87776dc808d16b.png) * The **Query** role (QRY) allows querying the corpus. * The **Indexing** role (IDX) allows data to be added to the corpus. * The **Administrator** role (ADM) allows query and indexing the corpus, but also resetting it, deleting it, adding and removing user access, and transferring its ownership. A corpus may also specifying querying or indexing as **default roles**. A default role is a role that is granted to any authenticated user in the account. For example, if you want any authenticated user to be able to run queries on the corpus, you would add the query role as default. Account Features[​](#account-features "Direct link to Account Features") ------------------------------------------------------------------------- Account features differ from roles in that they are enforced for the entire account and are generally tied to account tier. These features include: 1. Custom dimensions. Whether custom dimensions may be defined for corpora. 2. Maximum corpora per query. 3. Score retrieval. Whether or not downstream systems have access to the raw answer score. Advanced applications can utilize this information for thresholding, and for incorporation into downstream machine-learning systems. 4. Encoder swapping. Whether the indexing and querying encoders be swapped to support semantic similarity matching in addition to question-answer matching. 5. Textless. Defines whether corpora be built without storing the indexed text. Although all textual content is encrypted with per-corpus keys, this option may appeal when an even higher level of security is desired. Enabling this can potentially reduce the quality of search. 6. User rate limit. Whether per-user rate limits can be defined. 7. Corpus rate limit. Whether per-corpus rate limits can be defined. 8. Corpus encryption key. Whether every corpus uses a separate encryption key for maximum security. Currently this feature is enabled for all accounts and cannot be disabled. 9. Customer managed encryption key. Whether the account may use a customer managed master encryption key. This is an advanced feature that gives the customer total control over their data. By revoking access to the master key, the account will become inaccessible within minutes to the entire platform. 10. Document metadata. Specifies whether document level metadata may be stored while indexing. This is currently enabled for all accounts. 11. Document part metadata. Specifies whether part level metadata may be stored while indexing. This is currently enabled for all accounts. * [RBAC Roles](#rbac-roles) * [Account Level Roles](#account-level-roles) * [Corpus Level Roles](#corpus-level-roles) * [Account Features](#account-features) --- # API Key Management | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/authentication/api-key-management) ** (2.0). Version: 1.0 On this page API Keys allow controlled, anonymous access to several administrative tasks, indexing your data, and running semantic searches on your corpora. This greatly simplifies integration from public-facing systems like websites. You can easily create a [Personal API key](/docs/1.0/console-ui/personal-api-key) or an [Index or Query API Key](/docs/1.0/console-ui/index-and-query-api-keys) , and then simply embed the API key and directly pass it to Vectara when issuing requests. If a key is compromised, you can quickly revoke the key and replace it in minutes. Vectara has three kinds of API keys: Personal API Key[​](#personal-api-key "Direct link to Personal API Key") ------------------------------------------------------------------------- The Personal API Key helps developers in early stages of exploration and prototyping with Vectara. This method provides a straightforward getting started experience for integrating accounts with external applications without the complexity of OAuth authentication. You can use the Personal API Key when putting together a quick prototype, or if you are working on an integration that does not yet support OAuth 2.0. The Personal API Key enables most administrative tasks including creating, deleting, and listing corpora, managing API keys for accessible corpora, reading usage data, updating corpora filters, executing queries, and indexing. You cannot use a Personal API Key to delete an account, validate a registration, transfer account ownership, or access billing data. caution A Personal API Key inherits the permissions of its associated user account. For example, a key generated by a billing admin will **only** possess billing admin-related permissions. Because of their broad access, treat Personal API Keys with the same caution as passwords. Query API Keys[​](#query-api-keys "Direct link to Query API Keys") ------------------------------------------------------------------- Query API Keys are recommended for read-only querying operations and are designed for embedding in code that runs in potentially insecure environments like web browsers or mobile apps. Query API Keys provide the least amount of risk because they have a limited scope and do not modify account data. Index API Keys[​](#index-api-keys "Direct link to Index API Keys") ------------------------------------------------------------------- Index API Keys offer a practical solution for development and testing phases for when you need read and write access. Because they also provide write access, Index API Keys are more powerful than Query API Keys and should be treated like passwords and used with caution in production environments. info Account owners are responsible for charges incurred through anonymous access to your account with any of these API keys. danger πŸ”’ Always keep your API Keys and OAuth tokens private. Do not share them through email, Slack, Discord, forums, or other public channels because it can lead to unauthorized access. Treat these keys with the same confidentiality as your personal credentials. Use an API Key[​](#use-an-api-key "Direct link to Use an API Key") ------------------------------------------------------------------- To use a Personal, Index, or Query API key, pass it using the `x-api-key` header request. * JavaScript * Python * cURL api_key_header = { "customer-id": CUSTOMER_ID, "x-api-key": API_KEY} data_dict = { "query": [ { "query": "What is the meaning of life?", "num_results": 10, "corpus_key": [ { "customer_id": CUSTOMER_ID, "corpus_id": CORPUS_ID } ] } ]}payload = json.dumps(data_dict)response = requests.post( "https://api.vectara.io/v1/query", data=payload, verify=True, headers=api_key_header) fetch("https://api.vectara.io:443/v1/query", { headers: { "Content-Type": "application/json", "x-api-key": api_key, "customer-id": customer_id, }, body: JSON.stringify({ query: [ { query: "What is the meaning of life?", num_results: 10, corpus_key: [{ customer_id: customer_id, corpus_id: corpus_id }], }, ], }), method: "post",}) .then((res) => res.json()) .then((data) => console.log(data)) .catch((error) => console.log(error)); curl -X POST \ -H "x-api-key: ${API_KEY}" \ -H "customer-id: ${CUSTOMER_ID}" \ https://api.vectara.io:443/v1/query \ -d @- < /// Calls Vectara platform to reset a corpus. /// /// The unique customer ID in Vectara platform. /// The unique ID of the corpus to be reset. /// A valid authentication token. /// Exception if Reset operation fails. public static void ResetCorpus(long customerId, long corpusId, string jwtToken) { using (var client = new HttpClient()) { try { var request = new HttpRequestMessage { RequestUri = new Uri($"https://{ServerEndpoints.commonEndpoint}/v1/reset-corpus"), Method = HttpMethod.Post, }; Dictionary data = new() { { "customer_id", customerId }, { "corpus_id", corpusId } }; string jsonData = JsonSerializer.Serialize(data); Console.WriteLine(jsonData); request.Content = new StringContent(jsonData); request.Content.Headers.Remove("Content-Type"); request.Content.Headers.Add("Content-Type", "application/json"); request.Headers.Add("Authorization", $"Bearer {jwtToken}"); request.Headers.Add("customer-id", customerId.ToString()); HttpResponseMessage response = client.Send(request); string result = response.Content.ReadAsStringAsync().Result; Console.WriteLine(result); } catch (Exception) { throw; } } }} --- # uploadFile.php | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/uploadFile.php) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [php/rest/uploadFile.php](https://github.com/vectara/getting-started/tree/main/language-examples/php/rest/uploadFile.php) php/rest/uploadFile.php makeCurlFile('upload.pdf'), 'c' => $customer_id, 'o' => $corpus_id,];curl_setopt($ch, CURLOPT_URL, $url);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type:multipart/form-data', 'Authorization: Bearer ' . $jwt_token,]);curl_setopt($ch, CURLOPT_POSTFIELDS, $upload_data);curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);$result = curl_exec($ch);curl_close($ch);echo $result;?> --- # Authentication Overview | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/authentication/auth-overview) ** (2.0). Version: 1.0 On this page In Vectara, we have robust authentication and authorization methods in place to secure your data and operations. All Vectara APIs are authenticated. Indexing and Search APIs can be authenticated via [Index or Query API Keys](/docs/1.0/learn/authentication/api-key-management#query-api-keys) while, Admin actions (creating/deleting corpora) must be done via [Personal API Keys](/docs/1.0/learn/authentication/api-key-management#personal-api-keys) or [OAuth 2.0](/docs/1.0/learn/authentication/oauth-2) . Choosing Personal API keys, Index API Keys, Query API Keys, or OAuth 2.0[​](#choosing-personal-api-keys-index-api-keys-query-api-keys-or-oauth-20 "Direct link to Choosing Personal API keys, Index API Keys, Query API Keys, or OAuth 2.0") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- When it comes to securing your application and managing access, you have a choice between three different API Keys and OAuth. API Keys can be scoped either to be Adminstrative actions, query (read-only) or both query and index (read-and-write). Personal API Keys inherit the permissions of their associated user account. We recommend that you choose the most limited scope you can for your application: it's "cheap" to create multiple API keys, but having an accidental publication of an over-privileged API key is often organizationally "expensive." In general, we recommend that you use OAuth 2.0 if and where possible for production applications. OAuth can ensure a higher level of security and better protect your sensitive data. Authorization[​](#authorization "Direct link to Authorization") ---------------------------------------------------------------- Authorizations in Vectara include roles at the account and corpus levels. Account features also differ from roles and are generally tied to the account tier. For more details about Vectara's authorization/permissions model, see the [RBAC authorization](/docs/1.0/learn/authentication/role-based-access-control) page. Transport Layer Security (TLS)[​](#transport-layer-security-tls "Direct link to Transport Layer Security (TLS)") ----------------------------------------------------------------------------------------------------------------- All communication to and from the API endpoints take place using an encrypted communication channel (TLS). gRPC handles configuration of the TLS channel using [channel credentials](https://grpc.io/docs/guides/auth/#credential-types) , and you should refer to their documentation. ### Configure channel credentials[​](#configure-channel-credentials "Direct link to Configure channel credentials") The following code snippets show how to configure channel credentials using the default set of root certificates installed on your system, which is usually sufficient. * Java * Python * PHP $channel_creds = Grpc\ChannelCredentials::createSsl(); # Allow the gRPC runtime to load root certificates from the default location.# This is sufficient for most cases.channel_creds = grpc.ssl_channel_credentials()grpc.secure_channel("serving.vectara.io:443", channel_creds) NettyChannelBuilder .forAddress("serving.vectara.io", 443) .sslContext(GrpcSslContexts.forClient() .trustManager(null) // load root certificates from the default location .build()) .build(); * [Choosing Personal API keys, Index API Keys, Query API Keys, or OAuth 2.0](#choosing-personal-api-keys-index-api-keys-query-api-keys-or-oauth-20) * [Authorization](#authorization) * [Transport Layer Security (TLS)](#transport-layer-security-tls) * [Configure channel credentials](#configure-channel-credentials) --- # RestQueryData.cs | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/RestQueryData.cs) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [csharp/rest/RestQueryData.cs](https://github.com/vectara/getting-started/tree/main/language-examples/csharp/rest/RestQueryData.cs) csharp/rest/RestQueryData.cs using System.Text.Json;using Newtonsoft.Json.Linq;class RestQueryData{ /// /// Queries a Vectara corpus. /// /// The unique customer ID in Vectara platform. /// The corpus that needs to be queried. /// The query text. /// A valid authentication token. /// Exception if no results are found. public static void Query(long customerId, long corpusId, string query, string jwtToken) { using (var client = new HttpClient()) { try { var request = new HttpRequestMessage { RequestUri = new Uri($"https://{ServerEndpoints.commonEndpoint}/v1/query"), Method = HttpMethod.Post, }; Dictionary queryData = new(); List queryList = new(); List corpusList = new() { new Dictionary() { {"customerId", customerId}, {"corpusId", corpusId} } }; queryList.Add(new Dictionary() { {"query", query}, {"numResults", 10}, {"corpusKey", corpusList} }); queryData.Add("query", queryList); string jsonData = JsonSerializer.Serialize(queryData); request.Content = new StringContent(jsonData); request.Content.Headers.Remove("Content-Type"); request.Content.Headers.Add("Content-Type", "application/json"); request.Headers.Add("Authorization", $"Bearer {jwtToken}"); request.Headers.Add("customer-id", customerId.ToString()); HttpResponseMessage response = client.Send(request); string result = response.Content.ReadAsStringAsync().Result; JObject resultObj = JObject.Parse(result); JToken? statusArray = resultObj["status"]; if (statusArray == null) { throw new Exception("No results found"); } foreach (var status in statusArray) { JObject statusObj = JObject.Parse(status.ToString()); if (statusObj["code"].ToString() != "OK") { Console.Error.WriteLine(string.Format("Failure status on query: {0}", statusObj["statusDetail"])); } } JToken? responseSetArray = resultObj["responseSet"]; if (responseSetArray == null) { throw new Exception("No results found"); } foreach (var responseSet in responseSetArray) { JObject responseSetObj = JObject.Parse(responseSet.ToString()); JToken? documents = responseSetObj["document"]; foreach (JToken docSection in responseSetObj["response"]) { string text = docSection["text"].ToString(); double score = double.Parse(docSection["score"].ToString()); // doc that this section belongs to int documentIndex = int.Parse(docSection["documentIndex"].ToString()); JToken doc = documents.ElementAt(documentIndex); string docId = doc["id"].ToString(); Console.WriteLine("[score:{0:N2}] [docId:{1}] [text:{2}]", score, docId, text); } } } catch (Exception) { throw; } } }} --- # RestQuery.java | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/RestQuery.java) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [java/rest/src/main/java/com/vectara/examples/rest/RestQuery.java](https://github.com/vectara/getting-started/tree/main/language-examples/java/rest/src/main/java/com/vectara/examples/rest/RestQuery.java) java/rest/src/main/java/com/vectara/examples/rest/RestQuery.java package com.vectara.examples.rest;import com.fasterxml.jackson.databind.JsonNode;import com.fasterxml.jackson.databind.ObjectMapper;import java.net.URI;import java.net.http.HttpRequest;import java.net.http.HttpRequest.BodyPublishers;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.util.Iterator;public class RestQuery { /** * Queries from Vectara Serving platform. * * @param jwtToken A valid JWT token. * @param servingUrl Serving URL at which gRPC endpoints are available. * @param query The query text. * @param customerId The unique customer ID in the Vectara platform. * @param corpusId The unique corpus ID. * @return success or failure. */ public static boolean queryData( String jwtToken, String servingUrl, String query, long customerId, long corpusId) { try { String queryJson = String.format( "{\"query\":" + "[" + "{" + "\"query\":\"%s\"," + "\"numResults\":10," + "\"corpusKey\":" + "[" + "{" + "\"customerId\":%d," + "\"corpusId\":%d," + "\"dim\":[]" + "}" + "]" + "}" + "]" + "}", query, customerId, corpusId); HttpRequest.Builder builder = HttpRequest.newBuilder() .uri(URI.create(String.format("https://%s/v1/query", servingUrl))) .headers( "Content-Type", "application/json", "customer-id", String.valueOf(customerId)) .POST(BodyPublishers.ofString(queryJson)); builder.header("Authorization", "Bearer " + jwtToken); HttpRequest request = builder.build(); HttpResponse response = RestUtil.newHttpClient().send(request, BodyHandlers.ofString()); System.out.printf("Query response: %s", response.toString()); JsonNode responseNode = new ObjectMapper().readTree(response.body()); Iterator responseSetArray = responseNode.get("responseSet").elements(); while (responseSetArray.hasNext()) { JsonNode responseSet = responseSetArray.next(); Iterator docSections = responseSet.get("response").elements(); JsonNode documents = responseSet.get("document"); // array of documents while (docSections.hasNext()) { JsonNode docSection = docSections.next(); String matchingText = docSection.get("text").asText(); double score = docSection.get("score").asDouble(); int documentIndex = docSection.get("documentIndex").asInt(); JsonNode doc = documents.get(documentIndex); // doc that this section belongs to String docId = doc.get("id").asText(); System.out.printf("[score:%.4f] [docId:%s] [text:%s]%n", score, docId, matchingText); } } return true; } catch (Exception e) { e.printStackTrace(); return false; } }} --- # OAuth 2.0 Tokens | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/authentication/oauth-2) ** (2.0). Version: 1.0 On this page Vectara uses "Application clients" to support authentication with OAuth 2.0. These application clients enable you to generate JWT tokens which are used by Vectara to authenticate API requests. If you are not familiar with OAuth, think of it as a more secure way to send API calls, similar to an API key or username/password combination but with enhanced features. The client credentials grant is the OAuth flow that Vectara supports at this time. Here is how it works. You provide the OAuth 2.0 authentication provider with a `client_id` (similar to a username) and a `client_secret` (similar to a password). A successful authentication returns a [JWT token](https://jwt.io/) , which you can then pass into subsequent requests as an authenticated application. 🌟 Ready to Dive In? Check Out Our API Playground! 🌟[​](#-ready-to-dive-in-check-out-our-api-playground- "Direct link to 🌟 Ready to Dive In? Check Out Our API Playground! 🌟") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If already have familiarity about how JWT tokens work and you're ready to dive into our APIs, make your way to our [**API Playground**](/docs/1.0/rest-api/vectara-rest-api) ! This interactive environment allows you to experiment with Vectara's REST APIs directly from your browser! Tailored for developers, the API Playground offers a hands-on experience to understand and demonstrate our capabilities. caution πŸ”’ Always keep your JWT tokens private. Do not share them through email, Slack, Discord, forums, or other public channels because it can lead to unauthorized access. Treat these tokens with the same confidentiality as your personal credentials. Advantages of OAuth 2.0 vs API Keys[​](#advantages-of-oauth-20-vs-api-keys "Direct link to Advantages of OAuth 2.0 vs API Keys") --------------------------------------------------------------------------------------------------------------------------------- OAuth 2.0 takes more work to set up but offer several advantages over API keys: * OAuth 2.0 has built-in revocation flows in case a key is compromised. * The JWT token expires automatically after 30 minutes, so if a JWT token ever does get posted to a public place, it's less likely to be valid by the time an attacker discovers it. * OAuth 2.0 doesn't suffer from information leakage such as the username that created the client. * OAuth 2.0 is inherently more tightly scoped than API keys. * JWT tokens are detected by many security scanning tools, allowing them to more easily be flagged in the case of accidental publication. Authenticate with OAuth 2.0[​](#authenticate-with-oauth-20 "Direct link to Authenticate with OAuth 2.0") --------------------------------------------------------------------------------------------------------- OAuth 2.0 authentication consists of three steps: 1. Create an application client 2. Generate a JWT Token 3. Use the JWT token in an API request ### Create an application client[​](#create-an-application-client "Direct link to Create an application client") Visit the **API access** page in the Console or go to [https://console.vectara.com/console/apiAccess/appClients](https://console.vectara.com/console/apiAccess/appClients) to create a new application client. Applications will use the `client credentials` grant when they generate the JWT token. 1. Click **Create app client**. 2. Enter a **Name** and **Description** for the app client. 3. Select the appropriate roles for the client. 4. Click **Create**. The new app client appears in the list. This page provides three pieces of information that you will use to generate a JWT token: **Authentication URL** Access your authentication by clicking the copy icon for the "OAuth 2.0 authentication URL." ![Copy the Authentication URL](/assets/images/copy_authentication_url-827dc0a1bf757ec80541326513fc5dbc.png) The URL has the following format: `https://vectara-prod-.auth.us-west-2.amazoncognito.com/oauth2/token` **Client ID** Access the `client_id` by clicking the copy icon next to your app client's ID. ![Copy the Client ID](/assets/images/copy_client_id-0bf8a45ee0e6e000dff3a14473adbcb2.png) **Client secret** Access the `client_secret` by clicking the drop-down to the right of your app client and selecting **Copy secret.** ![Copy the Client Secret](/assets/images/copy_client_secret-63918dc0ff23e96abae28dd9e6ae59b8.png) Now that you have values for the authentication URL, `client_id`, and `client_secret`, you can generate a JWT token with a `client-credentials` grant. We provide [client credentials grant examples](/docs/getting-started-samples/JWTFetcher.cs) in different programming languages. ### Generate a JWT Token[​](#generate-a-jwt-token "Direct link to Generate a JWT Token") Use the information from the previous step to send a request to generate a JWT token. The client credentials grant is OAuth flow that Vectara supports at this time. When you create your client credentials grant request, you need the OAuth 2.0 Authentication URL, `client_id`, and `client_secret` values to generate the token correctly. Here's how you can generate a JWT token in JavaScript which is how you authenticate Vectara API requests in a JavaScript application: JavaScript Example const { data: { access_token: jwt }} = await axios({ method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, data: qs.stringify({ grant_type: "client_credentials", client_id: "", client_secret: "" }), url: "https://auth.vectara.io/oauth2/token"}); Here’s how you can generate a JWT token from the command line with a cURL command: cURL Example curl -XPOST -H "Content-type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=&client_secret=" \ https://auth.vectara.io/oauth2/token note This method is useful if you want to try out requests in our [**Vectara API Playground**](/docs/1.0/rest-api/vectara-rest-api) . ### Use the JWT token in an API request[​](#use-the-jwt-token-in-an-api-request "Direct link to Use the JWT token in an API request") To use a JWT token in an API request, pass the token using the `Authorization` header configuration. If you're using the API Playground such as [ListCorpora](/docs/1.0/rest-api/list-corpora) , use the JWT token value in the **Bearer Token** field: ![API Playground Example](/assets/images/api_playground_listcorpora-811f7c70a93ac9e99a22f9374c1b87f3.png) Click **Send API Request** to test the API call. * [🌟 Ready to Dive In? Check Out Our API Playground! 🌟](#-ready-to-dive-in-check-out-our-api-playground-) * [Advantages of OAuth 2.0 vs API Keys](#advantages-of-oauth-20-vs-api-keys) * [Authenticate with OAuth 2.0](#authenticate-with-oauth-20) * [Create an application client](#create-an-application-client) * [Generate a JWT Token](#generate-a-jwt-token) * [Use the JWT token in an API request](#use-the-jwt-token-in-an-api-request) --- # RestIndexData.cs | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/getting-started-samples/RestIndexData.cs) ** (2.0). Version: 1.0 This is an example of using the platform via REST. For more sample code, including any dependencies this file has, please have a look at our GitHub examples repository. This file can be found in that repo at [csharp/rest/RestIndexData.cs](https://github.com/vectara/getting-started/tree/main/language-examples/csharp/rest/RestIndexData.cs) csharp/rest/RestIndexData.cs using Microsoft.Extensions.FileProviders;using System.Net.Http.Headers;using System.Reflection;using System.Security.Cryptography;using System.Text;using System.Text.Json;class RestIndexData{ private static Stream ReadFileFromResource(string dir, string fileName) { var embeddedProvider = new EmbeddedFileProvider(Assembly.GetExecutingAssembly()); return embeddedProvider.GetFileInfo($"{dir}/{fileName}").CreateReadStream(); } /// /// Generates a random key based on the size passed. /// private static string GetRandomKey(int size) { char[] chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890".ToCharArray(); byte[] data = new byte[4 * size]; using (var crypto = RandomNumberGenerator.Create()) { crypto.GetBytes(data); } StringBuilder result = new StringBuilder(size); for (int i = 0; i < size; i++) { var rnd = BitConverter.ToUInt32(data, i * 4); var idx = rnd % chars.Length; result.Append(chars[idx]); } return result.ToString(); } /// /// Indexes data to a pre-created corpus in a customer account using FileUpload API. /// /// The unique customer ID in Vectara platform. /// The corpus ID to which data will be indexed. /// A valid authentication token. /// The name of the file that was uploaded. /// Exception if Index operation fails. public static string IndexViaUpload(long customerId, long corpusId, string jwtToken) { using (var client = new HttpClient()) { try { var request = new HttpRequestMessage { RequestUri = new Uri($"https://{ServerEndpoints.commonEndpoint}/v1/upload"), Method = HttpMethod.Post, }; // Getting a randomly generated key that will be used as boundary in // multipart/form-data request. string boundary = GetRandomKey(8); var multipartContent = new MultipartFormDataContent(boundary); multipartContent.Add(new StringContent(customerId.ToString()), name: "c"); multipartContent.Add(new StringContent(corpusId.ToString()), name: "o"); // File string fileName = "upload.pdf"; var fileStreamContent = new StreamContent(ReadFileFromResource("pdf", fileName)); multipartContent.Add(fileStreamContent, name: "file", fileName: fileName); fileStreamContent.Headers.ContentType = new MediaTypeHeaderValue("application/pdf"); request.Content = multipartContent; request.Content.Headers.Remove("Content-Type"); request.Content.Headers.Add("Content-Type", "multipart/form-data;boundary=" + boundary); request.Headers.Add("Authorization", $"Bearer {jwtToken}"); HttpResponseMessage response = client.Send(request); string result = response.Content.ReadAsStringAsync().Result; Console.WriteLine(result); return fileName; } catch (Exception) { throw; } } } /// /// Indexes some data to a pre-created corpus in a customer account using index API. /// /// The unique customer ID in Vectara platform. /// The corpus ID to which data will be indexed. /// A valid authentication token. /// Exception if Index operation fails. public static void Index(long customerId, long corpusId, string jwtToken) { using (var client = new HttpClient()) { try { var request = new HttpRequestMessage { RequestUri = new Uri($"https://{ServerEndpoints.commonEndpoint}/v1/index"), Method = HttpMethod.Post, }; Dictionary indexData = new(); Dictionary document = new(); Dictionary section = new(); Dictionary docMetadata = new(); Dictionary sectionMetadata = new(); sectionMetadata.Add("SectionHeader", "Aloha!"); section.Add("text", "Some dummy text"); section.Add("metadataJson", JsonSerializer.Serialize(sectionMetadata)); docMetadata.Add("Title", "Vectara"); // Doc id should be unique for every document within this corpus. document.Add("documentId", "doc-id-456789"); document.Add("title", "A Dummy title."); document.Add("metadataJson", JsonSerializer.Serialize(docMetadata)); // Sections can be 0 to many. That's why following code creates a list and adds // one section to that list. You can add as many as you like. document.Add("section", new List() {section}); indexData.Add("customerId", customerId); indexData.Add("corpusId", corpusId); indexData.Add("document", document); string jsonData = JsonSerializer.Serialize(indexData); request.Content = new StringContent(jsonData); request.Content.Headers.Remove("Content-Type"); request.Content.Headers.Add("Content-Type", "application/json"); request.Headers.Add("customer-id", customerId.ToString()); request.Headers.Add("Authorization", $"Bearer {jwtToken}"); HttpResponseMessage response = client.Send(request); string result = response.Content.ReadAsStringAsync().Result; Console.WriteLine(result); } catch (Exception) { throw; } } }} --- # Keeping Your Data Private | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/data-privacy/privacy-overview) ** (2.0). Version: 1.0 At Vectara, we treat your data with the utmost privacy: * We do not use your data or searches to train our models. * We isolate all customer instances from each other. * We build Vectara to protect and encrypt each corpus with distinct symmetric keys. If any individual corpus is compromised, the rest remain safe. * We encrypt your data in-flight using [Transport Layer Security (TLS)](/docs/learn/authentication/auth-overview#transport-layer-security-tls) . * We encrypt your data on disk. [Scale plan users](https://vectara.com/pricing/) can even [create and manage their own encryption keys](/docs/1.0/learn/data-privacy/encryption) . To learn more about how we approach security at Vectara, read [https://vectara.com/legal/security-at-vectara/](https://vectara.com/legal/security-at-vectara/) . --- # Data Encryption | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/data-privacy/encryption) ** (2.0). Version: 1.0 On this page When you send documents to the [index API](/docs/1.0/api-reference/indexing-apis/indexing) or [file upload API](/docs/1.0/api-reference/indexing-apis/file-upload/file-upload) , Vectara indexes both the document text and metadata. If you choose the β€œtextless” option (Scale users) for [corpus creation](/docs/1.0/api-reference/admin-apis/create-corpus) , Vectara converts the document text into vectors for indexing but **does not** store the text anywhere in the platform. However, metadata is always stored. note For the safety of your data, Vectara always stores your text and metadata in an encrypted format. By default this encryption uses Vectara's own encryption key to encrypt your data (text and/or metadata). For [Scale accounts](https://vectara.com/pricing/) Vectara also allows you to use your own AWS KMS encryption key so that you have full control over how your data is encrypted. If you would like to do so, follow the instructions below. caution If you use your own key and at some point disable your AWS KMS key, there is no way to encrypt or decrypt your data so your corpus will not be queryable by anyone until you enable the key back. You can disable and enable your KMS key to resume service but you should be very careful when removing your AWS KMS key as this is a permanently destructive action. If you remove the AWS KMS key entirely, neither you nor Vectara will be able to recover that encryption key, which also means any Vectara corpora depending on that key will be inaccessible forever. Create your AWS KMS key[​](#create-your-aws-kms-key "Direct link to Create your AWS KMS key") ---------------------------------------------------------------------------------------------- KMS keys are only available to Scale plan accounts. If you need help with setting up your customer-managed key, [reach out to support](https://vectara.com/contact-us/) . To create an AWS KMS key: 1. Go to KMS on the AWS Console 2. Select **Customer Managed Keys** 3. Select **Create key**. 4. Set **Key Type** to "Symmetric" and **Key Usage** to β€œEncrypt and decrypt”. 5. In the **Advanced options**: 1. Ensure that "KMS" is selected for the **Key material origin**. 2. For the regionality: 1. Both β€œSingle-Region key” and β€œMulti-Region key” are ok if the key is created in the `us-west-2` region. 2. If the key is not created in `us-west-2`, it needs to be created as a "Multi-Region key." Then, after creating the key, go to the **Regionality** tab and create a replica key in `us-west-2` by clicking **Create new replica keys**. 3. Eventually, the created key’s ARN should start with `arn:aws:kms:us-west-2` 6. On the β€œDefine key usage permissions” step of the key creation wizard, you should see the β€œOther AWS Accounts” section at the bottom. Enter `941566284283` as the AWS ID (this is Vectara's production AWS account ID). You are giving permission to Vectara to use your key to encrypt and decrypt your indexed documents. 7. On the last β€œReview” step, update the following section and update the ARN from `arn:aws:iam::941566284283:root` to `arn:aws:iam::941566284283:role/prod-eks2021021409582096910000000b` The key should look like the following: { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::941566284283:role/prod-eks2021021409582096910000000b" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*"} The final step to creating the AWS KMS key to finish the key creation. Attach your AWS KMS key to your account[​](#attach-your-aws-kms-key-to-your-account "Direct link to Attach your AWS KMS key to your account") ---------------------------------------------------------------------------------------------------------------------------------------------- In order to get Vectara to use your key, you must contact Vectara Support. Send us the ARN for the KMS key you created (starting with `arn:aws:kms:us-west-2`). The Vectara team will set up the configuration for you. In the future, you will be able to set the ARN on the Vectara Console and these instructions will be updated. How the encryption key works[​](#how-the-encryption-key-works "Direct link to How the encryption key works") ------------------------------------------------------------------------------------------------------------- Once your AWS KMS key is configured in the platform, when encrypting your document text or metadata, Vectara connects to your KMS service to generate an encryption key. The encryption key provided by the KMS is stored in-memory and used to encrypt and decrypt your data. The in-memory key expires every hour. In turn, every hour Vectara asks your AWS KMS to generate that encryption key again. * [Create your AWS KMS key](#create-your-aws-kms-key) * [Attach your AWS KMS key to your account](#attach-your-aws-kms-key-to-your-account) * [How the encryption key works](#how-the-encryption-key-works) --- # Textless Mode | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/data-privacy/textless) ** (2.0). Version: 1.0 On this page When you create a corpus [via the API](/docs/1.0/api-reference/admin-apis/create-corpus) or the [Vectara Console UI](/docs/1.0/console-ui/creating-a-corpus) , you have the option to **not** store the text, also known as a "textless" mode. This mode is available to our [Scale plan users](https://vectara.com/pricing/) for when you have very sensitive text content. The text content becomes unrecoverable to Vectara or to any user who successfully queries and finds the document. tip Textless mode is optimal for use cases where the cost of any information leakage is very high. Vectara does [**encrypt documents**](/docs/1.0/learn/data-privacy/encryption) . What happens in textless mode?[​](#what-happens-in-textless-mode "Direct link to What happens in textless mode?") ------------------------------------------------------------------------------------------------------------------ Let's look at when it's appropriate to enable textless, what happens on the platform, and what benefits and limitations it brings. When you enable `textless` on a corpus, Vectara discards the text content of the document immediately after it converts the text to a vector. At that point, the text is no longer recoverable. It also won't be returned in any Vectara APIs. note Vectara **does** retain any metadata that were supplied alongside the text, including document IDs. This retention lets you retrieve the document from a separate system of record based on the ID to show the metadata, and it also allows Vectara to perform any metadata-based filtering on the document. Enable Textless mode[​](#enable-textless-mode "Direct link to Enable Textless mode") ------------------------------------------------------------------------------------- To enable textless mode, set the `textless` value to `true` under `corpus`: curl -X POST \-H "Authorization: Bearer abcefg..." \-H "customer-id: 123456789" \https://api.vectara.io:443/v1/create-corpus \-d @- <" \-H "customer-id: 1234567899" \https://api.vectara.io:443/v1/query \-d @- < 3.0 and part.lang = 'deu' The `lang` metadata tag used in this example is detected and set automatically by the platform at indexing time. It's set at the part level for accuracy, because a single document may contain content in multiple languages. More complicated expressions are possible, such as the one below, which checks for documents with a publication date in 2021. 1609459200 < doc.pub_epoch and doc.pub_epoch < 1640995200 Here, `pub_epoch` stores the date in [epoch time](https://en.wikipedia.org/wiki/Unix_time) . You can find a full list of supported syntax on the [Functions and Operators](/docs/api-reference/search-apis/sql/func-opr) page. --- # Question-Answer Matching System | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/question-answer/question-answer-overview) ** (2.0). Version: 1.0 On this page Some users have frequently asked question (FAQ) databases or other forms of question databases where the use case demands that your users are trying to find the _nearest question_ to their own, so you can provide them with the authoritative answer from the "answer" side of the question-answer database. This approach may not offer the dynamic nature of Retrieval Augmented Generation (RAG), but it allows you to establish tight controls over the types of questions that users can ask and receive authorizative answers. These question-answer systems can be great for building RFP-answering systems for employees and FAQ lookups for customers. Format data for indexing[​](#format-data-for-indexing "Direct link to Format data for indexing") ------------------------------------------------------------------------------------------------- When you send data to Vectara for this use case, we recommend that you index the question in the `title` field and the answer to that question in the `text` content. For example: document.json { "customerId": 123456, "corpusId": 1, "document": { "documentId": "who-is-the-king-of-england", "title": "Who is the King of England?", "section": [ { "text": "Charles III" } ] }} Query for similar questions[​](#query-for-similar-questions "Direct link to Query for similar questions") ---------------------------------------------------------------------------------------------------------- Suppose you wanted to find the answer to a question related to this example. You can put Vectara into a document-matching mode by setting `semantics` to `RESPONSE`. For example: https://api.vectara.io/v1/query { "query": [ { "query": "Who's the English monarch?", "start": 0, "numResults": 10, "corpusKey": [ { "customerId": 12345678, "corpusId": 1, "semantics": "RESPONSE" } ] } ]} This `RESPONSE` setting disables Vectara's "question-answering" mode and instead tells it to find similar questions. You can also add a [filter expression](/docs/1.0/learn/metadata-search-filtering/filter-overview) of `part.is_title = true` to _only_ match the questions. Combine question matching and answering[​](#combine-question-matching-and-answering "Direct link to Combine question matching and answering") ---------------------------------------------------------------------------------------------------------------------------------------------- Expanding on the previous example, we can help users find question or answer matches together by using [batched queries](/docs/1.0/api-reference/search-apis/batched-queries) combined with filter expressions. For example: https://api.vectara.io/v1/query { "query": [ { "query": "Who's the English monarch?", "start": 0, "numResults": 10, "corpusKey": [ { "customerId": 12345678, "corpusId": 1, "semantics": "RESPONSE", "metadataFilter": "part.is_title = true" } ] }, { "query": "Who's the English monarch?", "start": 0, "numResults": 10, "corpusKey": [ { "customerId": 12345678, "corpusId": 1, "metadataFilter": "part.is_title IS NULL" } ] } ]} * [Format data for indexing](#format-data-for-indexing) * [Query for similar questions](#query-for-similar-questions) * [Combine question matching and answering](#combine-question-matching-and-answering) --- # Retrieval Augmented Generation (RAG) Overview | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/grounded-generation/grounded-generation-overview) ** (2.0). Version: 1.0 On this page Retrieval Augmented Generation (RAG) ensures that generated content is both verifiable and anchored to the data you supply. This minimizes the occurrence of [hallucinations](https://vectara.com/avoiding-hallucinations-in-llm-powered-applications/) (innaccurate or misleading information) commonly found in generative AI systems. Vectara's Retrieval Augmented Generation summarizes search results that answer complex queries directly while providing citations that ground these search results in facts from the data. ![Retrieval Augmented Generation (RAG) Summary Example](/assets/images/grounded_generation_summary_example-d6a61c9ddd2be57c29cc5902d32bcadc.png) Enable Summarization in a Query[​](#enable-summarization-in-a-query "Direct link to Enable Summarization in a Query") ---------------------------------------------------------------------------------------------------------------------- Summarization provides a chatbot-like experience to your users. To enable this behavior, send a `summary` request with your `query`. For example: https://api.vectara.io/v1/query { "query": [ { "query": "What is the infinite improbability drive?", "start": 0, "numResults": 10, "corpusKey": [ { "customerId": 12345678, "corpusId": 1, } ], "summary": [ { "summarizerPromptName": "vectara-summary-ext-v1.2.0", "responseLang": "en", "maxSummarizedResults": 5 } ] } ]} This query tells Vectara to return a summary in English using the `vectara-summary-ext-v1.2.0` summarizer and to consider the first 5 results when summarizing. note The `summarizerPromptName` is optional and will default to the best summarizer available to your account type. Only Scale users can change this value. When Vectara responds, it will contain the list of results as well as the generative summary. Here is an example response to the query `What is the infinite improbability drive?` when searching across the Hitchhiker's Guide to the Galaxy: response.json [ { "summary": { "text": "\nThe Infinite Improbability Drive is a form of propulsion developed by the Galactic Government on Damogran which allows for vast interstellar distances to be crossed in a nothingth of a second without the use of hyperspace [3]. It is incredibly powerful and rare, with only rumors circulating of its existence prior to its development [1]. It has been known to cause problems with other forms of propulsion, like the photon drive [4]. It is a remarkable breakthrough in Improbability Physics [2].", "lang": "eng", "statusList": [], "futureId": 2 }, "statusList": [] }, { "responseSet": { "responseList": [ { "text": "FordΒ wasΒ wildlyΒ excited. \"Arthur!\"Β heΒ said,Β \"thisΒ isΒ fantastic! We'veΒ beenΒ pickedΒ upΒ byΒ aΒ shipΒ \npoweredΒ byΒ theΒ InfiniteΒ ImprobabilityΒ Drive! ThisΒ isΒ incredible!Β IΒ heardΒ \nrumorsΒ aboutΒ itΒ before! TheyΒ wereΒ allΒ officiallyΒ denied,Β butΒ theyΒ mustΒ \nhaveΒ doneΒ it!", "score": 0.9203816652297974, "metadataList": [ { "name": "title", "value": "Chapter 9" }, { "name": "lang", "value": "eng" }, { "name": "breadcrumb", "value": "[\"THE HITCHHIKER'S GUIDE TO THE GALAXY\"]" }, { "name": "section", "value": "12" }, { "name": "offset", "value": "8137" }, { "name": "len", "value": "76" } ], "documentIndex": 0, "corpusKey": { ... }, "resultOffset": 79, "resultLength": 76 }, { "text": "Look,Β IΒ wasΒ right.\"Β  Β \nFordΒ jabbedΒ atΒ oneΒ ofΒ theΒ pagesΒ andΒ showedΒ itΒ toΒ Arthur.Β Β \n\" ItΒ says:Β 'SensationalΒ newΒ breakthroughΒ inΒ ImprobabilityΒ Physics. AsΒ \nsoonΒ asΒ theΒ ship'sΒ driveΒ reachesΒ InfiniteΒ ImprobabilityΒ itΒ passesΒ \nthroughΒ everyΒ pointΒ inΒ theΒ Universe. BeΒ theΒ envyΒ ofΒ otherΒ majorΒ \ngovernments. 'Β Wow,Β thisΒ isΒ bigΒ leagueΒ stuff.", "score": 0.8904105424880981, "metadataList": [ { "name": "title", "value": "Chapter 11" }, { "name": "lang", "value": "eng" }, { "name": "breadcrumb", "value": "[\"THE HITCHHIKER'S GUIDE TO THE GALAXY\"]" }, { "name": "section", "value": "14" }, { "name": "offset", "value": "8211" }, { "name": "len", "value": "107" } ], "documentIndex": 0, "corpusKey": { ... }, "resultOffset": 164, "resultLength": 107 }, { "text": "ChapterΒ 10 Chapter 10 TheΒ InfiniteΒ ImprobabilityΒ DriveΒ isΒ aΒ wonderfulΒ newΒ methodΒ ofΒ \ncrossingΒ vastΒ interstellarΒ distancesΒ inΒ aΒ mereΒ nothingthΒ ofΒ aΒ second,Β \nwithoutΒ allΒ thatΒ tediousΒ muckingΒ aboutΒ inΒ hyperspace. ItΒ wasΒ discoveredΒ byΒ aΒ luckyΒ chance,Β andΒ thenΒ developedΒ intoΒ aΒ \ngovernableΒ formΒ ofΒ propulsionΒ byΒ theΒ GalacticΒ Government'sΒ researchΒ \nteamΒ onΒ Damogran. This,Β briefly,Β isΒ theΒ storyΒ ofΒ itsΒ discovery.", "score": 0.8826565742492676, "metadataList": [ { "name": "title", "value": "Chapter 10" }, { "name": "lang", "value": "eng" }, { "name": "breadcrumb", "value": "[\"THE HITCHHIKER'S GUIDE TO THE GALAXY\"]" }, { "name": "section", "value": "13" }, { "name": "offset", "value": "8" }, { "name": "len", "value": "187" } ], "documentIndex": 0, "corpusKey": { ... }, "resultOffset": 37, "resultLength": 187 }, { "text": "TheΒ photonΒ driveΒ gaveΒ aΒ sicklyΒ judderΒ andΒ cutΒ outΒ again. saidΒ Arthur.Β Β \n\"Hey,Β didjaΒ hearΒ that?\" mutteredΒ ZaphodΒ asΒ heΒ leaptΒ nowΒ forΒ theΒ \nmanualΒ controlsΒ ofΒ theΒ InfiniteΒ ImprobabilityΒ Drive,Β \"theΒ monkeyΒ \nspoke!\" TheΒ ImprobabilityΒ DriveΒ gaveΒ twoΒ smallΒ whinesΒ andΒ thenΒ alsoΒ cutΒ \nout. \"PureΒ history,Β man,\"Β saidΒ Zaphod,Β kickingΒ theΒ ImprobabilityΒ Drive,Β \n\"aΒ talkingΒ monkey!\"", "score": 0.7908053398132324, "metadataList": [ { "name": "title", "value": "Chapter 3" }, { "name": "lang", "value": "eng" }, { "name": "breadcrumb", "value": "[\"THE RESTAURANT AT THE END OF THE UNIVERSE\"]" }, { "name": "section", "value": "42" }, { "name": "offset", "value": "769" }, { "name": "len", "value": "114" } ], "documentIndex": 0, "corpusKey": { ... }, "resultOffset": 111, "resultLength": 114 }, ... ], "documentList": [ { "id": "TheultimateHitchhikersGuide.pdf", "metadataList": [ { "name": "Author", "value": "Douglas Neil Adams" } ] } ], "futureId": 1 } }, { ... }] You can see in the results that the specific sources are referenced in the `summary`. Vectara issues these citations by putting them in `[number]` format in the summary text, where `number` starts from 1 and increases by 1 in each result in the `responseList`. Factual Consistency Score - Evaluate Hallucinations[​](#factual-consistency-score---evaluate-hallucinations "Direct link to Factual Consistency Score - Evaluate Hallucinations") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In your summarization request, you can set the `factual_consistency_score` field to `true`. Enable the Factual Consistency Score "summary": [ { "max_summarized_results": 3, "response_lang": "en", "factual_consistency_score": true }, } ] The Vectara Factual Consistency Score automatically evaluates and detects hallucinations in generated output. This score can range from `0.0` to `1.0`. Higher scores indicate a greater probability of being factually accurate, while lower scores indicate a greater probability of hallucinations. In the following example, the summary shows a `factualConsistency` score of `0.98`, which is 98%. Example Factual Consistency Score "summary": [ { "text": "According to the novel 'The Hitchhiker's Guide to the Galaxy' by Douglas Adams, the answer to the ultimate question of life, the universe, and everything is 42.", "lang": "en", "factualConsistency": { "score": 0.98 "status":{ "code":"OK", "statusDetail":"", "cause":null } }, } ] * [Enable Summarization in a Query](#enable-summarization-in-a-query) * [Factual Consistency Score - Evaluate Hallucinations](#factual-consistency-score---evaluate-hallucinations) --- # Default Metadata Filters | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/metadata-search-filtering/ootb-metadata-filters) ** (2.0). Version: 1.0 On this page A few pieces of metadata expressions filterable out of the box, as they're very useful in a variety of situations. Note that you can set up additional fields to filter on by setting up [filter attributes](/docs/1.0/api-reference/admin-apis/create-corpus#filter-attribute) on a corpus. `doc.id` field[​](#docid-field "Direct link to docid-field") ------------------------------------------------------------- Each document is assigneed a unique identifier at indexing. You can use the `doc.id` field to retrieve or filter specific documents in your corpus. Valid filter expressions include something like: * `doc.id` = 'my-document-2023.pdf' * `doc.id` = 'my-document-2022.pdf' OR 'my-document-2023.pdf' * `doc.id` = 'my-document-2023.pdf' AND 'my-document-2024.pdf' `part.lang` field[​](#partlang-field "Direct link to partlang-field") ---------------------------------------------------------------------- Each section of a document is evaluated for its language at index time and the `part.lang` field is added with a 3-character lower-case language code ([ISO 639-2](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) ). For example, if the section was detected as English, then `part.lang` would contain `eng` and if it was detected as German, than `part.lang` would contain `deu`. Valid filter expressions for this would be something like: * `part.lang = 'eng'` * `part.lang = 'deu'` * `part.lang = 'eng' OR part.lang = 'deu'` `part.is_title` field[​](#partis_title-field "Direct link to partis_title-field") ---------------------------------------------------------------------------------- When adding content, Vectara will add a special Boolean field to indicate whether the field is a title field or not. This is useful for a few different cases depending on how you model your data. For example, some users want to only match on a title field or never match on a title field, in which case this field can be used to filter. To filter for title fields only, you can use: `part.is_title = true` and conversely `part.is_title = false` will return only non-title sections. * [`doc.id` field](#docid-field) * [`part.lang` field](#partlang-field) * [`part.is_title` field](#partis_title-field) --- # Semantic Search Fundamentals | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/semantic-search/semantic-search-overview) ** (2.0). Version: 1.0 On this page Vectara lets you build a semantic, LLM-powered search application. Semantic search is not just about finding data, but about understanding data and helping you answer questions about your data. This topic outlines what Vectara can do for this use case as well as why and how to employ these features for the best overall end-user experience. Large Language Models (LLMs)[​](#large-language-models-llms "Direct link to Large Language Models (LLMs)") ----------------------------------------------------------------------------------------------------------- [LLMs](https://en.wikipedia.org/wiki/Large_language_model) are deep neural nets that are built with the task of specifically understanding human language. These models can be a great asset to many different use cases, including search and language generation. These models generally work by reading immense amounts of text to build the model and then using that model to convert text into vectors, both at index and at query time. For many use cases, this obviates the need for many language rules of traditional keyword systems like synonym management, stemming, and phrase parsing because the LLM can inherently understand what the user is asking. The team behind Vectara has built LLMs that work across a wide variety of languages and verticals. When you index data into Vectara or perform a search, also known as retrieval, the text is converted to one or more vectors via a LLM and then used to answer questions that your users have. Zero-shot models[​](#zero-shot-models "Direct link to Zero-shot models") ------------------------------------------------------------------------- [Zero-shot](https://en.wikipedia.org/wiki/Zero-shot_learning) models have an excellent understanding of language in general. They can understand and respond to the semantic meaning of questions without any additional tuning. This obviates much of the need for fine-tuning and specialized training on a particular dataset or in a particular vertical. The Vectara platform makes extensive use of zero-shot models that have been developed by the team to allow your end users to query using the language and verbiage of their choosing and find the right documents, regardless of the domain your documents are in. Hybrid search[​](#hybrid-search "Direct link to Hybrid search") ---------------------------------------------------------------- While zero-shot LLMs work very well in the vast majority of search use cases, there are some occasions where they struggle. In particular, many zero-shot LLMs don't work as well when users perform queries for things which have little semantic meaning. For example, a UPC code, barcode number, or particular named configuration setting has little to no semantic meaning, and if you expect your users to perform this type of search, it's best to look into our [hybrid search](/docs/1.0/learn/hybrid-search) documentation to learn about how to blend neural search and keyword search. * [Large Language Models (LLMs)](#large-language-models-llms) * [Zero-shot models](#zero-shot-models) * [Hybrid search](#hybrid-search) --- # Vectara Prompt Engine | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/prompts/vectara-prompt-engine) ** (2.0). Version: 1.0 On this page The Vectara Prompt Engine empowers Scale users to customize prompts that can reference the most relevant text and metadata for use cases that require Retrieval Augmented Generation (RAG). Vectara enables developers to directly add the retrieved documents and their metadata into the prompt generation. Vectara supports [Velocity Templates](https://velocity.apache.org/engine/1.7/user-guide.html) which offer developers a flexible way of customizing prompts and enhance the effectiveness of their generative AI applications. This capability unlocks more advanced workflows and customizations to answer questions about your business data. For example, answer questions based on previous answers, such as with RFI, RFP, and questionnaires. Draft support tickets from user feedback. You can even customize the formatting of results. Effective Prompts[​](#effective-prompts "Direct link to Effective Prompts") ---------------------------------------------------------------------------- Effective prompts guide LLMs to generate responses that meet specific user needs or objectives in generative AI applications. Define an objective that outlines what you aim to achieve, and provide detailed context to enrich the prompts with nuanced background information to help the AI understand the scenario better. Iteration and refinement are important processes to help you improve the outcome of your prompts. note Reach out to support if you want to modify the default prompt. Prompt Design[​](#prompt-design "Direct link to Prompt Design") ---------------------------------------------------------------- Prompt design includes a specific a `role` and `content` about this role, which provide context about how you want the role to behave and the kind of information that you want to retrieve. These values can also specify [variables and functions](/docs/prompts/custom-prompts-with-metadata) to provide more nuanced context. You then add different operations to customize the types of answers you want to retrieve. ### Role[​](#role "Direct link to Role") The `role` specifies the function of the individual or entity that you want to respond to the prompt. This function indicates the rules, responsibilities, and perspective of the action being performed. The typical role value is `system`. You then add context to this system with a `content` value such as `You are a helpful search assistant.` You could also specify the platform or environment within which you want the prompt issued and subsequent action taken and other rules that you want the system to follow. ### Content[​](#content "Direct link to Content") The `content` provides more information about the role and what you expect the entity to perform. This is crucial when you have loops and iterations in your prompts, like in our example. For each loop, specify the precise action or feedback desired from the prompt. Capture the context of what needs to be accomplished or directed. Clear and concise content helps ensure that the prompt communicates its intent effectively. Example content can include β€œYou are a helpful search assistant” or β€œGenerate a summary for the query”. Example Prompt Template[​](#example-prompt-template "Direct link to Example Prompt Template") ---------------------------------------------------------------------------------------------- The following example prompt specifies a role as a helpful search assistant. It then loops through Vectara query results with specific variables and functions. Finally, it generates a summary for the query. [ {"role": "system", "content": "You are a helpful search assistant."}, #foreach ($qResult in $vectaraQueryResults) {"role": "user", "content": "Give me the $vectaraIdxWord[$foreach.index] search result."}, {"role": "assistant", "content": "${qResult.getText()}" }, #end {"role": "user", "content": "Generate a summary for the query \"${vectaraQuery}\" based on the above results."}] * [Effective Prompts](#effective-prompts) * [Prompt Design](#prompt-design) * [Role](#role) * [Content](#content) * [Example Prompt Template](#example-prompt-template) --- # Select the Ideal Indexing API for Your Needs | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/select-ideal-indexing-api) ** (2.0). Version: 1.0 Selecting the ideal Indexing API for your application can significantly impact the effectiveness of integrating Vectara’s search functionalities into your application. The best indexing method depends on your needs, such as when you have semi-structured or unstructured documents, or if you want more granular control over the data segmentation and indexing process. Vectara offers the following indexing APIs for these different scenarios: * [**File Upload API**](/docs/1.0/api-reference/indexing-apis/file-upload/file-upload) If you want to extract text from existing, unstructured documents in common file types with minimal manual intervention, use the File Upload API. This option enables you to attach additional, user-defined metadata at the document level. You can also upload JSON versions of the same Document protocol buffers passed to the standard indexing API and the low-level indexing API, as long as the file ends with the `.json` extension. Our platform intelligently determines which flavor of document proto it's looking at. Note that sending any other kind of JSON to the indexing endpoint will cause it to error out. We recommend this option if you have not written your own extraction logic already. * [**Standard Indexing API**](/docs/1.0/api-reference/indexing-apis/indexing) If you have structured documents that you want Vectara to index and segment into chunks for you, use the standard indexing API. In Vectara, a `document` is very flexible in what it can represent. It can be as short as a tweet or as long as the 1600 page Bible. The `document` object typically includes unique identifiers like `title`, `description`, and `metadata` that you can leverage. The document is also broken down into sections. Each `section` can have a unique `id`, `title`, `text`, and `metadata`. Each section can also contain other sections. We recommend this option for applications where documents already have a clear and consistent structure like news articles, product descriptions, rows in database tables or CSV files, or records from an ERP system. * [**Low-Level Indexing API**](/docs/1.0/api-reference/indexing-apis/core_indexing) For the most advanced use cases, if you want full, granular control to chunk your document into `parts`, use the low-level indexing API. These documents also have a unique ID and metadata, but you also define individual document `parts` which make up granular sections of the overall document container. These parts define the actual text to be indexed. Each part is converted into exactly one vector in the underlying index. Each part can contain individual `text` blocks, `context`, and `metadata`, as well as custom dimension values that affect ranking results. We recommend this option for Machine Learning teams with expertise in neural information retrieval who want low-level control over how documents are indexed in our systems. Using the low-level API typically involves significant coordination between your Machine Learning team and organizational stakeholders. --- # Relevance Tuning Techniques | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/semantic-search/relevance-tuning-techniques) ** (2.0). Version: 1.0 On this page By default, Vectara uses a form of "question-answer" similarity to produce the scoring. This provides a very robust ability to answer your users questions. By default, scores go from -1 to 1 where a score of -1 would be "completely irrelevant" and a score of 1 would be a near/exact match. There are several controls which affect these scores and the associated result rankings. Custom dimensions[​](#custom-dimensions "Direct link to Custom dimensions") ---------------------------------------------------------------------------- [Custom dimensions](/docs/1.0/learn/semantic-search/add-custom-dimensions) provide [our Scale users](https://vectara.com/pricing/) with a fixed set of additional "dimensions" that contain user-defined numerical values and are stored in addition to the vectors that Vectara automatically extracts and stores from the text. At query time, users can use these custom dimensions to increase or decrease the resulting score dynamically, query by query. Custom dimensions are great to hold metadata like "upvotes" of a post, number of times a product has been purchased, and similar measures of business/relevance value. Hybrid search[​](#hybrid-search "Direct link to Hybrid search") ---------------------------------------------------------------- By default, Vectara uses purely semantic similarity when evaluating whether a document/section is responsive to a particular search. However, we often find that with a _slight_ introduction of keyword-focused algorithms, the relevance can be much better. Vectara supports this out of the box via [hybrid search](/docs/1.0/learn/hybrid-search) . Alternative similarity measures[​](#alternative-similarity-measures "Direct link to Alternative similarity measures") ---------------------------------------------------------------------------------------------------------------------- While Vectara uses question-answer style similarity by default, sometimes it's advantageous to use document-document similarity. For example, think of a case where a user asks "where can I find great tacos?" You typically wouldn't want to match the _closest_ document to that question (e.g. one that just has the text "where can I find great tacos") but instead a document that _answers_ that question (e.g. "you can find the best tacos at **\_\_\_**"). However, there are times when finding the most semantically similar documents is advantageous. In particular, [recommendation systems](/docs/1.0/learn/recommendation-systems/recommender-overview) tend to make heavy use of document similarity metrics. However, these can be useful in other use cases as well, including [matching questions](/docs/1.0/learn/question-answer/question-answer-overview) in FAQ search systems. Interpreting scores[​](#interpreting-scores "Direct link to Interpreting scores") ---------------------------------------------------------------------------------- If you want to understand a bit more about why Vectara produced a particular score, have a look at our [interpreting scores](/docs/1.0/api-reference/search-apis/interpreting-responses/interpreting-scores) documentation. Low-level indexing controls[​](#low-level-indexing-controls "Direct link to Low-level indexing controls") ---------------------------------------------------------------------------------------------------------- Sometimes, the best solution to changing relevance is by adjusting the low-level indexing controls. Vectara supports fine-grained tuning of this in the [low-level](/docs/1.0/api-reference/indexing-apis/core_indexing) API. There, you can pre-segment your documents into sections, and tell Vectara what the context is around the documents. Note that we do consider that anyone that _needs_ to use this API as a bit of a failure on our side to providing robust-enough APIs! If you find that you need to use this API because you're getting poor quality without it, please do [let us know](https://discuss.vectara.com) about your use case so we can consider adding structured APIs around it. * [Custom dimensions](#custom-dimensions) * [Hybrid search](#hybrid-search) * [Alternative similarity measures](#alternative-similarity-measures) * [Interpreting scores](#interpreting-scores) * [Low-level indexing controls](#low-level-indexing-controls) --- # Enable Pagination in Search Results | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/semantic-search/enable-pagination) ** (2.0). Version: 1.0 On this page Pagination provides you with customization options for individual preferences or application requirements. Upon query, Vectara returns the first 10 most relevant search results by default. However, there are times when this is not enough and you want to offer your users the ability to paginate through results. To enable pagination, use the `start` and `num_results` parameters under the `query`. Example: Set Results to 20 Per Page[​](#example-set-results-to-20-per-page "Direct link to Example: Set Results to 20 Per Page") --------------------------------------------------------------------------------------------------------------------------------- To page through where each page has 20 results, you set `start` to `0` and `num_results` to `20`. { "query": [ { "query": "What is offsides?", "queryContext": "", "start": 0, "numResults": 20, "contextConfig": { "charsBefore": 0, "charsAfter": 0, "sentencesBefore": 2, "sentencesAfter": 2, "startTag": "%START_SNIPPET%", "endTag": "%END_SNIPPET%" }, "corpusKey": [ // ... ], "summary": [ // ... ] } ]} Example: Set Results to Begin on Page 2[​](#example-set-results-to-begin-on-page-2 "Direct link to Example: Set Results to Begin on Page 2") --------------------------------------------------------------------------------------------------------------------------------------------- Then if your users want to paginate to page 2, you would send `start` as `20` and `num_results` to `20`, and for each page following, add another 20 to the `start`. { "query": [ { "query": "What is offsides?", "queryContext": "", "start": 20, "numResults": 20, "contextConfig": { "charsBefore": 0, "charsAfter": 0, "sentencesBefore": 2, "sentencesAfter": 2, "startTag": "%START_SNIPPET%", "endTag": "%END_SNIPPET%" }, "corpusKey": [ // ... ], "summary": [ // ... ] } ]} * [Example: Set Results to 20 Per Page](#example-set-results-to-20-per-page) * [Example: Set Results to Begin on Page 2](#example-set-results-to-begin-on-page-2) --- # Recommendation System | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/recommendation-systems/recommender-overview) ** (2.0). Version: 1.0 On this page Vectara can be used as a semantic recommendation system out of the box in order to provide your users with semantically similar documents/products. Semantic recommendation system considerations[​](#semantic-recommendation-system-considerations "Direct link to Semantic recommendation system considerations") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- Before you begin using Vectara for a semantic recommendation system, it's useful to think through what types of recommendation flows you want to enable. For example: * Do you want to recommend based on the entire document content or just 1 section/field like the document title? * Do you want to recommend semantically similar content regardless of the source language or do you want to only match a particular language? * Are you looking for exact duplicates or semantic similarity? Exact duplicate matching[​](#exact-duplicate-matching "Direct link to Exact duplicate matching") ------------------------------------------------------------------------------------------------- Exact duplicate matching can be useful when you want to ensure no duplicate content exists in your corpora or to find exact matches of "known bad" documents like those that might violate compliance rules in your organization. In general, we recommend that you use [filter expressions](/docs/1.0/api-reference/search-apis/sql/func-opr) for this. Specifically: 1. When you index your content, hash your content using something like SHA-256 and add that as custom metadata on the document 2. To find similar content to a particular document, hash the entire document using the same hashing algorithm and then perform a filtered query to find exact hash matches Similar document matching and near-duplicates[​](#similar-document-matching-and-near-duplicates "Direct link to Similar document matching and near-duplicates") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- Sometimes, you want to recommend alternative products or web pages to a user that are similar to the one they're looking at or a recently purchased product. These use cases can be dealt with by using Vectara in a document-to-document search/recommendation platform. In order to do this, the most important change is that you'll need to use `RESPONSE` similarity measure (available to [our Scale plan users](https://vectara.com/pricing/) ). It's easier to explain how this is different by first explaining how the `DEFAULT` similarity works. By default, Vectara is set up in a β€œquestion answering” mode. That is, Vectara's large language models are designed in principal to _answer an end-user's question_ instead of finding similar documents when in their default mode. You can think of this as "the best answer to the question `Who is the King of England?` is not a document which has the text `Who is the King of England?` even though that has the highest overlap of keywords possible. Instead, Vectara is set up by default to be able to find the best _answers_ to queries. Document recommendation systems are not trying to answer questions though: they're trying to find the most similar documents. So for that use case, what you need to do is change the mode of the search to document similarity instead of question answering. You do that via the semantics key which is inside of the corpusKey block in the query. If a user is looking at a document that has the text: All about meMy name is Shane and I'm ... and you wanted to find other documents that are similar to this, you can pass this document text to Vectara and set the `semantics` to `RESPONSE`. For example: https://api.vectara.io/v1/query { "query": [ { "query": "All about me\n\nMy name is Shane and I'm ...", "start": 0, "numResults": 10, "corpusKey": [ { "customerId": 12345678, "corpusId": 1, "semantics": "RESPONSE" } ] } ]} This will find documents that are most semantically similar to that document. Further recommendation refinement[​](#further-recommendation-refinement "Direct link to Further recommendation refinement") ---------------------------------------------------------------------------------------------------------------------------- At times, it can be useful to further refine the recommendations. For example: * Only suggest based on similar document titles * Only suggest results that share the same language * Only suggest results that were created by a particular user In these cases, it can be useful to use Vectara's [filter expressions](/docs/1.0/learn/metadata-search-filtering/filter-overview) . There are [out of the box filters](/docs/1.0/learn/metadata-search-filtering/ootb-metadata-filters) for title and language and you can make use of additional metadata you add, such as the author or publication date. * [Semantic recommendation system considerations](#semantic-recommendation-system-considerations) * [Exact duplicate matching](#exact-duplicate-matching) * [Similar document matching and near-duplicates](#similar-document-matching-and-near-duplicates) * [Further recommendation refinement](#further-recommendation-refinement) --- # Add Custom Dimensions to Enhance Scoring | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/learn/semantic-search/add-custom-dimensions) ** (2.0). Version: 1.0 On this page Custom dimensions enable [our Scale users](https://vectara.com/pricing/) to have a fixed set of additional "dimensions" that contain user-defined numerical values and are stored in addition to the dimensions that Vectara automatically extracts and stores from the text. At query time, users can use these custom dimensions to increase or decrease the resulting score dynamically, query by query. For example, let's say we want to add a custom dimension to boost posts from a forum based on how many "upvotes" it has received. We can create the corpus with a "votes" custom dimension as follows: curl -X POST \ -H "Authorization: Bearer ${JWT_TOKEN}" \ -H "customer-id: ${CUSTOMER_ID}" \ https://api.vectara.io:443/v1/create-corpus \ -d @- <= 1` The Corpus ID that contains the document. **documentId** stringrequired The Document ID to be deleted. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** object {} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # ComputeAccountSize | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 ComputeAccountSize ================== POST /v1/compute-account-size ------------------------ 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) . Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** Please note that this is an expensive operation, and the requests can be throttled by the platform. object Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **size** object\[\] One TextSize represents one cluster. The account size is a sum of all the sizes. Generally, this will only have one value. * Array \[\ \ \ **numChars** uint64\ \ Count of actual characters in the text that will be searched.\ \ **numMetadataChars** uint64\ \ Count of metadata characters such as URL, author, date of creation etc.\ \ * \] **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string { "size": [ { "numChars": "string", "numMetadataChars": "string" } ], "status": { "code": "OK", "statusDetail": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # ComputeCorpusSize | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 ComputeCorpusSize ================= POST /v1/compute-corpus-size ----------------------- Computes the amount of quota consumed by a corpus. This capability is useful for administrators to track and monitor the amount of usage for specific corpora. 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. Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **corpusId** int64 The corpus for which to compute the size. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **size** object **epochSecs** int64 The time at which the size was calculated. **size** uint64 The size of the corpus. **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string { "size": { "epochSecs": "string", "size": "string" }, "status": { "code": "OK", "statusDetail": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # DeleteApiKey | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/rest-api/delete-api-key) ** (2.0). Version: 1.0 DeleteApiKey ============ POST /v1/delete-api-key ------------------ Deletes API keys to help you manage the security and lifecycle of API keys in your application. 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) . Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **keyIds** string\[\] Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **status** object\[\] Status of the DeleteApiKeyRequest. * Array \[\ \ \ **code** vectaraStatusCode\ \ **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\]\ \ **Default value:** `OK`\ \ **statusDetail** string\ \ * \] { "status": [ { "code": "OK", "statusDetail": "string" } ]} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # DocumentService | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 Document operations, listing documents in a corpus [πŸ“„οΈ ListDocuments\ -----------------\ \ 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.](/docs/1.0/rest-api/list-documents) --- # CreateApiKey | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/rest-api/create-api-key) ** (2.0). Version: 1.0 CreateApiKey ============ POST /v1/create-api-key ------------------ 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) . Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** This request can be used to create one or more ApiKeys. Every ApiKey is bound to one or more corpora. **apiKeyData** object\[\] List of ApiKey data to create. * Array \[\ \ \ **description** string\ \ Description of the ApiKey.\ \ **apiKeyType** adminApiKeyType\ \ **Possible values:** \[`API_KEY_TYPE__UNDEFINED`, `API_KEY_TYPE__SERVING`, `API_KEY_TYPE__SERVING_INDEXING`, `API_KEY_TYPE__PERSONAL`\]\ \ **Default value:** `API_KEY_TYPE__UNDEFINED`\ \ 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.\ \ **corpusId** int64\[\]\ \ List of corpus ids to bind the ApiKey to.\ \ * \] Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **response** object\[\] List of ApiKeyOrStatus corresponding to the list of ApiKey data in request. * Array \[\ \ \ **keyId** string\ \ A valid ApiKey.\ \ **status** object\ \ **code** vectaraStatusCode\ \ **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\]\ \ **Default value:** `OK`\ \ **statusDetail** string\ \ * \] { "response": [ { "keyId": "string", "status": { "code": "OK", "statusDetail": "string" } } ]} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # CoreIndex | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 CoreIndex ========= POST /v1/core/index -------------- 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. Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** Request to index a document. **customerId** int64 The Customer ID to issue the request for. **corpusId** int64 The Corpus ID to index the document into. **document** object A document to index. **documentId** string A document ID to assign to this document. **metadataJson** string Metadata about the document. This should be a json string. It can be retrieved at query time. **parts** object\[\] All parts of this document. * Array \[\ \ \ **text** string\ \ A part of the document. e.g., a sentence.\ \ **context** string\ \ Context of the part.\ \ **metadataJson** string\ \ 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** object\[\]\ \ * Array \[\ \ \ **name** string\ \ The name of the dimension.\ \ **value** double\ \ The value of the dimension.\ \ * \]\ \ \ * \] **defaultPartContext** string 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** object\[\] A list of custom dimension values that are included in the generated representation of all parts. * Array \[\ \ \ **name** string\ \ The name of the dimension.\ \ **value** double\ \ The value of the dimension.\ \ * \] Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string **quotaConsumed** object **numChars** int64 The number of chars from the document that consumed the storage quota. **numMetadataChars** int64 The number of chars in the metadata of the document that consumed the storage quota. { "status": { "code": "OK", "statusDetail": "string" }, "quotaConsumed": { "numChars": "string", "numMetadataChars": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # CreateCorpus | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/rest-api/create-corpus) ** (2.0). Version: 1.0 CreateCorpus ============ POST /v1/create-corpus ----------------- 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. Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **corpus** object **id** int64 The Corpus ID. This value is ignored during Corpus creation. **name** string The name of the corpus. **description** string A description for the corpus. **dtProvision** int64 The time at which the corpus was provisioned. This value is ignored during Corpus creation. **enabled** boolean Whether the corpus is enabled for use or not. This value is ignored during Corpus creation. **swapQenc** boolean **swapIenc** boolean 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** boolean When a corpus is "textless", Vectara does not store the original text. Instead, Vectara converts the text to vectors and only retains metadata. **encrypted** boolean Encryption is on by default and cannot be turned off. **encoderId** uint64 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** int64 An optional maximum size of the metadata that each document can contain. **customDimensions** object\[\] * Array \[\ \ \ **name** string\ \ The name of the custom dimension. The maximum length of the name is 8 characters.\ \ **description** string\ \ A description for the custom dimension.\ \ **servingDefault** double\ \ The default weight to give this dimension when running queries. A value of 0.0, for example, gives it no weight at all.\ \ **indexingDefault** double\ \ The default value to give to documents for this custom dimension.\ \ * \] **filterAttributes** object\[\] * Array \[\ \ \ **name** string\ \ Name of the field, as seen in metadata.\ \ **description** string\ \ An optional description.\ \ **indexed** boolean\ \ Whether the field is indexed for maximum query speed.\ \ **type** adminFilterAttributeType\ \ **Possible values:** \[`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 value:** `FILTER_ATTRIBUTE_TYPE__UNDEFINED`\ \ **level** \- FILTER\_ATTRIBUTE\_LEVEL\_\_DOCUMENT: Document-level attribute - FILTER\_ATTRIBUTE\_LEVEL\_\_DOCUMENT\_PART: Part-level attribute\ \ **Possible values:** \[`FILTER_ATTRIBUTE_LEVEL__UNDEFINED`, `FILTER_ATTRIBUTE_LEVEL__DOCUMENT`, `FILTER_ATTRIBUTE_LEVEL__DOCUMENT_PART`\]\ \ **Default value:** `FILTER_ATTRIBUTE_LEVEL__UNDEFINED`\ \ * \] Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **corpusId** int64 The Corpus ID that was created. **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string { "corpusId": 0, "status": { "code": "OK", "statusDetail": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # DeleteTurns | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 DeleteTurns =========== POST /v1/delete-turns ---------------- Deletes specific turns from a conversation within the chat history corpus. This enables developers to remove inaccurate or inappropriate responses from the conversation history. 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) . Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **conversationId** string The ID of the conversations from which to delete turns. **turnId** string The ID of the turn to start deletion from. All turns in this conversation starting from this turn (inclusive) will be deleted. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string { "status": { "code": "OK", "statusDetail": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # FileUpload | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 FileUpload ========== POST /v1/upload ---------- 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. Request[​](#request "Direct link to Request") ---------------------------------------------- ### Query Parameters **c** integerrequired Customer ID **o** integerrequired Corpus ID **Example:** 1 **d** boolean If true, the server returns the extracted document that was indexed * multipart/form-data ### Body **doc\_metadata** string A JSON string of any additional metadata you want attached to the file. **file** binaryrequired The file to be indexed into Vectara. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * 400 * 401 * 403 * 409 * 507 A successful response * application/json * Schema * Example (from schema) **Schema** **response** object **status** object **quotaConsumed** object **numChars** string The number of characters Vectara indexed from the file uploaded. **numMetadataChars** string The number of metadata characters Vectara indexed from the file uploaded. { "response": { "status": {}, "quotaConsumed": { "numChars": "string", "numMetadataChars": "string" } }} An invalid request was sent. e.g. one or more parameters was missing, or the corpus does not exist. * application/json * Schema * Example (from schema) **Schema** **httpCode** integer Returned HTTP code { "httpCode": 0} The request was not authenticated The caller is not authorized to add documents to the corpus 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. 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. Loading... --- # DeleteCorpus | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/rest-api/delete-corpus) ** (2.0). Version: 1.0 DeleteCorpus ============ POST /v1/delete-corpus ----------------- 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. Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **customerId** int64required The Customer ID that contains the corpus to be deleted. **corpusId** int64required **Possible values:** `>= 1` The Corpus ID to be deleted. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string { "status": { "code": "OK", "statusDetail": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # DeleteConversations | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 DeleteConversations =================== POST /v1/delete-conversations ------------------------ 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. 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) . Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **conversationId** string\[\] The IDs of the conversations to delete. Limit: 1000 conversations. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string { "status": { "code": "OK", "statusDetail": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # DisableTurns | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 DisableTurns ============ POST /v1/disable-turns ----------------- Disables specific turns from a conversation within the chat history corpus. This is useful for excluding specific turns from a conversation. 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) . Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **conversationId** string The ID of the conversations from which to disable turns. **turnId** string The ID of the turn to start disabling from. All turns in this conversation starting from this turn will be disabled. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string { "status": { "code": "OK", "statusDetail": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # EnableApiKey | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 EnableApiKey ============ POST /v1/enable-api-key ------------------ Enables or disables a specific API key. 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) . Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **keyEnablement** object\[\] List of ApiKey ids to enable or disable. * Array \[\ \ \ **keyId** string\ \ ApiKey id to enable or disable.\ \ **enable** Enable or disable using this variable\ \ * \] Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **status** object\[\] List of Status such as OK, FAILED corresponding to the EnableApiKeyRequest. * Array \[\ \ \ **code** vectaraStatusCode\ \ **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\]\ \ **Default value:** `OK`\ \ **statusDetail** string\ \ * \] { "status": [ { "code": "OK", "statusDetail": "string" } ]} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # GetUsageMetrics | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 GetUsageMetrics =============== POST /v1/get-usage-metrics --------------------- 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. Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **corpusId** int64 The corpus for which the metric is requested. **window** object **startEpochSecs** int64 **endEpochSecs** int64 **type** The type of metric to get **Possible values:** \[`METRICTYPE__NONE`, `METRICTYPE__INDEXING`, `METRICTYPE__SERVING`\] **Default value:** `METRICTYPE__NONE` **aggregationIntervalSecs** int64 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. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **values** object\[\] List of IntervalValue containing values for either Indexing or Serving. These are aggregated by the interval specified in the request. * Array \[\ \ \ **indexingValue** object\ \ **docCount** uint64\ \ **docPartCount** uint64\ \ **docPartBytes** uint64\ \ 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** int64\ \ **servingValue** object\ \ **rowsRead** uint64\ \ **queryCount** uint64\ \ **startEpochSecs** int64\ \ * \] **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string { "values": [ { "indexingValue": { "docCount": "string", "docPartCount": "string", "docPartBytes": "string", "startEpochSecs": "string" }, "servingValue": { "rowsRead": "string", "queryCount": "string", "startEpochSecs": "string" } } ], "status": { "code": "OK", "statusDetail": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # Vectara API | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/rest-api) ** (2.0). Version: 1.0 [πŸ“„οΈ Introduction\ ----------------\ \ Vectara provides an end-to-end platform for creating GenAI products using](/docs/1.0/rest-api/vectara-rest-api) [πŸ—ƒοΈ AdminService\ ----------------\ \ 17 items](/docs/1.0/rest-api/admin-service) [πŸ—ƒοΈ IndexService\ ----------------\ \ 4 items](/docs/1.0/rest-api/index-service) [πŸ—ƒοΈ QueryService\ ----------------\ \ 2 items](/docs/1.0/rest-api/query-service) [πŸ—ƒοΈ DocumentService\ -------------------\ \ 1 items](/docs/1.0/rest-api/document-service) [πŸ—ƒοΈ ChatService\ ---------------\ \ 5 items](/docs/1.0/rest-api/chat-service) --- # IndexService | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 Indexing operations, such as creating and deleting documents [πŸ“„οΈ Delete\ ----------\ \ Delete documents from a corpus.](/docs/1.0/rest-api/delete) [πŸ“„οΈ Index\ ---------\ \ 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.](/docs/1.0/rest-api/index) [πŸ“„οΈ CoreIndex\ -------------\ \ This API is intended to be used by experts. It gives you fine-grained control over chunking](/docs/1.0/rest-api/core-index) [πŸ“„οΈ FileUpload\ --------------\ \ The File Upload API can be used to index binary files like PDFs, Word Documents, and similar.](/docs/1.0/rest-api/file-upload) --- # QueryService | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 Query operations, such as performing a search and retrieval augmented generation [πŸ“„οΈ Query\ ---------\ \ Search for relevant results, highlight relevant snippets, and do](/docs/1.0/rest-api/query) [πŸ“„οΈ StreamQuery\ ---------------\ \ Stream responses as you search for relevant results, highlight relevant snippets, and do](/docs/1.0/rest-api/stream-query) --- # ReadConversations | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 ReadConversations ================= POST /v1/read-conversations ---------------------- 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. 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) . Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **conversationId** string\[\] The IDs of the conversations to read. Limit: 10 conversations. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **Conversation** object\[\] * Array \[\ \ \ **id** string\ \ The ID of the conversation. This is unique within the chat history corpus.\ \ **turn** object\[\]\ \ The turns comprising this conversation.\ \ * Array \[\ \ \ **id** string\ \ 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** string\ \ The ID of the conversation this turn belongs to. This is the same as the ID of the first turn in the conversation.\ \ **query** string\ \ The query text.\ \ **answer** string\ \ The answer text.\ \ **enabled** boolean\ \ 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** int64\ \ The time at which this turn was created.\ \ * \]\ \ \ * \] **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string { "Conversation": [ { "id": "string", "turn": [ { "id": "string", "conversationId": "string", "query": "string", "answer": "string", "enabled": true, "epochSecs": "string" } ] } ], "status": { "code": "OK", "statusDetail": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # ListConversations | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 ListConversations ================= POST /v1/list-conversations ---------------------- List all the conversations in a customer account. 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) . Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **numResults** int64 Maximum number of conversations to return per page. **pageKey** byte 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. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **conversation** object\[\] The first turn in each conversation. This doesn't comprise all turns in each conversation; only the first turn of each conversation is returned. * Array \[\ \ \ **id** string\ \ 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** string\ \ The ID of the conversation this turn belongs to. This is the same as the ID of the first turn in the conversation.\ \ **query** string\ \ The query text.\ \ **answer** string\ \ The answer text.\ \ **enabled** boolean\ \ 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** int64\ \ The time at which this turn was created.\ \ * \] **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string **pageKey** byte 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. { "conversation": [ { "id": "string", "conversationId": "string", "query": "string", "answer": "string", "enabled": true, "epochSecs": "string" } ], "status": { "code": "OK", "statusDetail": "string" }, "pageKey": "string"} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # ListApiKeys | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/rest-api/list-api-keys) ** (2.0). Version: 1.0 ListApiKeys =========== POST /v1/list-api-keys ----------------- 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. Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **numResults** integer **apiKeyType** string\[\] **readCorporaInfo** boolean Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **keyData** object\[\] List of ApiKey and associated corpora. * Array \[\ \ \ **apiKey** object\ \ Represents an ApiKey. An ApiKey provides anonymous access to common tasks such as index data, query data, etc.\ \ **id** string\ \ **description** string\ \ Description of the ApiKey.\ \ **keyType** adminApiKeyType\ \ **Possible values:** \[`API_KEY_TYPE__UNDEFINED`, `API_KEY_TYPE__SERVING`, `API_KEY_TYPE__SERVING_INDEXING`, `API_KEY_TYPE__PERSONAL`\]\ \ **Default value:** `API_KEY_TYPE__UNDEFINED`\ \ 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.\ \ **enabled** boolean\ \ Whether the ApiKey is enabled.\ \ **tsStart** int64\ \ Seconds sinch Epoch when the ApiKey becomes active.\ \ **tsEnd** int64\ \ Seconds sinch Epoch when the ApiKey becomes inactive.\ \ **status** adminApiKeyStatus\ \ **Possible values:** \[`UNKNOWN`, `ENABLED`, `DISABLED`, `DELETED`\]\ \ **Default value:** `UNKNOWN`\ \ Status of ApiKey.\ \ **corpus** object\[\]\ \ List of corpora associated with the ApiKey.\ \ * Array \[\ \ \ **id** int64\ \ Corpus id.\ \ **name** string\ \ Corpus name.\ \ * \]\ \ \ * \] **pageKey** byte A key that is passed into a subsequent result in order to retrieve the next page of results. **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string { "keyData": [ { "apiKey": { "id": "string", "description": "string", "keyType": "API_KEY_TYPE__UNDEFINED", "enabled": true, "tsStart": "string", "tsEnd": "string", "status": "UNKNOWN" }, "corpus": [ { "id": 0, "name": "string" } ] } ], "pageKey": "string", "status": { "code": "OK", "statusDetail": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # ListCorpora | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/rest-api/list-corpora) ** (2.0). Version: 1.0 ListCorpora =========== POST /v1/list-corpora ---------------- 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. Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **filter** string A regex over the names and descriptions to match corpora against. **numResults** int64required **Possible values:** `>= 1` The maximum results to return. **pageKey** byte A key that is passed in to retrieve a specific page of results. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **corpus** object\[\] * Array \[\ \ \ **id** int64\ \ The Corpus ID. This value is ignored during Corpus creation.\ \ **name** string\ \ The name of the corpus.\ \ **description** string\ \ A description for the corpus.\ \ **dtProvision** int64\ \ The time at which the corpus was provisioned. This value is ignored during Corpus creation.\ \ **enabled** boolean\ \ Whether the corpus is enabled for use or not. This value is ignored during Corpus creation.\ \ **swapQenc** boolean\ \ **swapIenc** boolean\ \ 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** boolean\ \ When a corpus is "textless", Vectara does not store the original text. Instead, Vectara converts the text to vectors and only retains metadata.\ \ **encrypted** boolean\ \ Encryption is on by default and cannot be turned off.\ \ **encoderId** uint64\ \ 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** int64\ \ An optional maximum size of the metadata that each document can contain.\ \ **customDimensions** object\[\]\ \ * Array \[\ \ \ **name** string\ \ The name of the custom dimension. The maximum length of the name is 8 characters.\ \ **description** string\ \ A description for the custom dimension.\ \ **servingDefault** double\ \ The default weight to give this dimension when running queries. A value of 0.0, for example, gives it no weight at all.\ \ **indexingDefault** double\ \ The default value to give to documents for this custom dimension.\ \ * \]\ \ \ **filterAttributes** object\[\]\ \ * Array \[\ \ \ **name** string\ \ Name of the field, as seen in metadata.\ \ **description** string\ \ An optional description.\ \ **indexed** boolean\ \ Whether the field is indexed for maximum query speed.\ \ **type** adminFilterAttributeType\ \ **Possible values:** \[`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 value:** `FILTER_ATTRIBUTE_TYPE__UNDEFINED`\ \ **level** \- FILTER\_ATTRIBUTE\_LEVEL\_\_DOCUMENT: Document-level attribute - FILTER\_ATTRIBUTE\_LEVEL\_\_DOCUMENT\_PART: Part-level attribute\ \ **Possible values:** \[`FILTER_ATTRIBUTE_LEVEL__UNDEFINED`, `FILTER_ATTRIBUTE_LEVEL__DOCUMENT`, `FILTER_ATTRIBUTE_LEVEL__DOCUMENT_PART`\]\ \ **Default value:** `FILTER_ATTRIBUTE_LEVEL__UNDEFINED`\ \ * \]\ \ \ * \] **pageKey** byte A key that is passed into a subsequent result in order to retrieve the next page of results. **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string { "corpus": [ { "id": 0, "name": "string", "description": "string", "dtProvision": "string", "enabled": true, "swapQenc": true, "swapIenc": true, "textless": true, "encrypted": true, "encoderId": "string", "metadataMaxBytes": 0, "customDimensions": [ { "name": "string", "description": "string", "servingDefault": 0, "indexingDefault": 0 } ], "filterAttributes": [ { "name": "string", "description": "string", "indexed": true, "type": "FILTER_ATTRIBUTE_TYPE__UNDEFINED", "level": "FILTER_ATTRIBUTE_LEVEL__UNDEFINED" } ] } ], "pageKey": "string", "status": { "code": "OK", "statusDetail": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # ListDocuments | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 ListDocuments ============= POST /v1/list-documents ------------------ 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) . Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** Request to list documents in a corpus. **corpusId** int64 The Corpus ID. **numResults** int64 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** byte 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** string 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. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **document** object\[\] The list of documents. * Array \[\ \ \ **id** string\ \ The document ID that was used when indexing the document.\ \ **metadata** object\[\]\ \ Document metadata.\ \ * Array \[\ \ \ **name** string\ \ Name of the document metadata attribute.\ \ **value** string\ \ Value of the document metadata attribute.\ \ * \]\ \ \ * \] **nextPageKey** byte 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). { "document": [ { "id": "string", "metadata": [ { "name": "string", "value": "string" } ] } ], "nextPageKey": "string"} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # ReplaceCorpusFilterAttrs | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 ReplaceCorpusFilterAttrs ======================== POST /v1/replace-corpus-filter-attrs ------------------------------- 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. Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **corpusId** int64 The corpus for which to update filters. **filterAttributes** object\[\] The filters to set. The existing filters are replaced with this list of filters. * Array \[\ \ \ **name** string\ \ Name of the field, as seen in metadata.\ \ **description** string\ \ An optional description.\ \ **indexed** boolean\ \ Whether the field is indexed for maximum query speed.\ \ **type** adminFilterAttributeType\ \ **Possible values:** \[`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 value:** `FILTER_ATTRIBUTE_TYPE__UNDEFINED`\ \ **level** \- FILTER\_ATTRIBUTE\_LEVEL\_\_DOCUMENT: Document-level attribute - FILTER\_ATTRIBUTE\_LEVEL\_\_DOCUMENT\_PART: Part-level attribute\ \ **Possible values:** \[`FILTER_ATTRIBUTE_LEVEL__UNDEFINED`, `FILTER_ATTRIBUTE_LEVEL__DOCUMENT`, `FILTER_ATTRIBUTE_LEVEL__DOCUMENT_PART`\]\ \ **Default value:** `FILTER_ATTRIBUTE_LEVEL__UNDEFINED`\ \ * \] Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string **jobId** string 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. { "status": { "code": "OK", "statusDetail": "string" }, "jobId": "string"} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # Vectara REST API | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 Version: 1.0.0 Export * [OpenAPI Spec](https://docs.vectara.com/vectara-oas.yaml) Vectara REST API ================ ![Vectara](https://docs.vectara.com/img/vectara_wordmark.png)![Vectara](https://docs.vectara.com/img/vectara_wordmark_light.png) Vectara provides an end-to-end platform for creating GenAI products using a simple to use API. You can [sign up for an account](https://console.vectara.com/signup) and then view several [API Recipes](https://docs.vectara.com/docs/api-recipes) with example queries and parameter values. The Vectara API Playground lets you experiment with REST endpoints from your browser. Select an endpoint to view its definition, including the required or optional headers, body, responses, and sample commands. On the right side of each endpoint page, you manually enter your API Key or OAuth Bearer Token, `customer_id`, and then any required body parameters like the `corpusID` before sending the API request. note Vectara has three kinds of API keys: the Personal API Key, Index API Keys, and Query API Keys. The Personal API Key enables administrative tasks including creating, deleting, and listing corpora, and managing Index and Query API keys for accessible corpora, reading usage data, updating corpora filters, executing queries, and indexing. Query API Keys are used for read-only querying operations, while Index API Keys provide read and write access. The OAuth operations authenticate with a Bearer Token via the OAuth 2.0 client credentials grant. Review the [**OAuth 2.0 section**](https://docs.vectara.com/docs/learn/authentication/oauth-2) about how to generate the token. Authentication[​](#authentication "Direct link to Authentication") ------------------------------------------------------------------- * OAuth 2.0: oAuth * API Key: ApiKeyAuth OAuth2 access to Vectara | | | | --- | --- | | Security Scheme Type: | oauth2 | | OAuth Flow (clientCredentials): | Token URL: https://vectara-prod-YOUR\_VECTARA\_CUSTOMER\_ID.auth.us-west-2.amazoncognito.com/oauth2/token

Scopes: | | | | | --- | --- | | Security Scheme Type: | apiKey | | Header parameter name: | x-api-key | ### Contact Vectara Support: [support@vectara.com](mailto:support@vectara.com) URL: [http://support.vectara.com/](http://support.vectara.com/) ### Terms of Service [https://vectara.com/legal/online-customer-agreement/](https://vectara.com/legal/online-customer-agreement/) --- # ResetCorpus | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/rest-api/reset-corpus) ** (2.0). Version: 1.0 ResetCorpus =========== POST /v1/reset-corpus ---------------- 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) . Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **customerId** int64required The Customer ID that contains the corpus to be reset. **corpusId** int64required **Possible values:** `>= 1` The Corpus ID to be reset. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string { "status": { "code": "OK", "statusDetail": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # UpdateCorpusEnablement | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 UpdateCorpusEnablement ====================== POST /v1/update-corpus-enablement ---------------------------- 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. Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **corpusId** int64 The corpus to enable or disable. **enable** boolean If true, enable the corpus. Otherwise, disable it. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string { "status": { "code": "OK", "statusDetail": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # ListJobs | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/rest-api/list-jobs) ** (2.0). Version: 1.0 ListJobs ======== POST /v1/list-jobs ------------- 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. Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **jobId** string Optional filters. If specified, the filters are logically ANDed. \[Optional\] If specified, return the job for this id. **corpusId** int64\[\] \[Optional\] If specified, return jobs for these corpora only. **epochSecs** int64 \[Optional\] Get jobs that were created since this epoch timestamp. Max allowed value is 180 days ago. Default is 180 days. **state** adminJobState\[\] **Possible values:** \[`JOB_STATE__UNKNOWN`, `JOB_STATE__QUEUED`, `JOB_STATE__STARTED`, `JOB_STATE__COMPLETED`, `JOB_STATE__FAILED`, `JOB_STATE__TRANSIENT_FAILURE_RETRY_IMMINENT`, `JOB_STATE__ABORTED`\] \[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** int64 Maximum results to return. Max allowed value is 100. **pageKey** byte 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. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **status** object\[\] * Array \[\ \ \ **code** vectaraStatusCode\ \ **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\]\ \ **Default value:** `OK`\ \ **statusDetail** string\ \ * \] **job** object\[\] * Array \[\ \ \ **id** string\ \ **type** adminJobType\ \ **Possible values:** \[`JOB__UNKNOWN`, `JOB__CORPUS_REBUILD_VECTOR_INDEX`, `JOB__CORPUS_REPLACE_FILTER_ATTRS`\]\ \ **Default value:** `JOB__UNKNOWN`\ \ Type of jobs.\ \ **corpusId** int64\[\]\ \ Set if the job belongs to a corpus.\ \ **state** adminJobState\ \ **Possible values:** \[`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 value:** `JOB_STATE__UNKNOWN`\ \ The state of a job.\ \ **tsCreate** int64\ \ Epoch (secs) when the job was created.\ \ **tsStart** int64\ \ Epoch (secs) when the job was started. Not set if the job hasn't started yet.\ \ **tsComplete** int64\ \ Epoch (secs) when the job completed. Not set if the job hasn't completed yet.\ \ **userHandle** string\ \ Handle of the user that created this job.\ \ * \] **pageKey** byte A key that is passed into a subsequent result in order to retrieve the next page of results. { "status": [ { "code": "OK", "statusDetail": "string" } ], "job": [ { "id": "string", "type": "JOB__UNKNOWN", "corpusId": [ 0 ], "state": "JOB_STATE__UNKNOWN", "tsCreate": "string", "tsStart": "string", "tsComplete": "string", "userHandle": "string" } ], "pageKey": "string"} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # ListUsers | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/rest-api/list-users) ** (2.0). Version: 1.0 ListUsers ========= POST /v1/list-users -------------- List Users Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **listUsersType** \- LIST\_USERS\_TYPE\_\_CUSTOMER: Only List users with customer account-level authorizations. - LIST\_USERS\_TYPE\_\_ALL: List All the users **Possible values:** \[`LIST_USERS_TYPE__NONE`, `LIST_USERS_TYPE__CUSTOMER`, `LIST_USERS_TYPE__ALL`\] **Default value:** `LIST_USERS_TYPE__NONE` **pageKey** byte 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** int64 Number of results to return. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **user** object\[\] * Array \[\ \ \ **id** int64\ \ 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** string\ \ Name of the user. This is required for creating a new user.\ \ **type** adminUserType\ \ **Possible values:** \[`USER_TYPE__NONE`, `USER_TYPE__USER`, `USER_TYPE__FEDERATED_USER`, `USER_TYPE__APP_CLIENT`\]\ \ **Default value:** `USER_TYPE__NONE`\ \ * 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.\ \ **comment** Comment about the user\ \ **tsCreate** int64\ \ Seconds since epoch when the user was created.\ \ **idCreate** int64\ \ ID of the user who created this user.\ \ **email** string\ \ Email address associated with the user. This is required for creating a new user.\ \ **userStatus** \- USER\_STATUS\_\_ACTIVE: User is active - USER\_STATUS\_\_DISABLED: User is disabled\ \ **Possible values:** \[`USER_STATUS__NONE`, `USER_STATUS__ACTIVE`, `USER_STATUS__DISABLED`\]\ \ **Default value:** `USER_STATUS__NONE`\ \ **role** adminCustomerRole\[\]\ \ **Possible values:** \[`CustomerRole_None`, `CustomerRole_Owner`, `CustomerRole_Admin`, `CustomerRole_Billing_Admin`, `CustomerRole_Corpus_Admin`\]\ \ * \] **pageKey** byte A key that is passed into a subsequent result in order to retrieve the next page of results. **status** object **code** vectaraStatusCode **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\] **Default value:** `OK` **statusDetail** string { "user": [ { "id": 0, "handle": "string", "type": "USER_TYPE__NONE", "comment": "string", "tsCreate": "string", "idCreate": 0, "email": "string", "userStatus": "USER_STATUS__NONE", "role": [ "CustomerRole_None" ] } ], "pageKey": "string", "status": { "code": "OK", "statusDetail": "string" }} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # ManageUser | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 ManageUser ========== POST /v1/manage-user --------------- 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. Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **userAction** object\[\] * Array \[\ \ \ **user** object\ \ Represents a user in an account. A user is a person or an application that has access to the system.\ \ **id** int64\ \ 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** string\ \ Name of the user. This is required for creating a new user.\ \ **type** adminUserType\ \ **Possible values:** \[`USER_TYPE__NONE`, `USER_TYPE__USER`, `USER_TYPE__FEDERATED_USER`, `USER_TYPE__APP_CLIENT`\]\ \ **Default value:** `USER_TYPE__NONE`\ \ * 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.\ \ **comment** Comment about the user\ \ **tsCreate** int64\ \ Seconds since epoch when the user was created.\ \ **idCreate** int64\ \ ID of the user who created this user.\ \ **email** string\ \ Email address associated with the user. This is required for creating a new user.\ \ **userStatus** \- USER\_STATUS\_\_ACTIVE: User is active - USER\_STATUS\_\_DISABLED: User is disabled\ \ **Possible values:** \[`USER_STATUS__NONE`, `USER_STATUS__ACTIVE`, `USER_STATUS__DISABLED`\]\ \ **Default value:** `USER_STATUS__NONE`\ \ **role** adminCustomerRole\[\]\ \ **Possible values:** \[`CustomerRole_None`, `CustomerRole_Owner`, `CustomerRole_Admin`, `CustomerRole_Billing_Admin`, `CustomerRole_Corpus_Admin`\]\ \ **userActionType** \- 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\ \ **Possible values:** \[`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 value:** `USER_ACTION_TYPE__NONE`\ \ * \] Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **response** object\[\] List of users alongwith relative status such as OK, FAILED etc. * Array \[\ \ \ **user** object\ \ Represents a user in an account. A user is a person or an application that has access to the system.\ \ **id** int64\ \ 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** string\ \ Name of the user. This is required for creating a new user.\ \ **type** adminUserType\ \ **Possible values:** \[`USER_TYPE__NONE`, `USER_TYPE__USER`, `USER_TYPE__FEDERATED_USER`, `USER_TYPE__APP_CLIENT`\]\ \ **Default value:** `USER_TYPE__NONE`\ \ * 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.\ \ **comment** Comment about the user\ \ **tsCreate** int64\ \ Seconds since epoch when the user was created.\ \ **idCreate** int64\ \ ID of the user who created this user.\ \ **email** string\ \ Email address associated with the user. This is required for creating a new user.\ \ **userStatus** \- USER\_STATUS\_\_ACTIVE: User is active - USER\_STATUS\_\_DISABLED: User is disabled\ \ **Possible values:** \[`USER_STATUS__NONE`, `USER_STATUS__ACTIVE`, `USER_STATUS__DISABLED`\]\ \ **Default value:** `USER_STATUS__NONE`\ \ **role** adminCustomerRole\[\]\ \ **Possible values:** \[`CustomerRole_None`, `CustomerRole_Owner`, `CustomerRole_Admin`, `CustomerRole_Billing_Admin`, `CustomerRole_Corpus_Admin`\]\ \ **status** object\ \ **code** vectaraStatusCode\ \ **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\]\ \ **Default value:** `OK`\ \ **statusDetail** string\ \ * \] { "response": [ { "user": { "id": 0, "handle": "string", "type": "USER_TYPE__NONE", "comment": "string", "tsCreate": "string", "idCreate": 0, "email": "string", "userStatus": "USER_STATUS__NONE", "role": [ "CustomerRole_None" ] }, "status": { "code": "OK", "statusDetail": "string" } } ]} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... --- # ReadCorpus | Vectara Docs [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for Vectara Docs **1.0**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/docs/) ** (2.0). Version: 1.0 ReadCorpus ========== POST /v1/read-corpus --------------- 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. Request[​](#request "Direct link to Request") ---------------------------------------------- ### Header Parameters **customer-id** integerrequired Enter the Customer ID to use for the request. **timeout** string **Default value:** `30S` (Optional) Enter the timeout value of the request in seconds, such as 10S or 30S. * application/json ### Body **required** **corpusId** int64\[\] Corpora IDs to read. **readBasicInfo** boolean Subset of information to read. Set to true to read basic information about the corpus such as id, name, description, enabled, etc. **readSize** boolean Set to true to read the size of the corpus. **readApiKeys** boolean Set to true to read the API keys associated with the corpus. **readCustomDimensions** boolean Set to true to read the custom dimensions of the corpus. **readFilterAttributes** boolean Set to true to read the filter attributes of the corpus. Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 * default A successful response. * application/json * Schema * Example (from schema) **Schema** **corpora** object\[\] Information about the requested corpora. * Array \[\ \ \ **corpus** object\ \ **id** int64\ \ The Corpus ID. This value is ignored during Corpus creation.\ \ **name** string\ \ The name of the corpus.\ \ **description** string\ \ A description for the corpus.\ \ **dtProvision** int64\ \ The time at which the corpus was provisioned. This value is ignored during Corpus creation.\ \ **enabled** boolean\ \ Whether the corpus is enabled for use or not. This value is ignored during Corpus creation.\ \ **swapQenc** boolean\ \ **swapIenc** boolean\ \ 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** boolean\ \ When a corpus is "textless", Vectara does not store the original text. Instead, Vectara converts the text to vectors and only retains metadata.\ \ **encrypted** boolean\ \ Encryption is on by default and cannot be turned off.\ \ **encoderId** uint64\ \ 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** int64\ \ An optional maximum size of the metadata that each document can contain.\ \ **customDimensions** object\[\]\ \ * Array \[\ \ \ **name** string\ \ The name of the custom dimension. The maximum length of the name is 8 characters.\ \ **description** string\ \ A description for the custom dimension.\ \ **servingDefault** double\ \ The default weight to give this dimension when running queries. A value of 0.0, for example, gives it no weight at all.\ \ **indexingDefault** double\ \ The default value to give to documents for this custom dimension.\ \ * \]\ \ \ **filterAttributes** object\[\]\ \ * Array \[\ \ \ **name** string\ \ Name of the field, as seen in metadata.\ \ **description** string\ \ An optional description.\ \ **indexed** boolean\ \ Whether the field is indexed for maximum query speed.\ \ **type** adminFilterAttributeType\ \ **Possible values:** \[`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 value:** `FILTER_ATTRIBUTE_TYPE__UNDEFINED`\ \ **level** \- FILTER\_ATTRIBUTE\_LEVEL\_\_DOCUMENT: Document-level attribute - FILTER\_ATTRIBUTE\_LEVEL\_\_DOCUMENT\_PART: Part-level attribute\ \ **Possible values:** \[`FILTER_ATTRIBUTE_LEVEL__UNDEFINED`, `FILTER_ATTRIBUTE_LEVEL__DOCUMENT`, `FILTER_ATTRIBUTE_LEVEL__DOCUMENT_PART`\]\ \ **Default value:** `FILTER_ATTRIBUTE_LEVEL__UNDEFINED`\ \ * \]\ \ \ **corpusStatus** object\ \ **code** vectaraStatusCode\ \ **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\]\ \ **Default value:** `OK`\ \ **statusDetail** string\ \ **size** object\ \ **epochSecs** int64\ \ The time at which the size was calculated.\ \ **size** uint64\ \ The size of the corpus.\ \ **sizeStatus** object\ \ **code** vectaraStatusCode\ \ **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\]\ \ **Default value:** `OK`\ \ **statusDetail** string\ \ **apiKey** object\[\]\ \ API keys associated with the corpus. Only populated if read\_api\_keys is true.\ \ * Array \[\ \ \ **id** string\ \ **description** string\ \ Description of the ApiKey.\ \ **keyType** adminApiKeyType\ \ **Possible values:** \[`API_KEY_TYPE__UNDEFINED`, `API_KEY_TYPE__SERVING`, `API_KEY_TYPE__SERVING_INDEXING`, `API_KEY_TYPE__PERSONAL`\]\ \ **Default value:** `API_KEY_TYPE__UNDEFINED`\ \ 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.\ \ **enabled** boolean\ \ Whether the ApiKey is enabled.\ \ **tsStart** int64\ \ Seconds sinch Epoch when the ApiKey becomes active.\ \ **tsEnd** int64\ \ Seconds sinch Epoch when the ApiKey becomes inactive.\ \ **status** adminApiKeyStatus\ \ **Possible values:** \[`UNKNOWN`, `ENABLED`, `DISABLED`, `DELETED`\]\ \ **Default value:** `UNKNOWN`\ \ Status of ApiKey.\ \ * \]\ \ \ **apiKeyStatus** object\ \ **code** vectaraStatusCode\ \ **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\]\ \ **Default value:** `OK`\ \ **statusDetail** string\ \ **customDimension** object\[\]\ \ Custom dimensions of the corpus. Only populated if read\_custom\_dimensions is true.\ \ * Array \[\ \ \ **name** string\ \ The name of the custom dimension. The maximum length of the name is 8 characters.\ \ **description** string\ \ A description for the custom dimension.\ \ **servingDefault** double\ \ The default weight to give this dimension when running queries. A value of 0.0, for example, gives it no weight at all.\ \ **indexingDefault** double\ \ The default value to give to documents for this custom dimension.\ \ * \]\ \ \ **customDimensionStatus** object\ \ **code** vectaraStatusCode\ \ **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\]\ \ **Default value:** `OK`\ \ **statusDetail** string\ \ **filterAttribute** object\[\]\ \ Filter attributes of the corpus. Only populated if read\_filter\_attributes is true.\ \ * Array \[\ \ \ **name** string\ \ Name of the field, as seen in metadata.\ \ **description** string\ \ An optional description.\ \ **indexed** boolean\ \ Whether the field is indexed for maximum query speed.\ \ **type** adminFilterAttributeType\ \ **Possible values:** \[`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 value:** `FILTER_ATTRIBUTE_TYPE__UNDEFINED`\ \ **level** \- FILTER\_ATTRIBUTE\_LEVEL\_\_DOCUMENT: Document-level attribute - FILTER\_ATTRIBUTE\_LEVEL\_\_DOCUMENT\_PART: Part-level attribute\ \ **Possible values:** \[`FILTER_ATTRIBUTE_LEVEL__UNDEFINED`, `FILTER_ATTRIBUTE_LEVEL__DOCUMENT`, `FILTER_ATTRIBUTE_LEVEL__DOCUMENT_PART`\]\ \ **Default value:** `FILTER_ATTRIBUTE_LEVEL__UNDEFINED`\ \ * \]\ \ \ **filterAttributeStatus** object\ \ **code** vectaraStatusCode\ \ **Possible values:** \[`OK`, `FAILURE`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `UNAUTHENTICATED`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `UNSUPPORTED_MEDIA_TYPE`, `TOO_MANY_REQUESTS`, `INTERNAL_SERVER_ERROR`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`, `INSUFFICIENT_STORAGE`, `UNPARSEABLE_RESPONSE`, `DISABLED_CUSTOMER`, `INVALID_CUSTOMER_ID`, `DISABLED_CORPUS`, `INVALID_CORPUS_ID`, `DISABLED_API_KEY`, `EXPIRED_API_KEY`, `INVALID_API_KEY`, `CMK_INACCESSIBLE`, `QRY__DISABLED_CORPUS`, `QRY__DOCUMENT_DB_FAILURE`, `QRY__ENCODER_FAILURE`, `QRY__INTERRUPTED`, `QRY__INVALID_CORPUS`, `QRY__INVALID_START`, `QRY__INVALID_NUM_RESULTS`, `QRY__INVALID_CONTEXT`, `QRY__MISSING_QUERY`, `QRY__MISSING_CORPUS`, `QRY__TIMEOUT`, `QRY__TOO_MANY_CORPORA`, `QRY__TOO_MANY_QUERIES`, `QRY__VECTOR_INDEX_FAILURE`, `QRY__INVALID_DIMENSION`, `QRY__INVALID_CLIENTKEY`, `QRY__DECRYPTION_FAILURE`, `QRY__INVALID_RERANKER`, `QRY__PARTIAL_RERANK`, `QRY__RERANK_FAILURE`, `QRY__TOO_MANY_RESULT_ROWS`, `QRY__PARTIAL_RETRIEVAL`, `QRY__SMRY__INVALID_SUMMARIZER_PROMPT`, `QRY__SMRY__INVALID_SUMMARY_LANG`, `QRY__SMRY__UNSUPPORTED_SUMMARY_LANG`, `QRY__SMRY__PARTIAL_SUMMARY`, `QRY__SMRY__NO_QUERY_RESULTS`, `QRY__SMRY__EVAL_UNSUPPORTED_LANG`, `QRY__SMRY__EVAL_FAILURE`, `QRY__GEN__NO_QUERY_RESULTS`, `QRY__GEN__UNPARSEABLE_MODEL_PARAMS`, `CX_SPECS__INVALID_JSON`, `CX_SPECS__UNREGISTERED_TYPE`, `CX_SPECS__MISSING_SPEC`, `CX_SPECS__MISSING_TYPE`, `CX_SPECS__UNPARSEABLE_SPEC`, `ADM__INVALID_CUSTOMER_ID`, `ADM__INVALID_CORPUS_ID`, `ADM__INVALID_ENCODER_ID`, `ADM__INVALID_ROLE_ID`, `ADM__ROLE_ALREADY_EXISTS`, `ADM__ONLY_ONE_OWNER_SUPPORTED`, `ADM__INVALID_PERMISSION`, `ADM__ROLECREATION_FAILURE`, `ADM__USER_EMAIL_NOT_AVAIALBLE`, `ADM__USERNAME_NOT_AVAILABLE`, `ADM__SIGNUP_MISSING_NAME`, `ADM__SIGNUP_MISSING_ORG`, `ADM__SIGNUP_MISSING_EMAIL`, `ADM__SIGNUP_MISSING_PAYMENT`, `ADM__SIGNUP_MISSING_PLAN`, `ADM__SIGNUP_MISSING_PASSWORD`, `ADM__SIGNUP_INVALID_NAME`, `ADM__SIGNUP_INVALID_ORG`, `ADM__SIGNUP_INVALID_EMAIL`, `ADM__SIGNUP_INVALID_PAYMENT`, `ADM__SIGNUP_INVALID_PLAN`, `ADM__SIGNUP_INVALID_PASSWORD`, `ADM__SIGNUP_INVALID_ACCOUNT_ALIAS`, `ADM__SIGNUP_INVALID_EMAIL_VALIDATION_CODE`, `ADM__SIGNUP_MISSING_COUNTRY_CODE`, `ADM__SIGNUP_ROOT_EMAIL_NOT_AVAILABLE`, `ADM__CUST_MARK_DELETE_FAILED`, `ADM__CUST_FAISS_DEALLOC_FAILED`, `ADM__CUST_ALREADY_ACTIVE`, `ADM__CUST_REACTIVATE_FAILED`, `ADM__CUST_ENABLEMENT_FAILED`, `ADM__CORPUS_LIMIT_REACHED`, `ADM__STRIPE_CARD_DECLINED`, `ADM__STRIPE_PROCESSING_ERROR`, `ADM__EMAIL_VALIDATION_REQUEST_NOT_FOUND`, `ADM__EMAIL_NOT_VALIDATED`, `ADM__CHANGE_PLAN__NO_CURRENT_PLAN`, `ADM__CHANGE_PLAN__REQUIRES_MANUAL_CHANGE`, `ADM__CHANGE_PLAN__INVALID_PLAN_ID`, `ADM__CHANGE_PLAN__NO_PAYMENT_SOURCE`, `ADM__CHANGE_PLAN__INVALID_EFFECTIVE_DATE`, `ADM__CHANGE_PLAN__CONFLICTING_CHANGE`, `SCM__MISCONFIGURED_CONNECTION`, `STATS_DB_READ_FAILURE`, `VDB__TEXT_READ_FAILURE`, `REBUILD__LOW_RECALL`, `REBUILD__INDEX_UPLOAD_FAILURE`, `REBUILD__UPDATE_JOURNAL_FAILURE`, `REBUILD__UPDATE_FAISSPARAMS_FAILURE`, `REBUILD__NO_DATA`, `REBUILD__EVALUATION`, `IDX__TRANSIENT_PARTIAL_DELETION_FAILURE`, `IDX__PERMANENT_PARTIAL_DELETION_FAILURE`, `CALB__INVALID_JSON`, `CALB__INVALID_SPEC`, `CALB__UNREGISTERED_TYPE`, `CALB__MISSING_SPEC`, `CALB__MISSING_TYPE`, `CALB__UNPARSABLE_SPEC`\]\ \ **Default value:** `OK`\ \ **statusDetail** string\ \ * \] { "corpora": [ { "corpus": { "id": 0, "name": "string", "description": "string", "dtProvision": "string", "enabled": true, "swapQenc": true, "swapIenc": true, "textless": true, "encrypted": true, "encoderId": "string", "metadataMaxBytes": 0, "customDimensions": [ { "name": "string", "description": "string", "servingDefault": 0, "indexingDefault": 0 } ], "filterAttributes": [ { "name": "string", "description": "string", "indexed": true, "type": "FILTER_ATTRIBUTE_TYPE__UNDEFINED", "level": "FILTER_ATTRIBUTE_LEVEL__UNDEFINED" } ] }, "corpusStatus": { "code": "OK", "statusDetail": "string" }, "size": { "epochSecs": "string", "size": "string" }, "sizeStatus": { "code": "OK", "statusDetail": "string" }, "apiKey": [ { "id": "string", "description": "string", "keyType": "API_KEY_TYPE__UNDEFINED", "enabled": true, "tsStart": "string", "tsEnd": "string", "status": "UNKNOWN" } ], "apiKeyStatus": { "code": "OK", "statusDetail": "string" }, "customDimension": [ { "name": "string", "description": "string", "servingDefault": 0, "indexingDefault": 0 } ], "customDimensionStatus": { "code": "OK", "statusDetail": "string" }, "filterAttribute": [ { "name": "string", "description": "string", "indexed": true, "type": "FILTER_ATTRIBUTE_TYPE__UNDEFINED", "level": "FILTER_ATTRIBUTE_LEVEL__UNDEFINED" } ], "filterAttributeStatus": { "code": "OK", "statusDetail": "string" } } ]} An unexpected error response. * application/json * Schema * Example (from schema) **Schema** **code** int32 **message** string **details** object\[\] * Array \[\ \ \ **@type** string\ \ A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted).\ \ In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:\ \ * If no scheme is provided, `https` is assumed.\ \ * An HTTP GET on the URL must yield a \[google.protobuf.Type\]\[\]\ \ value in binary format, or produce an error.\ \ * Applications are allowed to cache lookup results based on the\ \ URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)\ \ \ Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com.\ \ Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics.\ \ * \] { "code": 0, "message": "string", "details": [ { "@type": "string" } ]} Loading... ---