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:

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

Conversation Management

The Conversation Management API enables chat-style interactions with your organizational data, including creating conversations, adding messages, sharing, and managing conversation lifecycle.

POST /conversations/create - Create Conversation

Start a new conversation thread.

Request
Response

Endpoint: 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’)

{
  "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"
}

Status: 201 Created

{
  "conversation": {
    "_id": "60d21b4667d0d8992e610c85",
    "title": "What is our company's vacation policy?",
    "messages": [
      {
        "_id": "msg1",
        "messageType": "user_query",
        "content": "What is our company's vacation policy?",
        "contentFormat": "MARKDOWN",
        "createdAt": "2025-04-27T12:00:00.000Z",
        "updatedAt": "2025-04-27T12:00:00.000Z"
      },
      {
        "_id": "msg2",
        "messageType": "bot_response",
        "content": "Our company provides 20 days of paid vacation...",
        "contentFormat": "MARKDOWN",
        "citations": [
          {
            "citationId": "citation123",
            "citationData": {
              "_id": "citation123",
              "content": "Employees are entitled to 20 days...",
              "chunkIndex": 4,
              "citationType": "document",
              "metadata": {
                "recordName": "Employee Handbook.pdf",
                "recordId": "doc123",
                "pageNum": [15],
                "mimeType": "application/pdf",
                "orgId": "org123",
                "origin": "google_drive",
                "webUrl": "https://drive.google.com/file/d/doc123",
                "score": 0.95
              }
            }
          }
        ],
        "confidence": "High",
        "followUpQuestions": [
          {
            "question": "How do I request vacation time?",
            "confidence": "Medium",
            "reasoning": "Related to vacation policy procedures"
          }
        ],
        "metadata": {
          "processingTimeMs": 1200,
          "modelVersion": "gpt-4-turbo",
          "aiTransactionId": "txn-abc123"
        },
        "createdAt": "2025-04-27T12:00:05.000Z",
        "updatedAt": "2025-04-27T12:00:05.000Z"
      }
    ],
    "status": "Complete",
    "orgId": "org123",
    "userId": "user456",
    "initiator": "user456",
    "isShared": false,
    "isDeleted": false,
    "isArchived": false,
    "lastActivityAt": 1714204805000,
    "conversationSource": "enterprise_search",
    "createdAt": "2025-04-27T12:00:00.000Z",
    "updatedAt": "2025-04-27T12:00:05.000Z",
    "isOwner": true,
    "accessLevel": "write"
  },
  "meta": {
    "requestId": "req-123",
    "timestamp": "2025-04-27T12:00:05.000Z",
    "duration": 1200
  }
}

POST /conversations/internal/create - Internal Create

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.

Status: 201 CreatedSame response structure as public create endpoint.

POST /conversations/stream - Stream Chat

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);
      }
    }
  }
};

Response: Server-Sent Events (SSE) streamSSE Events:

connected: Initial connection established
content: Streaming content chunks from AI backend
complete: Custom event containing final conversation data (replaces AI backend’s complete event)
error: Error occurred during processing

Important: The API intercepts the AI backend’s complete event and replaces it with its own format containing the saved conversation data.

POST /conversations/:conversationId/messages - Add Message

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:

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

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"
}

Status: 200 OK

{
  "conversation": {
    "_id": "60d21b4667d0d8992e610c85",
    "messages": [
      {
        "_id": "newMsgId1",
        "messageType": "user_query",
        "content": "How much notice should I give before taking vacation?",
        "createdAt": "2025-04-27T12:05:00.000Z"
      },
      {
        "_id": "newMsgId2", 
        "messageType": "bot_response",
        "content": "You should provide at least 2 weeks notice...",
        "citations": [
          {
            "citationId": "citation456",
            "citationData": {
              "content": "Vacation requests must be submitted...",
              "metadata": {
                "recordName": "HR Policy.pdf",
                "pageNum": [8]
              }
            }
          }
        ],
        "confidence": "High",
        "createdAt": "2025-04-27T12:05:02.000Z"
      }
    ],
    "lastActivityAt": 1714204302000,
    "status": "Complete",
    "isOwner": true,
    "accessLevel": "write"
  },
  "recordsUsed": 3,
  "meta": {
    "requestId": "req-456",
    "timestamp": "2025-04-27T12:05:02.000Z",
    "duration": 950,
    "recordsUsed": 3
  }
}

