> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipeshub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enterprise search

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

```http theme={null}
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

<AccordionGroup>
  <Accordion title="Conversation Management">
    The Conversation Management API enables chat-style interactions with your organizational data, including creating conversations, adding messages, sharing, and managing conversation lifecycle.

    <AccordionGroup>
      <Accordion title="POST /conversations/create - Create Conversation">
        Start a new conversation thread.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/conversations/create`

            **Request 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')                                      |

            ```json theme={null}
            {
              "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"
            }
            ```
          </Tab>

          <Tab title="Response">
            **Status:** `201 Created`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /conversations/internal/create - Internal Create">
        Internal endpoint for service-to-service communication using scoped tokens.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/conversations/internal/create`

            **Authentication:** Requires scoped token with `CONVERSATION_CREATE` scope.

            **Request Body:** Same structure as public create endpoint.
          </Tab>

          <Tab title="Response">
            **Status:** `201 Created`

            Same response structure as public create endpoint.
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /conversations/stream - Stream Chat">
        Create a conversation with real-time streaming responses via Server-Sent Events.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/conversations/stream`

            **Request Body:** Same as Create Conversation

            ```typescript theme={null}
            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);
                  }
                }
              }
            };
            ```
          </Tab>

          <Tab title="Response">
            **Response:** Server-Sent Events (SSE) stream

            **SSE 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.
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /conversations/:conversationId/messages - Add Message">
        Add a new message to an existing conversation.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/conversations/:conversationId/messages`

            **Path 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.

            ```json theme={null}
            {
              "query": "How much notice should I give before taking vacation?",
              "filters": { 
                "apps": ["drive"],
                "kb": ["kb-uuid-123"] 
              },
              "modelKey": "gpt-4"
            }
            ```
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /conversations/internal/:conversationId/messages - Internal Add Message">
        Internal endpoint for adding messages via service authentication.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/conversations/internal/:conversationId/messages`

            **Authentication:** Requires scoped token with `CONVERSATION_CREATE` scope.

            **Request Body:** Same structure as public add message endpoint.
          </Tab>

          <Tab title="Response">
            Same structure as public add message endpoint.
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /conversations/:conversationId/messages/stream - Stream Message">
        Add a message with real-time streaming response.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/conversations/:conversationId/messages/stream`

            **Request 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
          </Tab>

          <Tab title="Response">
            **Response:** SSE stream with same events as Stream Chat
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="GET /conversations - Get All Conversations">
        Retrieve all conversations for the authenticated user with pagination.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `GET /api/v1/conversations`

            **Query 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                  |
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="GET /conversations/:conversationId - Get Conversation By ID">
        Retrieve a specific conversation with paginated messages.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `GET /api/v1/conversations/:conversationId`

            **Query 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.
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="DELETE /conversations/:conversationId - Delete Conversation">
        Soft delete a conversation and its associated citations.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `DELETE /api/v1/conversations/:conversationId`

            **Access Control:** Only conversation initiator or users with 'write' access can delete.
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /conversations/:conversationId/share - Share Conversation">
        Share a conversation with other users in your organization.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/conversations/:conversationId/share`

            **Access Control:** Only conversation initiator can share.

            ```json theme={null}
            {
              "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
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /conversations/:conversationId/unshare - Unshare Conversation">
        Remove sharing access for specific users.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/conversations/:conversationId/unshare`

            ```json theme={null}
            {
              "userIds": ["507f1f77bcf86cd799439011"]
            }
            ```
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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.
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /conversations/:conversationId/message/:messageId/regenerate - Regenerate Answer">
        Regenerate the last AI response in a conversation.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/conversations/:conversationId/message/:messageId/regenerate`

            **Constraints:**

            * 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)
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="PATCH /conversations/:conversationId/title - Update Title">
        Update the title of a conversation.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `PATCH /api/v1/conversations/:conversationId/title`

            ```json theme={null}
            {
              "title": "Updated Vacation Policy Discussion"
            }
            ```

            **Validation:**

            * `title`: Required, 1-200 characters
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /conversations/:conversationId/message/:messageId/feedback - Add Feedback">
        Provide feedback on an AI response.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/conversations/:conversationId/message/:messageId/feedback`

            **Access Control:** Conversation initiator, shared users, or publicly shared conversations.

            **Restriction:** Cannot provide feedback on `user_query` messages.

            ```json theme={null}
            {
              "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`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="PATCH /conversations/:conversationId/archive - Archive Conversation">
        Archive a conversation.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `PATCH /api/v1/conversations/:conversationId/archive`

            **Access Control:** Conversation initiator or users with 'write' access.
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="PATCH /conversations/:conversationId/unarchive - Unarchive Conversation">
        Unarchive a conversation.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `PATCH /api/v1/conversations/:conversationId/unarchive`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="GET /conversations/show/archives - List Archived Conversations">
        Get all archived conversations with summary statistics.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `GET /api/v1/conversations/show/archives`

            **Query Parameters:** Same pagination and filtering as Get All Conversations
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Agent Conversations">
    The Agent Conversation API enables interactions with specific AI agents. Agent conversations inherit all conversation properties but include additional agent-specific features.

    <AccordionGroup>
      <Accordion title="POST /agent/:agentKey/conversations - Create Agent Conversation">
        Start a conversation with a specific agent.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/agent/:agentKey/conversations`

            **Path 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')         |

            ```json theme={null}
            {
              "query": "What can you help me with?",
              "quickMode": false,
              "tools": ["search", "calculator", "ticket_lookup"],
              "filters": {
                "apps": ["drive", "gmail"]
              }
            }
            ```
          </Tab>

          <Tab title="Response">
            **Status:** `201 Created`

            Same structure as regular conversation but includes:

            ```json theme={null}
            {
              "conversation": {
                "_id": "agent_conv_1",
                "agentKey": "support-agent",
                "conversationSource": "agent_chat",
                // ... all other conversation fields
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /agent/:agentKey/conversations/stream - Stream Agent Conversation">
        Create an agent conversation with streaming responses.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/agent/:agentKey/conversations/stream`

            **Request Body:** Same as Create Agent Conversation

            ```typescript theme={null}
            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
            };
            ```
          </Tab>

          <Tab title="Response">
            **Response:** SSE stream with agent-specific events and capabilities

            **SSE Events:** Same as regular conversation streaming
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /agent/:agentKey/conversations/:conversationId/messages - Add Agent Message">
        Add a message to an existing agent conversation.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/agent/:agentKey/conversations/:conversationId/messages`

            **Request Body:** Same structure as regular add message, **without** `previousConversations` (calculated automatically)

            ```json theme={null}
            {
              "query": "Can you look up ticket #12345?",
              "filters": {
                "apps": ["jira"]
              }
            }
            ```
          </Tab>

          <Tab title="Response">
            Same structure as regular add message response.
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /agent/:agentKey/conversations/:conversationId/messages/stream - Stream Agent Message">
        Add a streaming message to an agent conversation.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/agent/:agentKey/conversations/:conversationId/messages/stream`
          </Tab>

          <Tab title="Response">
            **Response:** SSE stream for real-time agent responses with tool usage
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="GET /agent/:agentKey/conversations - Get All Agent Conversations">
        Retrieve all conversations for a specific agent.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `GET /api/v1/agent/:agentKey/conversations`

            **Query Parameters:** Same as regular conversations
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "conversations": [
                {
                  "_id": "agent_conv_1",
                  "agentKey": "support-agent",
                  "title": "Customer Support Query",
                  "status": "Complete",
                  "conversationSource": "agent_chat",
                  "isOwner": true,
                  "accessLevel": "write"
                }
              ],
              "sharedWithMeConversations": [...],
              "pagination": {...},
              "meta": {...}
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="GET /agent/:agentKey/conversations/:conversationId - Get Agent Conversation">
        Retrieve a specific agent conversation.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `GET /api/v1/agent/:agentKey/conversations/:conversationId`
          </Tab>

          <Tab title="Response">
            **Response:** Same structure as regular conversation retrieval
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="DELETE /agent/:agentKey/conversations/:conversationId - Delete Agent Conversation">
        Delete an agent conversation.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `DELETE /api/v1/agent/:agentKey/conversations/:conversationId`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "message": "Conversation deleted successfully",
              "conversation": {
                "_id": "agent_conv_1",
                "agentKey": "support-agent",
                "isDeleted": true,
                "deletedBy": "user456",
                "lastActivityAt": 1714204800000
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Agent Management">
    The Agent Management API provides endpoints for creating, managing, and configuring AI agents and their templates.

    <AccordionGroup>
      <Accordion title="POST /agent/template - Create Agent Template">
        Create a new agent template.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/agent/template`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>

          <Tab title="Response">
            **Status:** `201 Created`

            **Response:** Created template object
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="GET /agent/template/:templateId - Get Agent Template">
        Retrieve a specific agent template.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `GET /api/v1/agent/template/:templateId`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            **Response:** Template object with all configuration details
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="PUT /agent/template/:templateId - Update Agent Template">
        Update an existing agent template.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `PUT /api/v1/agent/template/:templateId`

            **Request Body:** Same structure as create template
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            **Response:** Updated template object
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="DELETE /agent/template/:templateId - Delete Agent Template">
        Delete an agent template.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `DELETE /api/v1/agent/template/:templateId`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            **Response:** Deletion confirmation
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="GET /agent/template - List Agent Templates">
        Get all available agent templates.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `GET /api/v1/agent/template`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            **Response:** Array of template objects
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /agent/create - Create Agent">
        Create a new agent instance from a template.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/agent/create`

            ```json theme={null}
            {
              "templateId": "template123",
              "name": "My Support Agent",
              "customInstructions": "Focus on billing issues",
              "tools": ["search", "billing_lookup"]
            }
            ```
          </Tab>

          <Tab title="Response">
            **Status:** `201 Created`

            **Response:** Created agent object
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="GET /agent/:agentKey - Get Agent">
        Retrieve agent details.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `GET /api/v1/agent/:agentKey`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            **Response:** Complete agent configuration and metadata
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="PUT /agent/:agentKey - Update Agent">
        Update agent configuration.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `PUT /api/v1/agent/:agentKey`

            **Request Body:** Agent configuration updates
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            **Response:** Updated agent object
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="DELETE /agent/:agentKey - Delete Agent">
        Delete an agent.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `DELETE /api/v1/agent/:agentKey`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            **Response:** Deletion confirmation
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="GET /agent/ - List Agents">
        Get all available agents for the organization.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `GET /api/v1/agent/`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            **Response:** Array of agent objects with summary information
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="GET /agent/tools/list - Get Available Tools">
        Retrieve all available tools for agents.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `GET /api/v1/agent/tools/list`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "tools": [
                {
                  "name": "search",
                  "description": "Search organizational knowledge",
                  "parameters": {...}
                },
                {
                  "name": "calculator",
                  "description": "Perform calculations",
                  "parameters": {...}
                }
              ]
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="GET /agent/:agentKey/permissions - Get Agent Permissions">
        Get permissions for a specific agent.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `GET /api/v1/agent/:agentKey/permissions`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            **Response:** Agent permission configuration
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /agent/:agentKey/share - Share Agent">
        Share an agent with other users.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/agent/:agentKey/share`

            ```json theme={null}
            {
              "userIds": ["user789"],
              "accessLevel": "read"
            }
            ```
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            **Response:** Updated agent sharing configuration
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="POST /agent/:agentKey/unshare - Unshare Agent">
        Remove agent sharing.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/agent/:agentKey/unshare`

            ```json theme={null}
            {
              "userIds": ["user789"]
            }
            ```
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            **Response:** Updated agent sharing configuration
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="PUT /agent/:agentKey/permissions - Update Agent Permissions">
        Update agent permissions.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `PUT /api/v1/agent/:agentKey/permissions`

            **Request Body:** Updated permission configuration
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            **Response:** Updated permissions
          </Tab>
        </Tabs>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Semantic Search">
    Direct search functionality across your organization's content without creating conversations.

    <AccordionGroup>
      <Accordion title="POST /search - Search">
        Perform a semantic search across indexed content.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/search`

            ```json theme={null}
            {
              "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
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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\"}"
                }
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="GET /search - Search History">
        Get search history with pagination.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `GET /api/v1/search`

            **Query 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')
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="GET /search/:searchId - Get Search By ID">
        Retrieve a specific search result with populated citations.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `GET /api/v1/search/:searchId`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            [
              {
                "_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"
              }
            ]
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="DELETE /search/:searchId - Delete Search">
        Delete a specific search and its associated citations.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `DELETE /api/v1/search/:searchId`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "message": "Search deleted successfully"
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="DELETE /search - Delete Search History">
        Delete all search history and associated citations.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `DELETE /api/v1/search`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "message": "Search history deleted successfully"
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="PATCH /search/:searchId/share - Share Search">
        Share a search result with other users.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `PATCH /api/v1/search/:searchId/share`

            ```json theme={null}
            {
              "userIds": ["507f1f77bcf86cd799439011"],
              "accessLevel": "read"
            }
            ```

            **Validation:**

            * User existence validated against IAM service
            * `shareLink` automatically generated
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "_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"
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="PATCH /search/:searchId/unshare - Unshare Search">
        Remove search sharing.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `PATCH /api/v1/search/:searchId/unshare`

            ```json theme={null}
            {
              "userIds": ["507f1f77bcf86cd799439011"]
            }
            ```
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "id": "61f30c988a4e2e001b3c7d1a",
              "isShared": false,
              "shareLink": null,
              "sharedWith": [],
              "unsharedUsers": ["507f1f77bcf86cd799439011"],
              "meta": {
                "requestId": "req-unshare-123",
                "timestamp": "2025-04-27T13:15:00.000Z",
                "duration": 120
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="PATCH /search/:searchId/archive - Archive Search">
        Archive a search result.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `PATCH /api/v1/search/:searchId/archive`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="PATCH /search/:searchId/unarchive - Unarchive Search">
        Unarchive a search result.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `PATCH /api/v1/search/:searchId/unarchive`
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "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
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Configuration">
    Internal configuration management endpoints for service administration.

    <AccordionGroup>
      <Accordion title="POST /search/updateAppConfig - Update App Configuration">
        Internal endpoint for updating application configuration.

        <Tabs>
          <Tab title="Request">
            **Endpoint:** `POST /api/v1/search/updateAppConfig`

            **Authentication:** Requires scoped token with `FETCH_CONFIG` scope.
          </Tab>

          <Tab title="Response">
            **Status:** `200 OK`

            ```json theme={null}
            {
              "message": "User configuration updated successfully",
              "config": {
                "aiBackend": "https://ai.example.com",
                "iamBackend": "https://iam.example.com",
                "frontendUrl": "https://app.example.com",
                "jwtSecret": "[REDACTED]"
              }
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>

## Schema Definitions

<Tabs>
  <Tab title="Conversation Schema">
    ```typescript theme={null}
    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';
    }
    ```
  </Tab>

  <Tab title="Message Schema">
    ```typescript theme={null}
    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;
    }
    ```
  </Tab>

  <Tab title="Citation Schema">
    ```typescript theme={null}
    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;
    }
    ```
  </Tab>

  <Tab title="Search Schema">
    ```typescript theme={null}
    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;
    }
    ```
  </Tab>

  <Tab title="Constants">
    ```typescript theme={null}
    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}$/;
    ```
  </Tab>
</Tabs>

## Error Handling

All endpoints return structured error responses with specific error constants:

```json theme={null}
{
  "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