Skip to main content

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:
  1. Conversation Management - Chat-style interactions with your data
  2. Agent Conversations - Specialized conversations with AI agents
  3. Agent Management - Manages AI agents and templates
  4. 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:
Authorization: Bearer YOUR_TOKEN
Internal endpoints use scoped token authentication for service-to-service communication with specific scopes:
  • CONVERSATION_CREATE - For conversation creation
  • FETCH_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

The Conversation Management API enables chat-style interactions with your organizational data, including creating conversations, adding messages, sharing, and managing conversation lifecycle.
Start a new conversation thread.
  • Request
  • Response
Endpoint: POST /api/v1/conversations/createRequest Body Parameters:
ParameterTypeRequiredDescription
querystringYesThe user’s query (1-100,000 characters)
recordIdsstring[]NoMongoDB ObjectIds (24-character hex strings)
departmentsstring[]NoDepartment MongoDB ObjectIds
filtersobjectNoAdditional filters to narrow the search
filters.appsstring[]NoApp types: “drive”, “gmail”, “onedrive”, “sharepointOnline”, “local”
filters.kbstring[]NoKnowledge base UUIDs (not ObjectIds)
modelKeystringNoModel key for multi-model support
modelNamestringNoModel name for multi-model support
chatModestringNoChat mode (default: ‘standard’)
{
  "query": "What is our company's vacation policy?",
  "recordIds": ["60a2b5e3a1b3c4d5e6f7g8h9"], 
  "departments": ["507f1f77bcf86cd799439011"],
  "filters": {
    "apps": ["drive", "gmail"],
    "kb": ["550e8400-e29b-41d4-a716-446655440000"]
  },
  "modelKey": "gpt-4",
  "modelName": "GPT-4",
  "chatMode": "standard"
}
Internal endpoint for service-to-service communication using scoped tokens.
  • Request
  • Response
Endpoint: POST /api/v1/conversations/internal/createAuthentication: Requires scoped token with CONVERSATION_CREATE scope.Request Body: Same structure as public create endpoint.
Create a conversation with real-time streaming responses via Server-Sent Events.
  • Request
  • Response
Endpoint: POST /api/v1/conversations/streamRequest Body: Same as Create Conversation
const streamChat = async () => {
  const response = await fetch('/api/v1/conversations/stream', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_TOKEN'
    },
    body: JSON.stringify({
      query: "What is our vacation policy?",
      filters: { apps: ["drive"] }
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    const events = chunk.split('\n\n');
    
    for (const event of events) {
      if (event.startsWith('event: connected')) {
        console.log('Connection established');
      } else if (event.startsWith('event: complete')) {
        const data = JSON.parse(event.split('data: ')[1]);
        console.log('Final conversation:', data.conversation);
      } else if (event.startsWith('event: error')) {
        const error = JSON.parse(event.split('data: ')[1]);
        console.error('Stream error:', error);
      }
    }
  }
};
Add a new message to an existing conversation.
  • Request
  • Response
Endpoint: POST /api/v1/conversations/:conversationId/messagesPath Parameters:
  • conversationId: MongoDB ObjectId (24-character hex string)
Request Body Parameters:
ParameterTypeRequiredDescription
querystringYesThe user’s follow-up question (1-100,000 characters)
filtersobjectNoAdditional filters
filters.appsstring[]NoApp types: “drive”, “gmail”, “onedrive”, “sharepointOnline”, “local”
filters.kbstring[]NoKnowledge base UUIDs
modelKeystringNoModel key for multi-model support
modelNamestringNoModel name for multi-model support
chatModestringNoChat mode
Note: previousConversations is automatically calculated from existing messages - do NOT include in request.
{
  "query": "How much notice should I give before taking vacation?",
  "filters": { 
    "apps": ["drive"],
    "kb": ["kb-uuid-123"] 
  },
  "modelKey": "gpt-4"
}
Internal endpoint for adding messages via service authentication.
  • Request
  • Response
Endpoint: POST /api/v1/conversations/internal/:conversationId/messagesAuthentication: Requires scoped token with CONVERSATION_CREATE scope.Request Body: Same structure as public add message endpoint.
Add a message with real-time streaming response.
  • Request
  • Response
Endpoint: POST /api/v1/conversations/:conversationId/messages/streamRequest Body: Same as Add Message (without previousConversations)Behavior:
  1. Adds user message to existing conversation
  2. Streams AI response in real-time
  3. Sends custom complete event with updated conversation
Retrieve all conversations for the authenticated user with pagination.
  • Request
  • Response
Endpoint: GET /api/v1/conversationsQuery Parameters:
ParameterTypeDefaultDescription
pagenumber1Page number for pagination
limitnumber20Items per page (1-100)
sortBystringlastActivityAtField to sort by (createdAt, lastActivityAt, title)
sortOrderstringdescSort order (asc, desc)
searchstring-Search term for filtering
startDatestring-Filter by start date (ISO format)
endDatestring-Filter by end date (ISO format)
sharedboolean-Filter by shared status
conversationIdstring-Filter by specific conversation ID
Retrieve a specific conversation with paginated messages.
  • Request
  • Response
Endpoint: 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 pagination
  • limit: Messages per page
Important: Message pagination works backwards - newer messages have higher indices. The API returns the most recent messages first and paginates backwards through older messages.
Soft delete a conversation and its associated citations.
  • Request
  • Response
Endpoint: DELETE /api/v1/conversations/:conversationIdAccess Control: Only conversation initiator or users with ‘write’ access can delete.
Share a conversation with other users in your organization.
  • Request
  • Response
Endpoint: POST /api/v1/conversations/:conversationId/shareAccess Control: Only conversation initiator can share.
{
  "userIds": ["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012"],
  "accessLevel": "read"
}
Request Validation:
  • userIds: Array of MongoDB ObjectIds (24-character hex strings)
  • accessLevel: “read” or “write” (optional, defaults to “read”)
  • User existence is validated against IAM service
Remove sharing access for specific users.
  • Request
  • Response
Endpoint: POST /api/v1/conversations/:conversationId/unshare
{
  "userIds": ["507f1f77bcf86cd799439011"]
}
Regenerate the last AI response in a conversation.
  • Request
  • Response
Endpoint: 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)
Update the title of a conversation.
  • Request
  • Response
Endpoint: PATCH /api/v1/conversations/:conversationId/title
{
  "title": "Updated Vacation Policy Discussion"
}
Validation:
  • title: Required, 1-200 characters
Provide feedback on an AI response.
  • Request
  • Response
Endpoint: 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.
{
  "isHelpful": true,
  "ratings": {
    "accuracy": 5,
    "relevance": 4, 
    "completeness": 5,
    "clarity": 5
  },
  "categories": [
    "excellent_answer", 
    "helpful_citations"
  ],
  "comments": {
    "positive": "This was very helpful and accurate",
    "negative": "",
    "suggestions": "Could have included more recent policy updates"
  },
  "citationFeedback": [
    {
      "citationId": "citation123",
      "isRelevant": true,
      "relevanceScore": 5,
      "comment": "Perfect reference"
    }
  ],
  "followUpQuestionsHelpful": true,
  "unusedFollowUpQuestions": [],
  "metrics": {
    "userInteractionTime": 30000,
    "feedbackSessionId": "session-abc"
  }
}
Categories:
  • incorrect_information, missing_information, irrelevant_information
  • unclear_explanation, poor_citations
  • excellent_answer, helpful_citations, well_explained, other
Archive a conversation.
  • Request
  • Response
Endpoint: PATCH /api/v1/conversations/:conversationId/archiveAccess Control: Conversation initiator or users with ‘write’ access.
Unarchive a conversation.
  • Request
  • Response
Endpoint: PATCH /api/v1/conversations/:conversationId/unarchive
Get all archived conversations with summary statistics.
  • Request
  • Response
Endpoint: GET /api/v1/conversations/show/archivesQuery Parameters: Same pagination and filtering as Get All Conversations
The Agent Conversation API enables interactions with specific AI agents. Agent conversations inherit all conversation properties but include additional agent-specific features.
Start a conversation with a specific agent.
  • Request
  • Response
Endpoint: POST /api/v1/agent/:agentKey/conversationsPath Parameters:
  • agentKey: Unique string identifier for the agent (from ArangoDB)
Request Body Parameters:
ParameterTypeRequiredDescription
querystringYesThe user’s query (1-100,000 characters)
quickModebooleanNoEnable quick response mode
toolsstring[]NoAvailable tools for the agent
recordIdsstring[]NoMongoDB ObjectIds to search within
filtersobjectNoAdditional filters
modelKeystringNoModel key override
modelNamestringNoModel name override
chatModestringNoChat mode (default: ‘standard’)
{
  "query": "What can you help me with?",
  "quickMode": false,
  "tools": ["search", "calculator", "ticket_lookup"],
  "filters": {
    "apps": ["drive", "gmail"]
  }
}
Create an agent conversation with streaming responses.
  • Request
  • Response
Endpoint: POST /api/v1/agent/:agentKey/conversations/streamRequest Body: Same as Create Agent Conversation
const streamAgentConversation = async (agentKey) => {
  const response = await fetch(`/api/v1/agent/${agentKey}/conversations/stream`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_TOKEN'
    },
    body: JSON.stringify({
      query: "Help me troubleshoot a customer issue",
      quickMode: true,
      tools: ["search", "ticket_lookup", "knowledge_base"]
    })
  });

  // Handle SSE stream same as regular conversations
  const reader = response.body.getReader();
  // ... stream processing code
};
Add a message to an existing agent conversation.
  • Request
  • Response
Endpoint: POST /api/v1/agent/:agentKey/conversations/:conversationId/messagesRequest Body: Same structure as regular add message, without previousConversations (calculated automatically)
{
  "query": "Can you look up ticket #12345?",
  "filters": {
    "apps": ["jira"]
  }
}
Add a streaming message to an agent conversation.
  • Request
  • Response
Endpoint: POST /api/v1/agent/:agentKey/conversations/:conversationId/messages/stream
Retrieve all conversations for a specific agent.
  • Request
  • Response
Endpoint: GET /api/v1/agent/:agentKey/conversationsQuery Parameters: Same as regular conversations
Retrieve a specific agent conversation.
  • Request
  • Response
Endpoint: GET /api/v1/agent/:agentKey/conversations/:conversationId
Delete an agent conversation.
  • Request
  • Response
Endpoint: DELETE /api/v1/agent/:agentKey/conversations/:conversationId
The Agent Management API provides endpoints for creating, managing, and configuring AI agents and their templates.
Create a new agent template.
  • Request
  • Response
Endpoint: POST /api/v1/agent/template
{
  "name": "Customer Support Agent",
  "description": "Handles customer support queries",
  "instructions": "You are a helpful customer support agent...",
  "tools": ["search", "ticket_lookup"],
  "model": "gpt-4",
  "capabilities": ["reasoning", "search"],
  "constraints": {
    "maxTokens": 4000,
    "temperature": 0.7
  }
}
Retrieve a specific agent template.
  • Request
  • Response
Endpoint: GET /api/v1/agent/template/:templateId
Update an existing agent template.
  • Request
  • Response
Endpoint: PUT /api/v1/agent/template/:templateIdRequest Body: Same structure as create template
Delete an agent template.
  • Request
  • Response
Endpoint: DELETE /api/v1/agent/template/:templateId
Get all available agent templates.
  • Request
  • Response
Endpoint: GET /api/v1/agent/template
Create a new agent instance from a template.
  • Request
  • Response
Endpoint: POST /api/v1/agent/create
{
  "templateId": "template123",
  "name": "My Support Agent",
  "customInstructions": "Focus on billing issues",
  "tools": ["search", "billing_lookup"]
}
Retrieve agent details.
  • Request
  • Response
Endpoint: GET /api/v1/agent/:agentKey
Update agent configuration.
  • Request
  • Response
Endpoint: PUT /api/v1/agent/:agentKeyRequest Body: Agent configuration updates
Delete an agent.
  • Request
  • Response
