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.

Note: Throughout this documentation, AgentId and OrganisationID are represented as your unique GUIDs(Globally Unique Identifiers) - long alphanumeric strings (e.g., 550e8400-e29b-41d4-a716-446655440000) that let us uniquely identify your agent and organisation.

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:

Once you receive the JWT token from the authentication endpoint include it in the Authorisation header for all subsequent API requests:

Replace the token value with the actual JWT token you received in the successful authentication response.

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

Request to the create agent endpoint must include an authorization header with the token obtained from the authentication endpoint as well as the message containing the agent configuration, structured as follows:

The meaning of each respective field is as follows:

• Id: An optional unique identifier for the agent. If provided the system will use this as the agent GUID.If not provided, a new GUID will be automatically generated for this agent. 
• Name: An optional display name for the agent. If not provided, defaults to "ApiCreated-{AgentId}".
• Description: An optional human-readable description explaining the agent's purpose and capabilities.
• Plugins: A required array of plugin type identifiers (enums) that define the agent's capabilities. Available plugins must be enabled for the organisation.
• Instructions: Behavioral instructions that guide how the agent should respond to queries and interact with users.
• OrganisationId: A required identifier representing the organisation that will own this agent. Must be a valid organisation GUID.
• IsDynamicFlexibility: A boolean flag indicating whether the agent should dynamically adjust its response flexibility based on context.
• Flexibility: An enumerated value representing the agent's response flexibility level (affects how creative or conservative responses are).
• Scope: An enumerated value representing the agent's operational scope (defines who can access the agent)
• AllowDocumentDownload: A boolean flag indicating whether users can download source documents through this agent.
• GenerateRawChatGptResponse: A boolean flag for including raw LLM responses alongside processed answers.
• NotFoundMessage: An optional custom message displayed when the agent cannot find relevant content. Defaults to empty string if not provided.
• PresetPrompts: An optional dictionary of predefined prompts that can be used to standardize common interactions.

The meaning of each respective field is as follows:

• Message: A confirmation message indicating successful agent update.
• Agent: The complete created agent object showing all current values after the create operation.

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

Request to the list agents endpoint must include an authorization header with the token obtained from the authentication endpoint as well as the message containing optional filter parameters, structured as follows:

The meaning of each respective field is as follows:

• UserId: An optional identifier for a specific user. When provided, returns agents created by that user. If not provided, defaults to the authenticated user's agents (for basic users) or broader scope (for elevated users).
• OrganisationId: An optional identifier representing the organisation. When provided, returns all agents within that organisation (subject to user permissions). Users can only access agents within their own organisation.
• ShowDeletedAgents: An optional boolean flag indicating whether to include deleted agents in the response. Defaults to false if not specified.

The meaning of each respective field is as follows:

• Message: A descriptive message indicating the scope of agents returned (e.g., "User agents", "Organisation Agents", "All agents").
• AgentCount: The total number of agents returned in the response.
• Agents: An array of agent objects containing detailed information about each agent: 
• Id: Unique identifier for the agent
• Name: Display name of the agent
• Instructions: Behavioral instructions configured for the agent
• CreatedDate: Date the agent was created (format: DD.MM.YYYY)
• CreatedDateTime: Full timestamp when the agent was created
• Status: Numeric status code representing the agent's current state
• Description: Human-readable description of the agent's purpose
• OrganisationId: GUID of the organisation that owns the agent
• OrganisationName: Display name of the owning organisation
• CreatedByUserId: GUID of the user who created the agent
• CreatedByUserName: Display name of the user who created the agent
• IsFlexibilityDynamic: Boolean indicating if flexibility settings are dynamically adjusted
• PresetPrompts: Array of predefined prompts for the agent (may be null)
• IsDynamicFlexibility: Boolean flag for dynamic flexibility mode
• Flexibility: Enum value representing the agent's response flexibility level
• Scope: Numeric value representing the agent's operational scope
• AllowDocumentDownload: Boolean indicating if users can download documents through this agent
• GenerateRawChatGptResponse: Boolean flag for including raw LLM responses
• NotFoundMessage: Custom message displayed when no relevant content is found

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

Request to the update agent endpoint must include an authorization header with the token obtained from the authentication endpoint as well as the message containing the agent updates, structured as follows:

The meaning of each respective field is as follows:

• Id: A required unique identifier for the agent to be updated. Must be a valid agent GUID that exists and is not deleted.
• Name: An optional new display name for the agent. Only updates when a non-null value is provided.
• Description: An optional new description for the agent. Updates when provided, including null values which will clear the existing description.
• Plugins: An optional array of plugin type identifiers to replace the agent's current plugin configuration. All specified plugins must be enabled for the organisation.
• Instructions: An optional new set of behavioral instructions. Only updates when a non-null value is provided.
• IsDynamicFlexibility: An optional boolean to enable or disable dynamic flexibility mode.
• Flexibility: An optional enumerated value to set the agent's response flexibility level.
• Scope: An optional enumerated value to set the agent's operational scope.
• AllowDocumentDownload: An optional boolean to enable or disable document download permissions.
• GenerateRawChatGptResponse: An optional boolean to enable or disable raw LLM response inclusion.
• NotFoundMessage: An optional custom message for when no relevant content is found. Only updates when a non-null value is provided.
• PresetPrompts: An optional dictionary of predefined prompts. When provided, completely replaces the existing preset prompts collection.

The meaning of each respective field is as follows:

• Message: A confirmation message indicating successful agent update.
• Agent: The complete updated agent object showing all current values after the update operation, including both modified and unchanged fields.

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

Request to the delete agent endpoint must include an authorization header with the token obtained from the authentication endpoint as well as the message containing the agent identifiers, structured as follows:

The meaning of each respective field is as follows:

• 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 delete request is scoped to the correct set of uploaded documents and associated data.

The endpoint returns a plain text success message indicating the scope of deletion:

Full Deletion: 

When both search index documents and blob storage files are found and deleted.

Index Only:

When only search index documents are found and deleted.

Blobs Only: 

When only blob storage files are found and deleted.

No Files Found: 

When the agent exists but has no associated files.

If the list agent 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.
• UserId: An optional identifier for the user making the request. Used for logging and access control.
• ConversationId: An optional identifier for maintaining conversation context. If not provided, a new conversation ID will be generated automatically.
• Messages: An optional array of previous conversation messages to provide context. Only the last 20 messages are processed. Each message should contain: 
  
  • Role: The message sender ("user", "assistant", "system")
  • Content: The message content
• FilesToSearch: An optional array of specific file ids to search within. If not provided, all files associated with the agent will be searched.
• 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. If not provided, defaults to "Apologies I could not find what you are looking for. Please rephrase your prompt".
• Flexibility: An optional AgentFlexibility enum value (0-3) controlling response creativity. Defaults to PartiallyOpen (2).
• IsRawChatGptResponseOn: An optional boolean flag to include raw LLM responses in the output. Defaults to false.
• RagMode: An optional RagMode enum value specifying the retrieval mode. Defaults to Text (0).
• RequestedModes: An optional array of RagMode values for multi-mode processing. When specified, the system will process the query using multiple RAG modes and combine results.

The meaning of each respective field is as follows:

• Entity: Main response container object containing all query results and metadata
  Context: The full context that was included for the content retrieval
• GeneratedResponse: Object containing the language model's response and processing metadata 
  
  • Response: The natural language answer generated by the system based on retrieved content
  • DataSource: Dictionary mapping unique file identifiers to their display names for files that contributed content to the answer
  • InputTokens: Total number of tokens consumed in generating the LLM prompts
  • OutputTokens: Total number of tokens produced by the language model in its responses
  • AnswerFound: Boolean indicating whether meaningful content was found and used to generate an answer
  • FileNames: Array of unique file identifiers for all files that were matched during the search process
• SearchResults: Array of search result objects containing document chunks, metadata, and relevance scores
• ConversationId: Unique identifier for the conversation session, used to maintain context across multiple queries
• ErrorMessage: Text field containing error details when the operation fails, empty when successful
• IsSuccess: Boolean flag indicating whether the query operation completed successfully

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:

Defines the available plugin capabilities that can be assigned to agents:

Usage Example:

Can be used when creating or updating an agent to assign plugins per agent.

Controls how creatively the agent responds to queries:

Usage Example:

Can be used to set the agent flexibility to partially open when creating or updating an agent.

Indicates the current operational state of an agent:

Usage Example:

Can be used when creating or updating agent to set the agent to be accessible by affiliates.

Indicates the current operational state of an agent:

Usage Example:

Can be used to update an agent to Inactive.

Defines the retrieval and processing modes available for queries:

Usage Examples:

Agent will use Text Rag Mode only.

Agent will use Text and DocAi Rag Modes for this query.