REST APIs

While gRPC provides low latency and excellent scalability, REST APIs provide a traditional integration path for web-based applications. With the introduction of Vectara's REST API 2.0, developers can now leverage a more intuitive and user-friendly API design that follows RESTful principles and simplifies the getting started experience.

caution

Review the REST API 1.0 to 2.0 migration guide which highlights important differences between the Vectara REST API v1 and REST API v2.

API formatting guidelines

You can find all of our APIs at https://api.vectara.io/v2/<api-endpoint> The API endpoints are outlined in the various subsections of this API Reference section and are designed to be intuitive and follow a standard RESTful structure.

• The current version is v2.
• api-endpoint follows a hierarchical structure, using lowercase and hyphens. For example, /corpora/:corpus_key/documents.

API authentication

All Vectara APIs are authenticated. Indexing and Search APIs can be authenticated via API Keys. The Personal API Key enables most Admin actions for creating and deleting corpora, but for deleting accounts and accessing billing data, you need to use OAuth 2.0.

API Reference and OpenAPI specifications

You can find up-to-date OpenAPI specifications at https://docs.vectara.com/vectara-oas-2.yaml. These specifications provide a comprehensive overview of the available endpoints, request/response formats, and authentication requirements.

You can use these with tools of your choosing like Insomnia or Postman.

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 Reference and make real-time API calls from your browser.

List of Vectara REST 2.0 endpoints

Vectara provides the following REST 2.0 endpoints:

Request timeouts

By default, requests will take as long as they need to complete. However, you can request a maximum time for most of the APIs to take by specifying the Request-Timeout or Request-Timeout-Millis parameters in the HTTP headers. Request-Timeout is specified in seconds and if you need a more granular timeout, you can use Request-Timeout-Millis. Note that both parameters are considered best-effort: in the event either time lapses, Vectara will attempt to terminate the request as soon as possible after.

Queries

The following endpoints help you with queries:

• Query API: Perform searches across one or more corpora using advanced filtering, pagination, and summarization options.
• Simple Corpus Query API: Execute lightweight searches on a single corpus.
• Advanced Corpus Query API: Perform advanced queries on a specific corpus with additional filtering and customization options.

Corpora

The following endpoints enable you to programmatically manipulate corpora and perform many operations such as viewing corpus consumption, size, associated API keys, and more:

• Create Corpus API: Create a new corpus to store and manage documents.
• List Corpora API: Get a list of all corpora in your account.
• Get Corpus API: Retrieve metadata about a specific corpus.
• Delete Corpus API: Remove a corpus and all its associated data.
• Update Corpus API: Enable/disable the corpus or update filter attributes.
• Reset Corpus API: Clear all documents and data from a corpus while keeping the corpus itself.
• Replace Corpus Filter Attributes API: Update the filterable attributes of a corpus.

Index and upload documents

The following endpoints help you index, upload files, and manage documents:

• Index Document API: Add a document to a corpus in either structured or core format.
• File Upload API: Upload files to a corpus for automatic parsing and document extraction.
• List Documents API: Retrieve a list of documents in a specific corpus.
• Delete Document API: Remove a document from a corpus.

Chats

The following endpoints provide a streamlined solution for integrating chatbot functionalities into domain-specific applications and websites using Retrieval Augmented Generation (RAG):

• Chat API Overview describes chats at a higher level.
• Create Chat API: Start a new chat session with default retrieval parameters.
• List Chats API: Get a list of all chat sessions.
• Get Chat API: Retrieve a chat summary, including the initial message.
• Delete Chat API: Remove a chat session and all its associated turns.
• Create Chat Turn API: Add a message-response pair, also known as a turn, to an existing chat.
• Get Chat Turn API: Retrieve a specific turn from a chat.
• List Chat Turns API: Get a list of all turns within a chat.
• Update Chat Turn API: Modify a turn, such as enabling or disabling it.
• Delete Chat Turn API: Remove a turn from a chat, along with all subsequent turns.

Encoders, rerankers, and large language models (LLMs)

The following endpoints help you manage encoders, rerankers, and LLMs:

• List Encoders API: Get a list of available encoders for document embedding.
• List Rerankers API: Get a list of available rerankers for improving search result ranking.
• List Language Models (LLMs) API: Get a list of available large language models for query and chat endpoints.
• List Generation Presets API

Jobs

The following endpoints help you manage background jobs:

• Get Job API: Retrieve details about a specific background job.
• List Jobs API: Get a list of all background jobs for the account.

Users

The following endpoints help you manage users on your account:

• Create User API: Add a new user to the current customer account.
• Get User API: Retrieve details about a specific user.
• List Users API: Get a list of all users in the account.
• Update User API: Modify a user's details, such as enabled status or assigned roles.
• Delete User API: Remove a user from the account.
• Reset User Password API: Initiate a password reset for a user.

API keys

The following endpoints help you manage the lifecycle and security of API keys:

• Create API Key API: Generate a new API key for authentication.
• Get API Key API: Retrieve details about a specific API key.
• List API Keys API: Get a list of all API keys for the account.
• Update API Key API: Modify an API key, such as enabling or disabling it.
• Delete API Key API: Remove an API key from the account.

Application Clients

The following endpoints help you manage OAuth 2.0 application clients on your account:

• Create Application Client API: Add a new OAuth 2.0 application client for authentication.
• Get Application Client API: Retrieve details about a specific application client.
• List Application Clients API: Get a list of all application clients for the account.
• Update Application Client API: Modify an application client's details, such as assigned roles.
• Delete Application Client API: Remove an application client from the account.

note

Not all REST API endpoints have long-form documentation in this API Reference. For example, information about Get Usage Metrics is in the API Reference.