POST /conversations/internal/:conversationId/messages - Internal Add Message

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.

POST /conversations/:conversationId/messages/stream - Stream Message

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:

Adds user message to existing conversation
Streams AI response in real-time
Sends custom complete event with updated conversation

GET /conversations - Get All Conversations

Retrieve all conversations for the authenticated user with pagination.

Request
Response

Endpoint: 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

Status: 200 OK

{
  "conversations": [
    {
      "_id": "60d21b4667d0d8992e610c85",
      "title": "Vacation Policy Discussion",
      "initiator": "user456",
      "orgId": "org123",
      "userId": "user456", 
      "createdAt": "2025-04-20T15:30:00.000Z",
      "updatedAt": "2025-04-25T10:15:00.000Z",
      "lastActivityAt": 1714204800000,
      "isShared": true,
      "isDeleted": false,
      "isArchived": false,
      "status": "Complete",
      "conversationSource": "enterprise_search",
      "isOwner": true,
      "accessLevel": "write"
    }
  ],
  "sharedWithMeConversations": [
    {
      "_id": "60d21b4667d0d8992e610c86",
      "title": "HR Policies", 
      "initiator": "user789",
      "isShared": true,
      "isOwner": false,
      "accessLevel": "read"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPrevPage": false
  },
  "filters": {
    "applied": {
      "filters": ["search", "shared", "dateRange"],
      "values": {
        "search": "vacation",
        "shared": "true",
        "dateRange": {
          "start": "2025-01-01T00:00:00.000Z",
          "end": "2025-04-27T23:59:59.999Z"
        }
      }
    },
    "available": {
      "shared": {
        "values": ["true", "false"],
        "description": "Filter by shared status"
      },
      "search": {
        "type": "string",
        "description": "Search in conversation title and messages"
      }
    }
  },
  "meta": {
    "requestId": "req-789",
    "timestamp": "2025-04-27T12:10:00.000Z",
    "duration": 350
  }
}

GET /conversations/:conversationId - Get Conversation By 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.

Status: 200 OK

{
  "conversation": {
    "id": "60d21b4667d0d8992e610c85",
    "title": "Vacation Policy Discussion",
    "initiator": "user456",
    "status": "Complete",
    "failReason": null,
    "isShared": true,
    "sharedWith": [
      {
        "userId": "user789",
        "accessLevel": "read"
      }
    ],
    "messages": [
      {
        "_id": "msg1",
        "messageType": "user_query",
        "content": "What is our vacation policy?",
        "contentFormat": "MARKDOWN",
        "createdAt": "2025-04-27T12:00:00.000Z",
        "citations": []
      },
      {
        "_id": "msg2", 
        "messageType": "bot_response",
        "content": "Our company provides...",
        "citations": [
          {
            "citationId": "citation123",
            "citationData": {
              "_id": "citation123",
              "content": "Policy text...",
              "metadata": {
                "recordName": "Handbook.pdf"
              }
            }
          }
        ],
        "confidence": "High",
        "followUpQuestions": [
          {
            "question": "How do I request time off?",
            "confidence": "Medium"
          }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "totalCount": 5,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPrevPage": false,
      "messageRange": {
        "start": 1,
        "end": 5
      }
    },
    "access": {
      "isOwner": true,
      "accessLevel": "write"
    }
  },
  "meta": {
    "requestId": "req-abc",
    "timestamp": "2025-04-27T12:15:00.000Z",
    "duration": 180,
    "conversationId": "60d21b4667d0d8992e610c85",
    "messageCount": 5
  }
}

DELETE /conversations/:conversationId - Delete Conversation

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.

Status: 200 OK

{
  "id": "60d21b4667d0d8992e610c85",
  "status": "deleted",
  "deletedAt": "2025-04-27T12:20:00.000Z",
  "deletedBy": "user456",
  "citationsDeleted": 12,
  "meta": {
    "requestId": "req-def",
    "timestamp": "2025-04-27T12:20:00.000Z",
    "duration": 230
  }
}

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

Status: 200 OK

{
  "id": "60d21b4667d0d8992e610c85",
  "isShared": true,
  "shareLink": "https://app.example.com/conversations/60d21b4667d0d8992e610c85",
  "sharedWith": [
    {
      "userId": "507f1f77bcf86cd799439011",
      "accessLevel": "read"
    },
    {
      "userId": "507f1f77bcf86cd799439012", 
      "accessLevel": "read"
    }
  ],
  "meta": {
    "requestId": "req-ghi",
    "timestamp": "2025-04-27T12:25:00.000Z",
    "duration": 180
  }
}

POST /conversations/:conversationId/unshare - Unshare Conversation

Remove sharing access for specific users.

Request
Response

Endpoint: POST /api/v1/conversations/:conversationId/unshare

{
  "userIds": ["507f1f77bcf86cd799439011"]
}

Status: 200 OK

{
  "id": "60d21b4667d0d8992e610c85",
  "isShared": true,
  "shareLink": "https://app.example.com/conversations/60d21b4667d0d8992e610c85",
  "sharedWith": [
    {
      "userId": "507f1f77bcf86cd799439012",
      "accessLevel": "read"
    }
  ],
  "unsharedUsers": ["507f1f77bcf86cd799439011"],
  "meta": {
    "requestId": "req-jkl",
    "timestamp": "2025-04-27T12:30:00.000Z",
    "duration": 150
  }
}

Note: If no users remain in sharedWith, isShared becomes false and shareLink is removed.

POST /conversations/:conversationId/message/:messageId/regenerate - Regenerate Answer

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)

Status: 200 OK

{
  "conversation": {
    "id": "60d21b4667d0d8992e610c85",
    "messages": [
      {
        "_id": "msg2",
        "messageType": "bot_response", 
        "content": "Here is a new response with updated information...",
        "citations": [
          {
            "citationId": "citation456",
            "citationData": {
              "content": "Updated policy text...",
              "metadata": {
                "recordName": "Updated Handbook.pdf",
                "score": 0.88
              }
            }
          }
        ],
        "confidence": "High",
        "followUpQuestions": [
          {
            "question": "What about remote work policies?",
            "confidence": "Medium"
          }
        ]
      }
    ]
  },
  "meta": {
    "requestId": "req-mno",
    "timestamp": "2025-04-27T12:35:00.000Z",
    "duration": 1100
  }
}

PATCH /conversations/:conversationId/title - Update Title

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

Status: 200 OK

{
  "conversation": {
    "_id": "60d21b4667d0d8992e610c85",
    "title": "Updated Vacation Policy Discussion",
    "messages": [...],
    "createdAt": "2025-04-27T12:00:00.000Z",
    "updatedAt": "2025-04-27T12:40:00.000Z"
  },
  "meta": {
    "requestId": "req-pqr",
    "timestamp": "2025-04-27T12:40:00.000Z",
    "duration": 85
  }
}

POST /conversations/:conversationId/message/:messageId/feedback - Add Feedback

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

Status: 200 OK

{
  "conversationId": "60d21b4667d0d8992e610c85",
  "messageId": "msg2",
  "feedback": {
    "isHelpful": true,
    "ratings": {
      "accuracy": 5,
      "relevance": 4,
      "completeness": 5,
      "clarity": 5
    },
    "categories": ["excellent_answer", "helpful_citations"],
    "comments": {
      "positive": "This was very helpful and accurate",
      "suggestions": "Could have included more recent policy updates"
    },
    "source": "user",
    "feedbackProvider": "user456",
    "timestamp": 1714204800000,
    "metrics": {
      "timeToFeedback": 45000,
      "userInteractionTime": 30000,
      "feedbackSessionId": "session-abc",
      "userAgent": "Mozilla/5.0..."
    }
  },
  "meta": {
    "requestId": "req-stu",
    "timestamp": "2025-04-27T12:45:00.000Z",
    "duration": 120
  }
}

PATCH /conversations/:conversationId/archive - Archive Conversation

Archive a conversation.

Request
Response

Endpoint: PATCH /api/v1/conversations/:conversationId/archiveAccess Control: Conversation initiator or users with ‘write’ access.

Status: 200 OK

{
  "id": "60d21b4667d0d8992e610c85",
  "status": "archived",
  "archivedBy": "user456",
  "archivedAt": "2025-04-27T12:50:00.000Z",
  "meta": {
    "requestId": "req-vwx",
    "timestamp": "2025-04-27T12:50:00.000Z",
    "duration": 90
  }
}

PATCH /conversations/:conversationId/unarchive - Unarchive Conversation

Unarchive a conversation.

Request
Response

Endpoint: PATCH /api/v1/conversations/:conversationId/unarchive

Status: 200 OK

{
  "id": "60d21b4667d0d8992e610c85",
  "status": "unarchived",
  "unarchivedBy": "user456", 
  "unarchivedAt": "2025-04-27T12:55:00.000Z",
  "meta": {
    "requestId": "req-yz1",
    "timestamp": "2025-04-27T12:55:00.000Z",
    "duration": 95
  }
}

GET /conversations/show/archives - List Archived Conversations

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

Status: 200 OK

{
  "conversations": [
    {
      "_id": "archived1",
      "title": "Old Discussion",
      "status": "Complete",
      "isArchived": true,
      "archivedAt": "2025-04-20T10:00:00.000Z",
      "archivedBy": "user456",
      "isOwner": true,
      "accessLevel": "write"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 5,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  },
  "summary": {
    "totalArchived": 5,
    "oldestArchive": "2025-01-15T10:30:00.000Z",
    "newestArchive": "2025-04-20T15:45:00.000Z"
  },
  "meta": {
    "requestId": "req-234",
    "timestamp": "2025-04-27T13:00:00.000Z",
    "duration": 200
  }
}

Agent Conversations

The Agent Conversation API enables interactions with specific AI agents. Agent conversations inherit all conversation properties but include additional agent-specific features.

POST /agent/:agentKey/conversations - Create Agent Conversation

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:

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’)

{
  "query": "What can you help me with?",
  "quickMode": false,
  "tools": ["search", "calculator", "ticket_lookup"],
  "filters": {
    "apps": ["drive", "gmail"]
  }
}

Status: 201 CreatedSame structure as regular conversation but includes:

{
  "conversation": {
    "_id": "agent_conv_1",
    "agentKey": "support-agent",
    "conversationSource": "agent_chat",
    // ... all other conversation fields
  }
}

POST /agent/:agentKey/conversations/stream - Stream Agent Conversation

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
};

POST /agent/:agentKey/conversations/:conversationId/messages - Add Agent Message

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"]
  }
}

POST /agent/:agentKey/conversations/:conversationId/messages/stream - Stream Agent Message

Add a streaming message to an agent conversation.

Request
Response

Endpoint: POST /api/v1/agent/:agentKey/conversations/:conversationId/messages/stream

GET /agent/:agentKey/conversations - Get All Agent Conversations

Retrieve all conversations for a specific agent.

Request
Response

Endpoint: GET /api/v1/agent/:agentKey/conversationsQuery Parameters: Same as regular conversations

Status: 200 OK

{
  "conversations": [
    {
      "_id": "agent_conv_1",
      "agentKey": "support-agent",
      "title": "Customer Support Query",
      "status": "Complete",
      "conversationSource": "agent_chat",
      "isOwner": true,
      "accessLevel": "write"
    }
  ],
  "sharedWithMeConversations": [...],
  "pagination": {...},
  "meta": {...}
}

GET /agent/:agentKey/conversations/:conversationId - Get Agent Conversation

Retrieve a specific agent conversation.

Request
Response

Endpoint: GET /api/v1/agent/:agentKey/conversations/:conversationId

DELETE /agent/:agentKey/conversations/:conversationId - Delete Agent Conversation

Delete an agent conversation.

Request
Response

Endpoint: DELETE /api/v1/agent/:agentKey/conversations/:conversationId

Status: 200 OK

{
  "message": "Conversation deleted successfully",
  "conversation": {
    "_id": "agent_conv_1",
    "agentKey": "support-agent",
    "isDeleted": true,
    "deletedBy": "user456",
    "lastActivityAt": 1714204800000
  }
}

Agent Management

The Agent Management API provides endpoints for creating, managing, and configuring AI agents and their templates.

POST /agent/template - Create Agent Template

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
  }
}

Status: 201 CreatedResponse: Created template object

GET /agent/template/:templateId - Get Agent Template

Retrieve a specific agent template.

Request
Response

Endpoint: GET /api/v1/agent/template/:templateId

Status: 200 OKResponse: Template object with all configuration details

PUT /agent/template/:templateId - Update Agent Template

Update an existing agent template.

Request
Response

Endpoint: PUT /api/v1/agent/template/:templateIdRequest Body: Same structure as create template

Status: 200 OKResponse: Updated template object

DELETE /agent/template/:templateId - Delete Agent Template

Delete an agent template.

Request
Response

Endpoint: DELETE /api/v1/agent/template/:templateId

Status: 200 OKResponse: Deletion confirmation

GET /agent/template - List Agent Templates

Get all available agent templates.

Request
Response

Endpoint: GET /api/v1/agent/template

Status: 200 OKResponse: Array of template objects

POST /agent/create - Create Agent

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"]
}

Status: 201 CreatedResponse: Created agent object

GET /agent/:agentKey - Get Agent

Retrieve agent details.

Request
Response

Endpoint: GET /api/v1/agent/:agentKey

Status: 200 OKResponse: Complete agent configuration and metadata

PUT /agent/:agentKey - Update Agent

Update agent configuration.

Request
Response

Endpoint: PUT /api/v1/agent/:agentKeyRequest Body: Agent configuration updates

Status: 200 OKResponse: Updated agent object

DELETE /agent/:agentKey - Delete Agent

Delete an agent.

Request
Response

Endpoint: DELETE /api/v1/agent/:agentKey

Status: 200 OKResponse: Deletion confirmation

GET /agent/ - List Agents

Get all available agents for the organization.

Request
Response

Endpoint: GET /api/v1/agent/

Status: 200 OKResponse: Array of agent objects with summary information

GET /agent/tools/list - Get Available Tools

Retrieve all available tools for agents.

Request
Response

Endpoint: GET /api/v1/agent/tools/list

Status: 200 OK

{
  "tools": [
    {
      "name": "search",
      "description": "Search organizational knowledge",
      "parameters": {...}
    },
    {
      "name": "calculator",
      "description": "Perform calculations",
      "parameters": {...}
    }
  ]
}

GET /agent/:agentKey/permissions - Get Agent Permissions

Get permissions for a specific agent.

Request
Response

Endpoint: GET /api/v1/agent/:agentKey/permissions

Status: 200 OKResponse: Agent permission configuration

Share an agent with other users.

Request
Response

Endpoint: POST /api/v1/agent/:agentKey/share

{
  "userIds": ["user789"],
  "accessLevel": "read"
}

Status: 200 OKResponse: Updated agent sharing configuration

POST /agent/:agentKey/unshare - Unshare Agent

Remove agent sharing.

Request
Response

Endpoint: POST /api/v1/agent/:agentKey/unshare

{
  "userIds": ["user789"]
}

Status: 200 OKResponse: Updated agent sharing configuration

PUT /agent/:agentKey/permissions - Update Agent Permissions

Update agent permissions.

Request
Response

Endpoint: PUT /api/v1/agent/:agentKey/permissionsRequest Body: Updated permission configuration

Status: 200 OKResponse: Updated permissions

Semantic Search

Direct search functionality across your organization’s content without creating conversations.

POST /search - Search

Perform a semantic search across indexed content.

Request
Response

Endpoint: POST /api/v1/search

{
  "query": "vacation policy approval process",
  "limit": 10,
  "filters": {
    "apps": ["drive", "gmail"],
    "kb": ["550e8400-e29b-41d4-a716-446655440000"]
  },
  "modelKey": "gpt-4",
  "modelName": "GPT-4",
  "chatMode": "search"
}

Validation:

query: Required, 1+ characters
limit: Optional, 1-100 (default: 10)
filters.apps: Array of valid app types
filters.kb: Array of UUIDs

Status: 200 OK

{
  "searchId": "61f30c988a4e2e001b3c7d1a",
  "searchResponse": {
    "searchResults": [
      {
        "_id": "citation123",
        "content": "The vacation policy approval process requires employees to submit requests at least 14 days in advance...",
        "chunkIndex": 4,
        "citationType": "document",
        "metadata": {
          "recordId": "doc123",
          "recordName": "Company Policy Handbook.pdf", 
          "pageNum": [12],
          "blockNum": [1, 2],
          "mimeType": "application/pdf",
          "recordVersion": 1,
          "orgId": "org123",
          "origin": "google_drive",
          "extension": "pdf",
          "webUrl": "https://drive.google.com/file/d/doc123",
          "score": 0.92,
          "categories": "HR",
          "departments": ["Human Resources"],
          "topics": ["vacation", "policy", "approval"]
        },
        "createdAt": "2025-04-26T09:30:00.000Z",
        "updatedAt": "2025-04-26T09:30:00.000Z"
      }
    ],
    "records": {
      "doc123": "{\"_id\":\"doc123\",\"name\":\"Company Policy Handbook.pdf\",\"type\":\"document\",\"created\":\"2024-10-15T09:45:00.000Z\",\"url\":\"https://drive.google.com/file/d/doc123\"}"
    }
  }
}

GET /search - Search History

Get search history with pagination.

Request
Response

Endpoint: 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’)

Status: 200 OK

