Developer Api

Introduction

System Overview

Teravera Secure AI API V2.0
API Version	Release Date	End of Life (EOL)	Type
V2.0	17.12.2025	N/A	Major

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 JWT bearer tokens, 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.

System Access

Authentication

All API requests to the Teravera AI system must be authenticated using a valid JWT bearer token. Tokens are issued via the /api/v2/authenticate endpoint.

Authentication Request Format

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

{
  "Username": "Your Username Here",
  "AccessKey": "Your Access Key Here",
  "OrganisationId": "Your Organisation GUID Here"
}

Authentication Success Response

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

{
  "Token": "Output JWT Token Here",
  "Expires": "expiry date here - yyyy-MM-ddTHH:mm:ssZ"
}

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

Authorization: Bearer abcdefghijklmnop123456...

Authentication Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Agents

Create Agent Endpoint

The /api/v2/agents/create endpoint creates a new agent with the specified configuration and capabilities.

Create Agent Request Format

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:

{
  "Name": "example agent",
  // Optional Fields
  "Id": "Optional Agent GUID Here",
  "Description": "Optional description of the agent",
  "Plugins": [0,1,2,3],
  "Instructions": "Behavioral instructions for the agent",
  "Flexibility": 1,
  "Scope": 0,
  "ShowDocumentReference": false,
  "AllowDocumentDownload": true,
  "GenerateRawChatGptResponse": false,
  "NotFoundMessage": "Custom message when no answer is found",
  "PresetPrompts": {
    "Prompt Question": "Prompt Answer"
  }
}

The meaning of each respective field is as follows:

Name: A required display name for the agent.
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.
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.
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)
ShowDocumentReference: A boolean flag indicating whether to show a reference to source documents through this 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 standard message if not provided.
PresetPrompts: An optional dictionary of predefined prompts that can be used to standardize common interactions.

Create Agent Success Response

{
  "Message": "New Agent Created.",
  "Agent": {
    "Details": {
      "Id": "New Agent GUID",
      "Name": "example name",
      "Status": "Active",
      "Description": "example description",
      "CreatedDateTime": "01.01.2025 12:00:00",
      "OrganisationId": "Organisation GUID",
      "OrganisationName": "Organisation Name",
      "CreatedByUserId": "User GUID",
      "CreatedByUserName": "User Name"
    },
    "Settings": {
      "Instructions": "example instructions",
      "NotFoundMessage": "example not found message",
      "Flexibility": "FullyClosed",
      "Scope": "Local",
      "ShowDocumentReference": false,
      "AllowDocumentDownload": false,
      "GenerateRawChatGptResponse": false,
      "Plugins": ["LocalDocumentUpload"],
      "PresetPrompts": { "Example Prompt": "Example Response" }
    }
  }
}

The meaning of each respective field is as follows:

Message: A confirmation message indicating successful agent creation.
Agent: The complete created agent object with nested Details and Settings objects.
Details: Contains agent identification and metadata (Id, Name, Status, Description, timestamps, organisation and user info).
Settings:Contains agent configuration (Instructions, NotFoundMessage, Flexibility, Scope, flags, Plugins, PresetPrompts).

Create Agent Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Endpoints Specific Errors

Status Code	Description	Common Causes
409 Conflict	Agent Id is not unique or has been deleted	Attempting to use an existing or deleted agents GUID
403 Forbidden	Organisation does not have access to requested plugins	Specifying plugin types not available with your service/subscription tier

List Agents Endpoint

The /api/v2/agents/list endpoint retrieves a list of available agents based on the user's access permissions.

List Agents Request Format

Request to the list agents endpoint must include an authorization header with the token obtained from the authentication endpoint:

{
  "ShowDeletedAgents": false
}

The meaning of each respective field is as follows:

ShowDeletedAgents: An optional boolean flag indicating whether to include deleted agents. Defaults to false.

List Agents Success Response

{
  "Message": "All agents",
  "AgentCount": 3,
  "Agents": [
    {
      "Id": "Agent GUID",
      "Name": "Example Agent Name",
      "Status": "Active",
      "Description": "Agent description here",
      "CreatedDateTime": "01.01.2025 12:00:00",
      "OrganisationId": "Organisation GUID",
      "OrganisationName": "Organisation Name",
      "CreatedByUserId": "User GUID",
      "CreatedByUserName": "User Name"
    }
  ]
}

The meaning of each respective field is as follows:

Message: A confirmation message indicating successful agent update.
AgentCount: The complete created agent object showing all current values after the create operation.
Agents: An array of agent detail objects containing identificaion and metadata for each agent.

List Agents Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Endpoints Specific Errors

Status Code	Description	Common Causes
403 Forbidden	You do not have access to this agent	Attempting to access agents outside your access scope
404 Not Found	Agent not found	Agent does not exist or has been removed
409 Conflict	Agent has been deleted	Attempting to access a deleted agent

Update Agent Endpoint

The /api/v2/agents/update endpoint modifies an existing agent's configuration, allowing partial updates.

Update Agent Request Format

Request to the update agent endpoint must include an authorization header:

{
  "Id": "Your Agent GUID",
  // Optional Fields to update
  "Name": "Updated Agent Name",
  "Description": "Updated description",
  "Plugins": [0, 1],
  "Instructions": "Updated behavioral instructions",
  "Flexibility": 2,
  "Scope": 1,
  "ShowDocumentReference": false,
  "AllowDocumentDownload": true,
  "GenerateRawChatGptResponse": false,
  "NotFoundMessage": "Updated not found message",
  "PresetPrompts": { "updated prompt": "updated answer" },
  "Overwrite": false
}

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.
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.
ShowDocumentReference: A Boolean flag indicating whether to show a reference to source documents through this agent
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.
Overwrite: An optional boolean. When true, replaces existing Plugins and PresetPrompts entirely. When false (default), adds to existing collections.

Update Agent Success Response

{
  "Message": "Agent Updated",
  "Agent": {
    "Details": {
      "Id": "Agent GUID",
      "Name": "example agent",
      "Status": "Active",
      "Description": "description of agent",
      "CreatedDateTime": "01.01.2025 12:00:00",
      "OrganisationId": "Organisation GUID",
      "OrganisationName": "Organisation Name",
      "CreatedByUserId": "User GUID",
      "CreatedByUserName": "User Name"
    },
    "Settings": {
      "Instructions": "example instructions",
      "NotFoundMessage": "example not found message",
      "Flexibility": "PartiallyOpen",
      "Scope": "Affiliates",
      "ShowDocumentReference": true,
      "AllowDocumentDownload": false,
      "GenerateRawChatGptResponse": true,
      "Plugins": ["LocalDocumentUpload", "StructuredDocuments"],
      "PresetPrompts": { "Example question": "Example answer" }
    }
  }
}

The meaning of each respective field is as follows:

Message: A confirmation message indicating successful agent update.
Agent: The complete updated agent object with nested Details and Settings objects.
Details: Contains agent identification and metadata.
Settings: Contains agent configuration including all current values after the update.

Update Agent Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Endpoints Specific Errors

Status Code	Description	Common Causes
409 Conflict	Agent Id is not unique or has been deleted	Attempting to use an existing or deleted agents GUID
403 Forbidden	Organisation does not have access to requested plugins	Specifying plugin types not available with your service/subscription tier

Get Agent Endpoint

The GET /api/v2/agents/{id} endpoint retrieves a single agent's full details including settings.

Get Agent Request Format

Request to the get agent endpoint must include an authorization header with the token obtained from the authentication endpoint. The agent ID is passed as a route parameter.

Route Parameter:

Id:Required. The GUID of the agent to retrieve

Get Agent Success Response

