TeraVera Secure AI

The TeraVera AI is an enterprise-grade, Azure native AI Agent platform designed for secure, scalable document querying. It processes uploaded documents into searchable content using vector embeddings, keyword search, and LLM-based response generation.

The APIs and endpoints described in this document are intended for developers integrating directly with the system. This includes functionality for document upload, query execution, and response handling. Authentication is handled via OAuth 2.0, and all operations are executed within the scope of the client's secure Azure environment.

Key Features:

• Secure Document Ingestion: Current File Type support (PDF, DOCX, TXT, CSV, Excel)
• Dynamic Indexing Pipeline: Documents are automatically chunked, embedded, and stored.
• Multi-Modal Retrieval: Combines vector search, BM25 keyword ranking, and semantic reranking to return highly relevant document chunks.
• LLM-Based Response Generation: Retrieved data processed and sent along with the prompt to an Azure-hosted LLM (e.g., ChatGPT-4o).
• Tenant-Level Isolation: Each client operates in a fully separated Azure environment enforced via RBAC and Zero Trust architecture.
• No Data Retention: All queries, intermediate data, and outputs are transient—nothing is stored or used for model training.
• Scalable and Fault-Tolerant: The system leverages serverless orchestration to dynamically scale and recover from transient failures.

Requests to the authentication endpoint include a username, access key, and organisation ID:

On successful authentication, a signed JWT is issued as a session token and returned in a Set-Cookie header:

If the authentication endpoint fails, it will produce one of the following error codes

Request to the upload endpoint must include an authorisation header with the bearer token obtained from the authentication endpoint as well as the form data containing the file to be uploaded which is structured as follows:

A successful file upload returns the following response format, regardless of file type:

If the authentication endpoint fails, it will produce one of the following error codes:

Request to the query endpoint include an authorisation header with the token obtained from the authentication endpoint as well as the message containing the query and the files to be queried which is structured as follows:

The meaning of each respective field is as follows:

• Query: A required natural language question posed by the user. This is used to perform semantic search across indexed content and to drive LLM response generation.
• OrganisationId: A required identifier representing the client or tenant. This is used to enforce data isolation and access control between different clients.
• AgentId: A required identifier for the current project or knowledgebase. It ensures the query is scoped to the correct set of uploaded documents and associated data.
• ProjectSummary: An optional description of the project or query context that may be inserted into the prompt to help the LLM disambiguate answers.
• NotFoundMessage: An optional custom message returned when no relevant content is found in either structured or unstructured sources. If not provided, a default fallback message is used.

The meaning of each respective field is as follows:

• Context: The full prompt sent to the LLM, including the query, retrieved content, and any optional metadata like project summaries.
• GeneratedResponse: A nested object containing the output from the language model and metadata about response generation.
  • Response: The final natural language answer generated by the model, grounded in the retrieved content.
  • FileNames: A list of files that contributed content to the generated answer. May be null if not applicable.
  • AnswerFound: A boolean indicating whether a meaningful answer was returned (true) or the NotFoundMessage was used (false).
  • InputTokens: Number of tokens consumed in constructing the LLM prompt.
  • OutputTokens: Number of tokens in the model's generated response.
• FileNames (outside GeneratedResponse): A list of all files matched during search, whether or not they contributed to the final response.
• SearchResults: Raw search results from unstructured sources, including scored document chunks and associated metadata.
• TableResults: Structured data results from document if relevant, including table schema and rows. May be null if none found.
• ErrorMessage: A plain text field that remains empty on success.
• IsSuccess: A boolean flag indicating whether the query operation was successfully processed.

If the authentication endpoint fails, it will produce one of the following error codes:

Request to the delete endpoint include an authorisation header with the token obtained from the authentication endpoint as well as the message containing the file to be deleted which is structured as follows:

On successful deletion of the file, a plain text message is returned:

If the delete endpoint fails, it will produce one of the following error codes: