Enterprise Search API
The Enterprise Search Service provides intelligent search capabilities across your organization’s data, enabling users to find information through natural language queries. The service consists of four main components:- Conversation Management - Chat-style interactions with your data
- Agent Conversations - Specialized conversations with AI agents
- Agent Management - Manages AI agents and templates
- Semantic Search - Direct search queries across your content
Base URL
All endpoints are prefixed with/api/v1
Authentication
All endpoints require authentication via Bearer token:CONVERSATION_CREATE- For conversation creationFETCH_CONFIG- For configuration updates
Architecture Overview
The Enterprise Search Service is built on a Node.js backend with MongoDB for data persistence. It leverages AI models to provide accurate responses and semantic search capabilities. The service integrates with:- AI Backend - Processes queries and generates responses
- IAM Service - Handles user authentication and authorization
- Configuration Manager - Manages application settings
Data Models
Conversations
Conversations represent chat sessions with the AI assistant, containing user queries, AI responses, and citations that reference source documents.Agent Conversations
Specialized conversations with specific AI agents, inheriting from regular conversations with additional agent-specific metadata.Citations
References to source documents that back the AI’s responses, including content snippets and comprehensive metadata.Searches
Individual search queries and their results, including citations and metadata.API Endpoints
Conversation Management
Conversation Management
POST /conversations/create - Create Conversation
POST /conversations/create - Create Conversation
- Request
- Response
POST /api/v1/conversations/createRequest Body Parameters:| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | The user’s query (1-100,000 characters) |
| recordIds | string[] | No | MongoDB ObjectIds (24-character hex strings) |
| departments | string[] | No | Department MongoDB ObjectIds |
| filters | object | No | Additional filters to narrow the search |
| filters.apps | string[] | No | App types: “drive”, “gmail”, “onedrive”, “sharepointOnline”, “local” |
| filters.kb | string[] | No | Knowledge base UUIDs (not ObjectIds) |
| modelKey | string | No | Model key for multi-model support |
| modelName | string | No | Model name for multi-model support |
| chatMode | string | No | Chat mode (default: ‘standard’) |
POST /conversations/internal/create - Internal Create
POST /conversations/internal/create - Internal Create
- Request
- Response
POST /api/v1/conversations/internal/createAuthentication: Requires scoped token with CONVERSATION_CREATE scope.Request Body: Same structure as public create endpoint.POST /conversations/stream - Stream Chat
POST /conversations/stream - Stream Chat
- Request
- Response
POST /api/v1/conversations/streamRequest Body: Same as Create ConversationPOST /conversations/:conversationId/messages - Add Message
POST /conversations/:conversationId/messages - Add Message
- Request
- Response
POST /api/v1/conversations/:conversationId/messagesPath Parameters:conversationId: MongoDB ObjectId (24-character hex string)
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | The user’s follow-up question (1-100,000 characters) |
| filters | object | No | Additional filters |
| filters.apps | string[] | No | App types: “drive”, “gmail”, “onedrive”, “sharepointOnline”, “local” |
| filters.kb | string[] | No | Knowledge base UUIDs |
| modelKey | string | No | Model key for multi-model support |
| modelName | string | No | Model name for multi-model support |
| chatMode | string | No | Chat mode |
previousConversations is automatically calculated from existing messages - do NOT include in request.POST /conversations/internal/:conversationId/messages - Internal Add Message
POST /conversations/internal/:conversationId/messages - Internal Add Message
- Request
- Response
POST /api/v1/conversations/internal/:conversationId/messagesAuthentication: Requires scoped token with CONVERSATION_CREATE scope.Request Body: Same structure as public add message endpoint.POST /conversations/:conversationId/messages/stream - Stream Message
POST /conversations/:conversationId/messages/stream - Stream Message
- Request
- Response
POST /api/v1/conversations/:conversationId/messages/streamRequest Body: Same as Add Message (without previousConversations)Behavior:- Adds user message to existing conversation
- Streams AI response in real-time
- Sends custom
completeevent with updated conversation
GET /conversations - Get All Conversations
GET /conversations - Get All Conversations
- Request
- Response
GET /api/v1/conversationsQuery Parameters:| Parameter | Type | Default | Description |
|---|---|---|---|
| page | number | 1 | Page number for pagination |
| limit | number | 20 | Items per page (1-100) |
| sortBy | string | lastActivityAt | Field to sort by (createdAt, lastActivityAt, title) |
| sortOrder | string | desc | Sort order (asc, desc) |
| search | string | - | Search term for filtering |
| startDate | string | - | Filter by start date (ISO format) |
| endDate | string | - | Filter by end date (ISO format) |
| shared | boolean | - | Filter by shared status |
| conversationId | string | - | Filter by specific conversation ID |
GET /conversations/:conversationId - Get Conversation By ID
GET /conversations/:conversationId - Get Conversation By ID
- Request
- Response
GET /api/v1/conversations/:conversationIdQuery Parameters:sortBy: Field to sort messages by (createdAt, messageType, content)sortOrder: Sort order (asc, desc)page: Page number for message paginationlimit: Messages per page
DELETE /conversations/:conversationId - Delete Conversation
DELETE /conversations/:conversationId - Delete Conversation
- Request
- Response
DELETE /api/v1/conversations/:conversationIdAccess Control: Only conversation initiator or users with ‘write’ access can delete.POST /conversations/:conversationId/share - Share Conversation
POST /conversations/:conversationId/share - Share Conversation
POST /conversations/:conversationId/unshare - Unshare Conversation
POST /conversations/:conversationId/unshare - Unshare Conversation
POST /conversations/:conversationId/message/:messageId/regenerate - Regenerate Answer
POST /conversations/:conversationId/message/:messageId/regenerate - Regenerate Answer
- Request
- Response
POST /api/v1/conversations/:conversationId/message/:messageId/regenerateConstraints:- Can only regenerate the last message in the conversation
- Message must be of type
bot_response - Requires at least 2 messages (user query + bot response)
PATCH /conversations/:conversationId/title - Update Title
PATCH /conversations/:conversationId/title - Update Title
- Request
- Response
PATCH /api/v1/conversations/:conversationId/titletitle: Required, 1-200 characters
POST /conversations/:conversationId/message/:messageId/feedback - Add Feedback
POST /conversations/:conversationId/message/:messageId/feedback - Add Feedback
- Request
- Response
POST /api/v1/conversations/:conversationId/message/:messageId/feedbackAccess Control: Conversation initiator, shared users, or publicly shared conversations.Restriction: Cannot provide feedback on user_query messages.incorrect_information,missing_information,irrelevant_informationunclear_explanation,poor_citationsexcellent_answer,helpful_citations,well_explained,other
PATCH /conversations/:conversationId/archive - Archive Conversation
PATCH /conversations/:conversationId/archive - Archive Conversation
- Request
- Response
PATCH /api/v1/conversations/:conversationId/archiveAccess Control: Conversation initiator or users with ‘write’ access.PATCH /conversations/:conversationId/unarchive - Unarchive Conversation
PATCH /conversations/:conversationId/unarchive - Unarchive Conversation
- Request
- Response
PATCH /api/v1/conversations/:conversationId/unarchiveGET /conversations/show/archives - List Archived Conversations
GET /conversations/show/archives - List Archived Conversations
- Request
- Response
GET /api/v1/conversations/show/archivesQuery Parameters: Same pagination and filtering as Get All ConversationsAgent Conversations
Agent Conversations
POST /agent/:agentKey/conversations - Create Agent Conversation
POST /agent/:agentKey/conversations - Create Agent Conversation
- Request
- Response
POST /api/v1/agent/:agentKey/conversationsPath Parameters:agentKey: Unique string identifier for the agent (from ArangoDB)
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | The user’s query (1-100,000 characters) |
| quickMode | boolean | No | Enable quick response mode |
| tools | string[] | No | Available tools for the agent |
| recordIds | string[] | No | MongoDB ObjectIds to search within |
| filters | object | No | Additional filters |
| modelKey | string | No | Model key override |
| modelName | string | No | Model name override |
| chatMode | string | No | Chat mode (default: ‘standard’) |
POST /agent/:agentKey/conversations/stream - Stream Agent Conversation
POST /agent/:agentKey/conversations/stream - Stream Agent Conversation
- Request
- Response
POST /api/v1/agent/:agentKey/conversations/streamRequest Body: Same as Create Agent ConversationPOST /agent/:agentKey/conversations/:conversationId/messages - Add Agent Message
POST /agent/:agentKey/conversations/:conversationId/messages - Add Agent Message
- Request
- Response
POST /api/v1/agent/:agentKey/conversations/:conversationId/messagesRequest Body: Same structure as regular add message, without previousConversations (calculated automatically)POST /agent/:agentKey/conversations/:conversationId/messages/stream - Stream Agent Message
POST /agent/:agentKey/conversations/:conversationId/messages/stream - Stream Agent Message
- Request
- Response
POST /api/v1/agent/:agentKey/conversations/:conversationId/messages/streamGET /agent/:agentKey/conversations - Get All Agent Conversations
GET /agent/:agentKey/conversations - Get All Agent Conversations
- Request
- Response
GET /api/v1/agent/:agentKey/conversationsQuery Parameters: Same as regular conversationsGET /agent/:agentKey/conversations/:conversationId - Get Agent Conversation
GET /agent/:agentKey/conversations/:conversationId - Get Agent Conversation
- Request
- Response
GET /api/v1/agent/:agentKey/conversations/:conversationIdDELETE /agent/:agentKey/conversations/:conversationId - Delete Agent Conversation
DELETE /agent/:agentKey/conversations/:conversationId - Delete Agent Conversation
- Request
- Response
DELETE /api/v1/agent/:agentKey/conversations/:conversationIdAgent Management
Agent Management
POST /agent/template - Create Agent Template
POST /agent/template - Create Agent Template
- Request
- Response
POST /api/v1/agent/templateGET /agent/template/:templateId - Get Agent Template
GET /agent/template/:templateId - Get Agent Template
- Request
- Response
GET /api/v1/agent/template/:templateIdPUT /agent/template/:templateId - Update Agent Template
PUT /agent/template/:templateId - Update Agent Template
- Request
- Response
PUT /api/v1/agent/template/:templateIdRequest Body: Same structure as create templateDELETE /agent/template/:templateId - Delete Agent Template
DELETE /agent/template/:templateId - Delete Agent Template
- Request
- Response
DELETE /api/v1/agent/template/:templateIdGET /agent/template - List Agent Templates
GET /agent/template - List Agent Templates
- Request
- Response
GET /api/v1/agent/templatePOST /agent/create - Create Agent
POST /agent/create - Create Agent
- Request
- Response
POST /api/v1/agent/createGET /agent/:agentKey - Get Agent
GET /agent/:agentKey - Get Agent
- Request
- Response
GET /api/v1/agent/:agentKeyPUT /agent/:agentKey - Update Agent
PUT /agent/:agentKey - Update Agent
- Request
- Response
PUT /api/v1/agent/:agentKeyRequest Body: Agent configuration updatesDELETE /agent/:agentKey - Delete Agent
DELETE /agent/:agentKey - Delete Agent
- Request
- Response
DELETE /api/v1/agent/:agentKeyGET /agent/ - List Agents
GET /agent/ - List Agents
- Request
- Response
GET /api/v1/agent/GET /agent/tools/list - Get Available Tools
GET /agent/tools/list - Get Available Tools
- Request
- Response
GET /api/v1/agent/tools/listGET /agent/:agentKey/permissions - Get Agent Permissions
GET /agent/:agentKey/permissions - Get Agent Permissions
- Request
- Response
GET /api/v1/agent/:agentKey/permissionsPOST /agent/:agentKey/share - Share Agent
POST /agent/:agentKey/share - Share Agent
POST /agent/:agentKey/unshare - Unshare Agent
POST /agent/:agentKey/unshare - Unshare Agent
PUT /agent/:agentKey/permissions - Update Agent Permissions
PUT /agent/:agentKey/permissions - Update Agent Permissions
- Request
- Response
PUT /api/v1/agent/:agentKey/permissionsRequest Body: Updated permission configurationSemantic Search
Semantic Search
POST /search - Search
POST /search - Search
- Request
- Response
POST /api/v1/searchquery: Required, 1+ characterslimit: Optional, 1-100 (default: 10)filters.apps: Array of valid app typesfilters.kb: Array of UUIDs
GET /search - Search History
GET /search - Search History
- Request
- Response
GET /api/v1/searchQuery Parameters:page: Page number (default: 1)limit: Items per page (1-100, default: 10)sortBy: Field to sort by (default: ‘createdAt’)sortOrder: Sort order (default: ‘desc’)
GET /search/:searchId - Get Search By ID
GET /search/:searchId - Get Search By ID
- Request
- Response
GET /api/v1/search/:searchIdDELETE /search/:searchId - Delete Search
DELETE /search/:searchId - Delete Search
- Request
- Response
DELETE /api/v1/search/:searchIdDELETE /search - Delete Search History
DELETE /search - Delete Search History
- Request
- Response
DELETE /api/v1/searchPATCH /search/:searchId/share - Share Search
PATCH /search/:searchId/share - Share Search
PATCH /search/:searchId/unshare - Unshare Search
PATCH /search/:searchId/unshare - Unshare Search
PATCH /search/:searchId/archive - Archive Search
PATCH /search/:searchId/archive - Archive Search
- Request
- Response
PATCH /api/v1/search/:searchId/archivePATCH /search/:searchId/unarchive - Unarchive Search
PATCH /search/:searchId/unarchive - Unarchive Search
- Request
- Response
PATCH /api/v1/search/:searchId/unarchiveConfiguration
Configuration
POST /search/updateAppConfig - Update App Configuration
POST /search/updateAppConfig - Update App Configuration
- Request
- Response
POST /api/v1/search/updateAppConfigAuthentication: Requires scoped token with FETCH_CONFIG scope.Schema Definitions
- Conversation Schema
- Message Schema
- Citation Schema
- Search Schema
- Constants
Error Handling
All endpoints return structured error responses with specific error constants:VALIDATION_ERROR- Invalid request parameters (from validators)NOT_FOUND- Resource not foundUNAUTHORIZED- Authentication requiredFORBIDDEN- Insufficient permissionsINTERNAL_ERROR- Server errorAI_SERVICE_UNAVAILABLE- AI backend unavailableBAD_REQUEST- Malformed request
- Connection refused → “AI Service is currently unavailable. Please check your network connection or try again later.”
- API errors → Conversation marked as ‘Failed’ with specific failure reason
- Processing errors → Error message added to conversation messages
Important Notes
- MongoDB ObjectIds: All ID fields use 24-character hexadecimal strings matching
/^[0-9a-fA-F]{24}$/ - UUIDs vs ObjectIds: Knowledge base filters use UUIDs, not ObjectIds
- Computed Fields: Response objects include computed
isOwnerandaccessLevelfields - Pagination: Conversation messages paginate backwards (newest first)
- Streaming: Custom
completeevents replace AI backend events with conversation data - Agent Conversations: Inherit all conversation features plus agent-specific capabilities
- Access Control: Strict validation of user permissions and resource ownership
- Transaction Support: Uses MongoDB transactions when replica sets are available