{
  "searchHistory": [
    {
      "_id": "search1",
      "query": "vacation policy approval process",
      "limit": 10,
      "orgId": "org123",
      "userId": "user456",
      "isShared": false,
      "isArchived": false,
      "createdAt": "2025-04-27T10:00:00.000Z",
      "updatedAt": "2025-04-27T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalCount": 25,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPrevPage": false
  },
  "filters": {...},
  "meta": {
    "requestId": "req-567",
    "timestamp": "2025-04-27T13:05:00.000Z",
    "duration": 150
  }
}

GET /search/:searchId - Get Search By ID

Retrieve a specific search result with populated citations.

Request
Response

Endpoint: GET /api/v1/search/:searchId

Status: 200 OK

[
  {
    "_id": "61f30c988a4e2e001b3c7d1a",
    "query": "vacation policy approval process",
    "limit": 10,
    "orgId": "org123",
    "userId": "user456",
    "citationIds": [
      {
        "_id": "citation123",
        "content": "The vacation policy...",
        "chunkIndex": 4,
        "citationType": "document",
        "metadata": {
          "recordName": "Policy Handbook.pdf",
          "recordId": "doc123",
          "webUrl": "https://drive.google.com/file/d/doc123"
        },
        "createdAt": "2025-04-27T10:00:00.000Z"
      }
    ],
    "records": {
      "doc123": "{\"name\":\"Policy Handbook.pdf\",\"type\":\"document\"}"
    },
    "isShared": false,
    "isArchived": false,
    "createdAt": "2025-04-27T10:00:00.000Z",
    "updatedAt": "2025-04-27T10:00:00.000Z"
  }
]

DELETE /search/:searchId - Delete Search

Delete a specific search and its associated citations.

Request
Response

Endpoint: DELETE /api/v1/search/:searchId

Status: 200 OK

{
  "message": "Search deleted successfully"
}

DELETE /search - Delete Search History

Delete all search history and associated citations.

Request
Response

Endpoint: DELETE /api/v1/search

Status: 200 OK

{
  "message": "Search history deleted successfully"
}

Share a search result with other users.

Request
Response

Endpoint: PATCH /api/v1/search/:searchId/share

{
  "userIds": ["507f1f77bcf86cd799439011"],
  "accessLevel": "read"
}

Validation:

User existence validated against IAM service
shareLink automatically generated

Status: 200 OK

{
  "_id": "61f30c988a4e2e001b3c7d1a",
  "query": "vacation policy approval process",
  "isShared": true,
  "shareLink": "https://app.example.com/search/61f30c988a4e2e001b3c7d1a",
  "sharedWith": [
    {
      "userId": "507f1f77bcf86cd799439011",
      "accessLevel": "read"
    }
  ],
  "createdAt": "2025-04-27T10:00:00.000Z",
  "updatedAt": "2025-04-27T13:10:00.000Z"
}

PATCH /search/:searchId/unshare - Unshare Search

Remove search sharing.

Request
Response

Endpoint: PATCH /api/v1/search/:searchId/unshare

{
  "userIds": ["507f1f77bcf86cd799439011"]
}

Status: 200 OK

{
  "id": "61f30c988a4e2e001b3c7d1a",
  "isShared": false,
  "shareLink": null,
  "sharedWith": [],
  "unsharedUsers": ["507f1f77bcf86cd799439011"],
  "meta": {
    "requestId": "req-unshare-123",
    "timestamp": "2025-04-27T13:15:00.000Z",
    "duration": 120
  }
}

PATCH /search/:searchId/archive - Archive Search

Archive a search result.

Request
Response

Endpoint: PATCH /api/v1/search/:searchId/archive

Status: 200 OK

{
  "id": "61f30c988a4e2e001b3c7d1a",
  "status": "archived",
  "archivedBy": "user456",
  "archivedAt": "2025-04-27T13:10:00.000Z",
  "meta": {
    "requestId": "req-archive-123",
    "timestamp": "2025-04-27T13:10:00.000Z",
    "duration": 95
  }
}

PATCH /search/:searchId/unarchive - Unarchive Search

Unarchive a search result.

Request
Response

Endpoint: PATCH /api/v1/search/:searchId/unarchive

Status: 200 OK

{
  "id": "61f30c988a4e2e001b3c7d1a",
  "status": "unarchived",
  "unarchivedBy": "user456",
  "unarchivedAt": "2025-04-27T13:15:00.000Z",
  "meta": {
    "requestId": "req-unarchive-123",
    "timestamp": "2025-04-27T13:15:00.000Z",
    "duration": 88
  }
}

Configuration

Internal configuration management endpoints for service administration.

POST /search/updateAppConfig - Update App Configuration

Internal endpoint for updating application configuration.

Request
Response

Endpoint: POST /api/v1/search/updateAppConfigAuthentication: Requires scoped token with FETCH_CONFIG scope.

Status: 200 OK

{
  "message": "User configuration updated successfully",
  "config": {
    "aiBackend": "https://ai.example.com",
    "iamBackend": "https://iam.example.com",
    "frontendUrl": "https://app.example.com",
    "jwtSecret": "[REDACTED]"
  }
}

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';
}

interface IMessage {
  messageType: 'user_query' | 'bot_response' | 'error' | 'feedback' | 'system';
  content: string;
  contentFormat?: 'MARKDOWN' | 'JSON' | 'HTML';
  
  // AI Response Data
  citations?: IMessageCitation[];
  confidence?: 'High' | 'Medium' | 'Low' | 'Very High' | 'Unknown';
  followUpQuestions?: IFollowUpQuestion[];
  
  // User Feedback
  feedback?: IFeedback[];
  
  // Processing Metadata
  metadata?: {
    processingTimeMs?: number;
    modelVersion?: string;
    aiTransactionId?: string;
    reason?: string;
  };
  
  // Timestamps
  createdAt?: Date;
  updatedAt?: Date;
}

interface IFollowUpQuestion {
  question: string;
  confidence: 'High' | 'Medium' | 'Low' | 'Very High' | 'Unknown';
  reasoning?: string;
}