{
  "Message": "Agent Example Agent Name",
  "Agent": {
    "Details": {
      "Id": "Agent GUID",
      "Name": "Example Agent Name",
      "Status": "Active",
      "Description": "Agent description",
      "CreatedDateTime": "01.01.2025 12:00:00",
      "OrganisationId": "Organisation GUID",
      "OrganisationName": "Organisation Name",
      "CreatedByUserId": "User GUID",
      "CreatedByUserName": "User Name"
    },
    "Settings": {
      "Instructions": "Agent instructions",
      "NotFoundMessage": "Not found message",
      "Flexibility": "FullyClosed",
      "Scope": "Local",
      "ShowDocumentReference": false,
      "AllowDocumentDownload": false,
      "GenerateRawChatGptResponse": false,
      "Plugins": ["LocalDocumentUpload"],
      "PresetPrompts": { "Prompt": "Answer" }
    }
  }
}

The meaning of each respective field is as follows:

Message: A confirmation message including the agent name
Agent: The complete updated agent object with nested Details and Settings objects.
Details: Contains agent identification and metadata.
Settings: Contains agent configuration including instructions,plugins and prompts.

Get Agent Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Endpoints Specific Errors

Status Code	Description	Common Causes
409 Conflict	Agent has been deleted	Attempting to retrieve a deleted agent

Delete Agent Endpoint

The /api/v2/agents/delete endpoint permanently deletes an agent along with all associated files.

Delete Agent Request Format

Request to the delete agent endpoint must include an authorization header:

{
  "AgentId": "Your Agent GUID Here"
}

The meaning of each respective field is as follows:

AgentId: A required identifier for the agent to delete.

Delete Agent Success Response

{
  "Message": "Agent deleted Successfully",
  "AgentId": "Deleted Agent GUID"
}

The meaning of each respective field is as follows:

Message: A confirmation message indicating successful agent deletion.
AgentId: The GUID of the deleted agent.

Delete Agent Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Endpoints Specific Errors

Status Code	Description	Common Causes
409 Conflict	Agent has been deleted	Attempting to retrieve a deleted agent
500/502	Internal proccessing errors	File cleanup or deletion failures

Verify agent status before deletion.For Internal errors , contact support with the traceId.

Chat

Chat Endpoint

The /api/v2/agents/ask endpoint accepts a natural language query and returns a context-aware response.

Chat Request Format

Request to the query endpoint must include an authorization header:

{
  "Query": "Example Query",
  "AgentId": "Your Agent GUID Here",
  // Optional fields below
  "ConversationId": "Optional Conversation GUID",
  "Messages": [
    { "role": "user", "content": "Previous message content" },
    { "role": "assistant", "content": "Previous assistant response" }
  ],
  "FilesToSearch": ["file1.pdf", "file2.docx"],
  "ProjectSummary": "Optional project context",
  "RagMode": 0,
  "RequestedModes": [0, 1]
}

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.
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.
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.
FilesToSearch: An optional project context to help guide responses.
RagMode: An optional RAG mode (0=Text, 1=Table, 2=DocAI, 3=LLMAction).
RequestModes: An optional array of requested RAG modes.

Chat Success Response

{
  "Context": "...",
  "GeneratedResponse": {
    "Response": "Here is the answer to your query...",
    "RawChatGptResponse": "",
    "DataSource": {
      "file-id-1": "document1.pdf",
      "file-id-2": "document2.docx"
    },
    "AnswerFound": true,
    "InputTokens": 902,
    "OutputTokens": 40
  },
  "FileNames": ["file-id-1", "file-id-2"],
  "Files": [
    {
      "FileId": "file-id-1",
      "FileName": "document1.pdf",
      "DownloadUrl": "https://api.teravera.com/v2/files/download?agentId=...&fileId=..."
    }
  ],
  "ConversationId": "Conversation GUID"
}

The meaning of each respective field is as follows:

Context: The Full context used for content retrieval.
GeneratedResponse: Object containing the LLM response and metadata.
Response: The natural language answer generated by the system.
RawChatGptResponse: Raw LLM response (empty unless enabled).
DataSource: Dictionary mapping file IDs to file names.
AnswerFound: Boolean indicating whether relevant content was found.
InputTokens: Number of tokens consumed in the prompt.
OutputTokens: Number of tokens in the response.
FileNames: Array of file IDs that matched the search.
Files: Array of file objects with download URLs (if AllowDocumentDownload is enabled).
ConversationId: The conversation session identifier.

Chat Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Chat History Endpoint

The /api/v2/agents/chat/history conversation history for a specific agent and user.

Chat History Request Format

Request to the chat history endpoint must include an authorization header with the token obtained from the authentication endpoint:

{
  "AgentId": "Your Agent GUID Here",
  // Optional fields
  "TakeCount": 50,
"SearchTerm": "optional search filter"
}

The meaning of each respective field is as follows:

AgentId: required identifier for the agent to query
TakeCount: An optional integer limiting the number of conversations returned.
SearchTerm: An optional string to filter conversations by content

Chat History Success Response

{
"Message": "OK",
"AgentId": "Agent GUID",
"UserId": "User GUID",
"ChatHistory": [
{ 
"ConversationId": "conv-guid-1", "Messages": [...], "CreatedDate": "2025-01-01T12:00:00Z" },
{ 
"ConversationId": "conv-guid-2", "Messages": [...], "CreatedDate": "2025-01-02T14:30:00Z" 
}
]
}

The meaning of each respective field is as follows:

Message: A status message confirming successful retrieval.
AgentId: The agent GUID for the returned history
UserId: The effective user ID used for the query.
ChatHistory: An array of conversation objects containing messages and metadata.

Chat History Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Endpoints Specific Errors

Status Code	Description	Common Causes
403 Forbidden	You do not have access to this conversation	Attempting to access a conversation not within your scope
404 Not Found	Conversation not found	Invalid AgentId or no chat history exists

Chat Conversation Endpoint

The /api/v2/agents/chat/conversation endpoint retrieves a specific chat conversation by its unique conversation ID.

Chat Conversation Request Format

Request to the chat conversation endpoint must include an authorization header with the token obtained from the authentication endpoint:

{
  "AgentId": "Your Agent GUID Here",
    "ConversationId": "Your Conversation GUID Here",
}

The meaning of each respective field is as follows:

AgentId: A required identifier for the agent to retrieve from.
ConversationId: A required unique identifier for the specific conversation to retrieve

Chat Conversation Success Response

{

"AgentId": "Agent GUID",
"UserId": "User GUID",
"ConversationId": "Conversation GUID",
"ChatHistory": [
{ "role": "user", "content": "User message content" },
{ "role": "assistant", "content": "Assistant response content" }
]
}

The meaning of each respective field is as follows:

AgentId: The Agent GUID for the returned history.
UserId: The user ID for the conversation history.
ConversationId: The unique identifier of the retrieved conversation
ChatHistory: An array of conversation objects containing the full conversation thread.

Chat Conversation Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Endpoints Specific Errors

Status Code	Description	Common Causes
403 Forbidden	You do not have access to this conversation	Attempting to access a conversation outside access scope
404 Not Found	Conversation not found or has been deleted	Invalid ConversationId or conversation has been removed

Delete Chat Conversation Endpoint

The /api/v2/agents/chat/delete endpoint retrieves a specific chat conversation by its unique conversation ID.

Delete Chat Conversation Request Format

Request to the delete chat conversation endpoint must include an authorization header with the token obtained from the authentication endpoint:

{
  "AgentId": "Your Agent GUID Here",
    "ConversationId": "Your Conversation GUID Here",
}

The meaning of each respective field is as follows:

AgentId: A required identifier for the agent that owns the conversation
ConversationId: A required unique identifier for the conversation to delete

Delete Chat Conversation Success Response

{
"Message":"Chat history for conversation 'conv-guid' deleted successfully",
"AgentId": "Agent GUID",
"ConversationId": "Deleted Conversation GUID"
}

The meaning of each respective field is as follows:

Message: A confirmation message indicating successful deletion. Message varies based on deletion state (already deleted, partially deleted, or fully deleted).
AgentId:The agent GUID for the returned history.
ConversationId: The unique identifier of the deleted conversation

Delete Chat Conversation Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Endpoints Specific Errors

Status Code	Description	Common Causes
403 Forbidden	You do not have access to this conversation	Attempting to access a conversation outside access scope
404 Not Found	Conversation not found	Invalid ConversationId

File

Upload Endpoint

The /api/v2/files/upload endpoint handles uploading of documents. Supported file types include .pdf, .docx, .txt

Upload Request Format

Request to the upload endpoint must include an authorization header with the bearer token as well as multipart form-data containing:

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Endpoints Specific Errors

Field	Type	Description
AgentId	text	Required. The agent GUID to upload the file to.
File	file	Required. The file to upload.
UseDocumentIntelligence	text(boolean)	Optional. Enable Document Intelligence processing.
Pages	text	Optional. Specific pages to process (for DocAI).

Upload Success Response

{
  "Message": "File received and beginning indexing...",
  "FileId": "Generated File GUID",
  "FileName": "original-filename.pdf"
}

Response Codes:

202 Accepted:Background Proccesing started for text documents.
200 OK:DocAI files processed immediately.

Upload Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Endpoints Specific Errors

Status Code	Description	Common Causes
409 Conflict	File with name already exists	Uploading a file with a duplicate filename to the same agent
403 Forbidden	You do not have permission to access this agent	Attempting to upload to an agent outside your access scope
404 Not Found	Agent not found	Invalid AgentId or agent has been removed
413 Request Entity Too Large	File exceeds token limit	Document contains more than 200,000 tokens

For duplicate filename conflicts, either rename the file or use the generated FileId from a previous upload to reference existing files.
For large documents, split the document into smaller files.

Upload Status Endpoint

The /api/v2/files/status endpoint retrieves the current processing status of an uploaded file.

Upload Status Request Format

Request to the status endpoint must include an authorization header obtained from the authentication endpoint:

{
  "AgentId": "Your Agent GUID Here",
  // Specify one of these parameters
  "FileId": "File GUID to check",
  "FileName": "Alternative: FileName to check"
}

Upload Status Success Response

{
  "FileStatus": "File is ready",
  "UploadDate": "2025-01-01T12:00:00Z",
  "DeletedDate": null
}

The meaning of each respective field is as follows:

FileStatus: Human-readable status message. Possible values: "File is ready", "File is processing", "File is awaiting completion", "File has been deleted", "File processing has failed, please re-upload the file".
UploadDate: Timestamp whenthe file was uploaded
DeleteDate: Timestamp when file was deleted(null if not deleted)

Upload Status Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Endpoints Specific Errors

Status Code	Description	Common Causes
403 Forbidden	You do not have permission to access this agent	Attempting to check status for an agent outside your access scope
404 Not Found	Agent not found	Invalid AgentId or agent has been removed
404 Not Found	File not found	Invalid FileId/FileName or file does not belong to the specified agent
409 Conflict	Multiple files with same name found	Using FileName when multiple files share the same name

For filename conflicts, use the FileId parameter instead of FileName to target the specific file. The conflict response includes a list of matching files with their IDs.

List Files Endpoint

The /api/v2/files/list endpoint retrieves a list of files for a specified agent.

List Files Request Format

Request to the list endpoint must include an authorization header:

{
  "AgentId": "Your Agent GUID Here",
  "ShowDeletedFiles": false
}

The meaning of each respective field is as follows:

AgentId: :The AgentId to list files for.
ShowDeletedFiles: Optional boolean. When true, includes deleted files in the response. Defaults to false.

List Files Success Response


  "Message": "Agent Example Agent Files",
  "FileCount": 3,
  "Files": [
    {
      "Id": "File GUID",
      "Name": "document.pdf",
      "UploadedDate": "01.01.2025",
      "ReadableName": "Readable Document Name",
      "Status": "Completed",
      "DownloadUrl": "https://api.teravera.com/v2/files/download?agentId=...&fileId=..."
    }
  ]
}

The meaning of each respective field is as follows:

Message: Descriptive message including the agent name.
FileCount: Total number of files returned.
Files: Array of file objects.
Id: The file's unique GUID.
Name: Original filename.
UploadedDate: Date the file was uploaded.
ReadableName: Human-readable file name.
Status: Current processing status (e.g., "Completed", "Processing", "Failed")
DownloadUrl: Download link (only if agent has AllowDocumentDownload enabled).

List Files Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Endpoints Specific Errors

Status Code	Description	Common Causes
403 Forbidden	You do not have permission to access this agent	Attempting to check status for an agent outside your access scope
404 Not Found	Agent not found	Invalid AgentId or agent has been removed
409 Conflict	Agent has been delted	Attempting to list files for a deleted agent

Use the List Agents endpoint with ShowDeletedAgents parameter to verify agent status before listing files.

Delete File Endpoint

The /api/v2/files/delete endpoint removes both the file storage and indexed document chunks.

Request to the delete endpoint must include an authorization header:

{
  "AgentId": "Your Agent GUID Here",
  // Specify one of the following
  "FileId": "File GUID to delete",
  "FileName": "Alternative: FileName to delete",
  // Optional
  "DeleteAllFiles": false
}

The meaning of each respective field is as follows:

AgentId: Required. The agent GUID that owns the file(s).
FileId: Optional. The GUID of the specific file to delete.
FileName: Optional. Alternative to FileId - the filename to delete.
DeleteAllFiles: Optional boolean. When true, deletes all files for the agent.

Delete File Success Format

{
  "Message": "File successfully deleted",
  "DeletedFileNames": ["filename.pdf"],
  "AgentId": "Agent GUID"
}

The meaning of each respective field is as follows:

Message: Confirmation message indicating successful deletion.
DeletedFileNames: Array of filenames that were deleted.
AgentId: The agent GUID the files belonged to.

Delete File Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Endpoints Specific Errors

Status Code	Description	Common Causes
403 Forbidden	You do not have permission to access this agent	Attempting to check status for an agent outside your access scope
403 Forbidden	You do not have permission to access this file	Insufficient permissions for the specific file
404 Not Found	Agent not found	Invalid AgentId or agent has been removed
404 Not Found	File not found	Invalid FileId/FileName or file does not belong to the specified agent
502 Bad Gateway	Upstream service error	Internal storage or indexing operation failed

For 502 errors, retry the request after a short delay. If the error persists, contact support with the traceId from the response.

Download File Endpoint

The GET /api/v2/files/download endpoint retrieves a file for download.

Download File Request Format

Request via query parameters with authorization header:

GET /api/v2/files/download?agentId={agentId}&fileId={fileId}

The meaning of each respective field is as follows:

agentId: Required. The agent GUID.
fileId: Required. The file GUID to download.

Note: Download is only available if the agent has AllowDocumentDownload enabled.

Download File Success Response

Returns the file as a binary stream with:

Content-Disposition: attachment; filename="original-filename.pdf"
Content-Type: Appropriate MIME type for the file

Download File Error Responses

Error responses use RFC 9457 Problem Details format. See Section 5 for details.

Endpoints Specific Errors

Status Code	Description	Common Causes
403 Forbidden	You do not have permission to download this file	Agent has AllowDocumentDownload disabled or user lacks access
404 Not Found	File not found	Invalid FileId, file has been deleted, or file does not exist in storage
409 Conflict	File State prevents download	File is still processing or in an invalid state.

For 502 errors, retry the request after a short delay. If the error persists, contact support with the traceId from the response.

Error Responses

All error responses from the API conform to the RFC 9457 Problem Details spec using the application/problem+json media type.

Error Response

Error Response Format

Field	Type	Description
type	string	A URI reference identifying the error type
title	string	A short, human-readable summary
status	integer	The HTTP status code
detail	string	A human-readable explanation specific to this occurrence
instance	string	A URI reference identifying the specific occurrence
traceId	string	Correlation ID for support and debugging
errors	object	Validation errors keyed by field name (when applicable)

Example Error Response

{
  "type": "https://teravera.com/developer-api/#createagenterrorresponses",
  "title": "Validation Failed",
  "status": 400,
  "detail": "One or more validation errors occurred.",
  "instance": "/agents/create",
  "traceId": "abc123-def456",
  "errors": {
    "name": ["Name is required"],
    "scope": ["Invalid scope value"]
  }
}

Common Error Responses

Request Errors

Status	Detail
400	Request body is empty.
400	Request body is not valid JSON: {message}

These errors occur when the HTTP request body is missing or contains malformed JSON.

Common Causes:

No request body provided
Invalid JSON syntax (missing or extra brackets, quotes, commas)
Unsupported content encoding

Solution: Ensure your request includes a properly formatted JSON body with Content-Type: application/json header..

Validation Errors

Status	Detail
400	Validation error (see errors field)

These errors occur when the request body is valid JSON but contains invalid or missing field values.

Common Causes:

Missing required fields
Invalid GUID format
Empty string values where content is required
Values outside permitted range

Solution: Check the errors field in the response for specific validation failures. Each key in the errors object corresponds to a field name with an array of error messages.

Authentication Errors

Status	Detail
401	Unauthorized User.

These errors occur when the request body is valid JSON but contains invalid or missing field values.

Common Causes:

Missing required fields
Invalid GUID format
Empty string values where content is required
Values outside permitted range

Solution: Check the errors field in the response for specific validation failures. Each key in the errors object corresponds to a field name with an array of error messages.

Server Errors

Status	Detail
500	Unexpected Server Error.

These errors indicate an unexpected condition on the server that prevented it from fulfilling the request.

Common Causes:

Temporary service unavailability
Internal processing failure
Infrastructure issues

Solution:

Retry the request after a short delay (recommended: exponential backoff)
If the error persists, contact support with the traceId from the response

Support Contact: apisupport@teravera.com

Appendix

Enums

This section provides the complete reference for all enumerated types used in the Teravera Secure AI API. When making API requests, use the integer values shown below.

Plugin Type Enum

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

Value	Name	Description
0	LocalDocumentUpload	Add documents to your agent's knowledgebase to support contextual understanding and intelligent queries.
3	ExternalStorageConnection	Set up a connection to a sharepoint account, Files will be automatically uploaded and processed into this knowledge base

Usage Example: "Plugins": [0,3]

Agent Flexibility Enum

Controls how creatively the agent responds to queries:

Value	Name	Description
0	FullyClosed	Agent strictly adheres to document content, minimal inference
1	PartiallyClosed	Agent primarily uses document content with limited logical inference
2	PartiallyOpen	Agent uses document content but allows moderate creative interpretation
3	FullyOpen	Agent can make broader inferences and creative connections from content

Usage Example: "Flexibility": 2

Agent Scope Enum

Defines who can access and use the agent:

Value	Name	Description
0	Local	Agent access restricted to local organisation users only
1	Affiliates	Agent can be accessed by users from affiliated organizations
2	Global	Agent can be accessed by users across all organisations

Usage Example: "Scope": 1

Agent Status Enum

Indicates the current operational state of an agent:

Value	Name	Description
0	Active	Agent is operational and available for queries
1	Inactive	Agent is temporarily disabled but can be reactivated
2	Deleted	Agent has been permanently deleted and cannot be recovered

Usage Example: "Status": 0