Endpoint: DELETE /api/v1/agent/:agentKey
Get all available agents for the organization.
  • Request
  • Response
Endpoint: GET /api/v1/agent/
Retrieve all available tools for agents.
  • Request
  • Response
Endpoint: GET /api/v1/agent/tools/list
Get permissions for a specific agent.
  • Request
  • Response
Endpoint: GET /api/v1/agent/:agentKey/permissions
Share an agent with other users.
  • Request
  • Response
Endpoint: POST /api/v1/agent/:agentKey/share
{
  "userIds": ["user789"],
  "accessLevel": "read"
}
Remove agent sharing.
  • Request
  • Response
Endpoint: POST /api/v1/agent/:agentKey/unshare
{
  "userIds": ["user789"]
}
Update agent permissions.
  • Request
  • Response
Endpoint: PUT /api/v1/agent/:agentKey/permissionsRequest Body: Updated permission configuration
Internal configuration management endpoints for service administration.
Internal endpoint for updating application configuration.
  • Request
  • Response
Endpoint: POST /api/v1/search/updateAppConfigAuthentication: Requires scoped token with FETCH_CONFIG scope.

Schema Definitions

  • Conversation Schema
  • Message Schema
  • Citation Schema
  • Search Schema
  • Constants
interface IConversation {
  // Identifiers
  userId: Types.ObjectId;
  orgId: Types.ObjectId;
  initiator: Types.ObjectId;
  
  // Content
  title?: string;
  messages: IMessageDocument[];
  
  // Sharing
  isShared?: boolean;
  shareLink?: string;
  sharedWith?: Array<{
    userId: Types.ObjectId;
    accessLevel: 'read' | 'write';
  }>;
  
  // State
  isDeleted?: boolean;
  deletedBy?: Types.ObjectId;
  isArchived?: boolean;
  archivedBy?: Types.ObjectId;
  lastActivityAt?: Number; // Unix timestamp
  status?: 'None' | 'Inprogress' | 'Complete' | 'Failed';
  failReason?: String;
  
  // Metadata
  tags?: Types.ObjectId[];
  conversationSource: 'enterprise_search' | 'records' | 'connectors' | 'internet_search' | 'personal_kb_search' | 'agent';
  conversationSourceRecordId?: Types.ObjectId;
  conversationSourceConnectorIds?: Types.ObjectId[];
  conversationSourceRecordType?: string;
  
  // Timestamps
  createdAt?: Date;
  updatedAt?: Date;
}

interface IAgentConversation extends IConversation {
  agentKey: string; // Reference to agent _key in ArangoDB
  conversationSource: 'agent_chat';
}

Error Handling

All endpoints return structured error responses with specific error constants:
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "query",
      "issue": "Query is required and must be between 1-100000 characters"
    }
  },
  "meta": {
    "requestId": "req-error-123",
    "timestamp": "2025-04-27T13:20:00.000Z"
  }
}
Common Error Codes:
  • VALIDATION_ERROR - Invalid request parameters (from validators)
  • NOT_FOUND - Resource not found
  • UNAUTHORIZED - Authentication required
  • FORBIDDEN - Insufficient permissions
  • INTERNAL_ERROR - Server error
  • AI_SERVICE_UNAVAILABLE - AI backend unavailable
  • BAD_REQUEST - Malformed request
AI Service Specific Errors:
  • 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

  1. MongoDB ObjectIds: All ID fields use 24-character hexadecimal strings matching /^[0-9a-fA-F]{24}$/
  2. UUIDs vs ObjectIds: Knowledge base filters use UUIDs, not ObjectIds
  3. Computed Fields: Response objects include computed isOwner and accessLevel fields
  4. Pagination: Conversation messages paginate backwards (newest first)
  5. Streaming: Custom complete events replace AI backend events with conversation data
  6. Agent Conversations: Inherit all conversation features plus agent-specific capabilities
  7. Access Control: Strict validation of user permissions and resource ownership
  8. Transaction Support: Uses MongoDB transactions when replica sets are available
I