interface IMessageCitation {
  citationId?: Types.ObjectId;
  relevanceScore?: number; // 0-1
  excerpt?: string;
  context?: string;
}

interface ICitation extends Document {
  content: string;
  chunkIndex: number;
  metadata: ICitationMetadata;
  citationType: string;
  createdAt: Date;
  updatedAt: Date;
}

interface ICitationMetadata {
  // Document Structure
  blockNum?: number[];
  pageNum?: number[];
  sheetNum?: number;
  sheetName?: string;
  
  // Classification
  subcategoryLevel1?: string;
  subcategoryLevel2?: string;
  subcategoryLevel3?: string;
  categories?: string;
  departments?: string[];
  topics?: string[];
  languages?: string[];
  
  // Source Information
  connector?: string;
  recordType?: string;
  orgId: string; // Required
  blockType?: string;
  blockText?: string;
  mimeType: string; // Required
  recordId: string; // Required
  chunkIndex: number;
  recordVersion: number;
  recordName: string; // Required
  origin: string; // Required
  extension: string;
  webUrl: string; // Required - URL to access the source
  
  // Positioning (for visual documents)
  bounding_box?: Array<{
    x: number;
    y: number;
  }>;
  
  // Search Relevance
  score?: number;
  
  // System Fields
  _id?: string;
  _collection_name?: string;
}

interface IEnterpriseSemanticSearch extends Document {
  // Query Parameters
  query: string; // Required, indexed
  limit: number; // Required
  
  // Results
  citationIds: mongoose.Types.ObjectId[]; // References to citations
  records: Record<string, any>; // Map of record details (string values)
  
  // Ownership
  orgId: mongoose.Types.ObjectId; // Required, indexed
  userId: mongoose.Types.ObjectId; // Required, indexed
  
  // Sharing
  isShared: boolean; // Default: false
  shareLink: string;
  sharedWith: {
    userId: mongoose.Types.ObjectId;
    accessLevel: 'read' | 'write'; // Default: 'read'
  }[];
  
  // State
  isArchived: boolean; // Default: false
  archivedBy: mongoose.Types.ObjectId;
  
  // Timestamps
  createdAt: Date;
  updatedAt: Date;
}

export const APP_TYPES = {
  DRIVE: 'drive',
  GMAIL: 'gmail', 
  ONEDRIVE: 'onedrive',
  SHAREPOINT_ONLINE: 'sharepointOnline',
  LOCAL: 'local',
} as const;

export type AppType = (typeof APP_TYPES)[keyof typeof APP_TYPES];

export const CONFIDENCE_LEVELS = {
  HIGH: 'High',
  MEDIUM: 'Medium', 
  LOW: 'Low',
  VERY_HIGH: 'Very High',
  UNKNOWN: 'Unknown',
} as const;

export const CONVERSATION_STATUS = {
  COMPLETE: 'Complete',
  FAILED: 'Failed',
  INPROGRESS: 'Inprogress', 
  NONE: 'None',
} as const;

// MongoDB ObjectId validation regex
const objectIdRegex = /^[0-9a-fA-F]{24}$/;

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

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 isOwner and accessLevel fields
Pagination: Conversation messages paginate backwards (newest first)
Streaming: Custom complete events 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

Welcome To PipesHub

System Overview

Authentication

Mail Configuration

AI Providers

Connectors

Integrations

Agents

Toolsets

MCP Server

User Management

Deployment

Developer

Additional Resources

Enterprise search

Enterprise Search API

Base URL

Authentication

Architecture Overview

Data Models

Conversations

Agent Conversations

Citations

Searches

API Endpoints

Schema Definitions

Error Handling

Important Notes

​Enterprise Search API

​Base URL

​Authentication

​Architecture Overview

​Data Models

​Conversations

​Agent Conversations

​Citations

​Searches

​API Endpoints

​Schema Definitions

​Error Handling

​Important Notes

Enterprise Search API

Base URL

Authentication

Architecture Overview

Data Models

Conversations

Agent Conversations

Citations

Searches

API Endpoints

Schema Definitions

Error Handling

Important Notes