Data Rooms

What is a dataroom, and how can you manage it using API.

Data Rooms are individual chat threads that you can create at the left side of the Knowledge Bot. This is where you start a conversation with the Knowledge Bot. It is a secure, organized workspace where users can centralize and manage project-specific knowledge.

Each room includes:

• Chat thread: Start conversations, ask questions, or use the Prompt Library and Workflows to speed up your prompt needs.

• Data: Upload or connect files, links, databases, and other types of data inside that room. So answers from AI stay focused on that topic.

• Settings: Control what knowledge is connected, what AI models (LLMs) are used, and how the room behaves.

Managing Data Room

A Data Room / Conversation must be created and managed within an Active Knowledge Bot (See Bot Relationship).

Creating a Data Room

We support creating a data room directly from the _id of a pre-defined (workshop) knowledge bot or from the _id of an active (dashboard) knowledge bot.

In case an active knowledge bot replicating the workshop knowledge bot is not yet created, a new one will be created and attached to the API Key owner. If there's already one, this active knowledge bot will then be used to create the new data room. All created data rooms will be attached to an active knowledge bot regardless.

To create a new data room, use the following endpoint:

Add Convo To Bot

post

Creates a new active bot if it doesn't exist and adds a new dataroom / conversation to that active bot.

This endpoint accepts both bot_id of a pre-defined bot and an active bot. In the case of a pre-defined bot, an active bot linked to this pre-defined bot will be fetched or created, and then used to link with the new data room.

The new data room is attached to the active bot, regardless.

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

bot_idstringRequired

Body

application/json

dataroomIdany ofOptional

stringOptional

or

nullOptional

convoNameany ofOptional

stringOptional

or

nullOptional

defaultLanguageany ofOptionalDefault: English

stringOptional

or

nullOptional

sessionIdany ofOptional

stringOptional

or

nullOptional

isDefaultConvoNameany ofOptionalDefault: true

booleanOptional

or

nullOptional

isCompanyGptBotany ofOptionalDefault: false

booleanOptional

or

nullOptional

lengthPresetany ofOptional

string · enumOptionalPossible values:

or

nullOptional

enableGenerateImageany ofOptionalDefault: false

booleanOptional

or

nullOptional

enableGenerateVideoany ofOptionalDefault: false

booleanOptional

or

nullOptional

enableWebSearchany ofOptional

booleanOptional

or

nullOptional

webSearchTypeany ofOptional

string · enumOptionalPossible values:

or

nullOptional

webSearchConfigany ofOptional

or

nullOptional

modelany ofOptional

string · enumOptionalPossible values:

or

string · enumOptionalPossible values:

or

nullOptional

imageModelany ofOptional

string · enumOptionalPossible values:

or

nullOptional

agentany ofOptional

stringOptional

or

nullOptional

customAgentIdany ofOptional

stringOptional

or

nullOptional

isTemporaryany ofOptionalDefault: false

booleanOptional

or

nullOptional

isDefaultGreetingany ofOptionalDefault: true

booleanOptional

or

nullOptional

isDefaultDataroomany ofOptionalDefault: true

booleanOptional

or

nullOptional

networkany ofOptional

stringOptional

or

nullOptional

networkCapabilitiesany ofOptional

string[]Optional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/cortex/active-bot/{bot_id}/convo

HTTPcURLJavaScriptPython

POST /cortex/active-bot/{bot_id}/convo HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 584

{
  "dataroomId": "text",
  "convoName": "text",
  "defaultLanguage": "English",
  "sessionId": "text",
  "isDefaultConvoName": true,
  "isCompanyGptBot": false,
  "lengthPreset": "automatic",
  "enableGenerateImage": false,
  "enableGenerateVideo": false,
  "enableWebSearch": true,
  "webSearchType": "normal_web_search",
  "webSearchConfig": {
    "webSearchProvider": "linkup_normal_web_search",
    "isLinkupDeepSearch": false
  },
  "model": "gpt-3.5-turbo",
  "imageModel": "openai-dall-e-3",
  "agent": "text",
  "customAgentId": "text",
  "isTemporary": false,
  "isDefaultGreeting": true,
  "isDefaultDataroom": true,
  "network": "text",
  "networkCapabilities": [
    "text"
  ]
}

{
  "dataRoomId": "text",
  "activeBotId": "text"
}

The response contains the dataRoomId (convo_id) of the data room, and activeBotId of the active knowledge bot, which is required to access and manage data rooms. To retrieve details of a Data Room, use the following endpoint.

Get Convo Detail

get

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

convo_idstringRequired

Query parameters

messageany ofOptional

stringOptional

or

nullOptional

session_idany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/cortex/conversation/{convo_id}

HTTPcURLJavaScriptPython

GET /cortex/conversation/{convo_id} HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "text",
  "createdAt": "2025-12-10T09:20:00.825Z",
  "modifiedAt": "2025-12-10T09:20:00.825Z",
  "messages": [
    {
      "_id": "text",
      "createdAt": "2025-12-10T09:20:00.825Z",
      "modifiedAt": "2025-12-10T09:20:00.825Z",
      "botId": "text",
      "userId": "text",
      "content": "text",
      "rawContent": "text",
      "role": "text",
      "model": "gpt-3.5-turbo",
      "messageType": "assistant-greeting",
      "status": "activate",
      "langfuseUrl": "",
      "currentContent": "text",
      "uploadedFiles": [
        {
          "_id": "text",
          "createdAt": "2025-12-10T09:20:00.825Z",
          "modifiedAt": "2025-12-10T09:20:00.825Z",
          "name": "text",
          "tokens": 1,
          "enabled": true,
          "errorMessage": "text",
          "status": "IN_PROGRESS",
          "calculatedStatus": "SUCCESS",
          "fileType": "TEXT",
          "url": "text",
          "originUrl": "text",
          "thumbUrl": "text",
          "isDeleted": false,
          "archivedAt": "2025-12-10T09:20:00.825Z",
          "dataRetentionConfig": {
            "isTemporary": true,
            "retentionPeriodDay": 1,
            "enableDataRetention": true
          },
          "isSaved": false,
          "convoId": "text",
          "dataroomId": "text",
          "isSmartOcr": false
        }
      ],
      "selectedWorkflowId": "",
      "workflow": {
        "runTaskId": "",
        "workflowId": "",
        "workflowName": "",
        "stepId": "",
        "stepName": ""
      },
      "selectedStrategy": "",
      "selectedAction": "",
      "selectedAgentTask": {
        "_id": "text",
        "createdAt": "2025-12-10T09:20:00.825Z",
        "modifiedAt": "2025-12-10T09:20:00.825Z",
        "category_id": "text",
        "name": "text",
        "type": "custom",
        "description": "text",
        "category": {
          "_id": "text",
          "createdAt": "2025-12-10T09:20:00.825Z",
          "modifiedAt": "2025-12-10T09:20:00.825Z",
          "icon": "text",
          "name": "text",
          "owner": "text",
          "count": 1,
          "isPublic": false,
          "isTemplate": false
        },
        "isFavorite": false,
        "isSelected": false,
        "isActive": false,
        "categoryName": "text"
      },
      "strategies": [
        {
          "name": "text",
          "slug": "",
          "description": "",
          "icon": "",
          "actions": [
            {
              "name": "text",
              "slug": "",
              "prompt": "",
              "description": "",
              "icon": "",
              "isDefault": true
            }
          ],
          "scopes": [
            "scope-user"
          ],
          "isDefault": true
        }
      ],
      "targetAgentTask": {
        "_id": "text",
        "createdAt": "2025-12-10T09:20:00.825Z",
        "modifiedAt": "2025-12-10T09:20:00.825Z",
        "category_id": "text",
        "name": "text",
        "type": "custom",
        "description": "text",
        "category": {
          "_id": "text",
          "createdAt": "2025-12-10T09:20:00.825Z",
          "modifiedAt": "2025-12-10T09:20:00.825Z",
          "icon": "text",
          "name": "text",
          "owner": "text",
          "count": 1,
          "isPublic": false,
          "isTemplate": false
        },
        "isFavorite": false,
        "isSelected": false,
        "isActive": false,
        "categoryName": "text"
      },
      "targetSelectedStrategy": "",
      "targetSelectedAction": "",
      "promptMessageId": "",
      "isSaved": false,
      "noteId": "text",
      "insightsGraphType": "STATUS_QUO",
      "doc_ref": [
        {
          "doc_id": "text",
          "doc_name": "text",
          "text_id": [
            {
              "content": "text",
              "text_id": "text",
              "score": 0,
              "isRelatedChunk": false,
              "doc_type": "vector-db"
            }
          ],
          "isDownloadable": false,
          "originalUrl": "text",
          "thumbUrl": "text",
          "score": 0,
          "doc_type": "vector-db",
          "prompt": "text",
          "url": "text",
          "status": "SUCCESS",
          "kb_filetype": "text",
          "docExist": true,
          "havePermission": true,
          "breadcrumb": "text",
          "isExtractedZipFileSharepoint": false
        }
      ],
      "webSearchQuery": "text",
      "webRef": [
        {
          "query": "text",
          "answer": [
            {
              "id": "text",
              "url": "text",
              "title": "text",
              "content": "text"
            }
          ]
        }
      ],
      "webProRef": [
        {
          "question": "text",
          "search_queries": [
            {
              "query": "text",
              "answer": [
                {
                  "id": "text",
                  "url": "text",
                  "title": "text",
                  "content": "text"
                }
              ]
            }
          ]
        }
      ],
      "isWebProR": false,
      "webSearchConfig": {
        "webSearchProvider": "linkup_normal_web_search",
        "isLinkupDeepSearch": false
      },
      "isBorrowWebCitation": false,
      "targetText": "text",
      "targetMessageId": "text",
      "messageReplies": [
        "text"
      ],
      "isUnliked": true,
      "feedbackAt": "2025-12-10T09:20:00.825Z",
      "feedbackContent": "text",
      "messageQueryId": "text",
      "mediaUrls": []
    }
  ],
  "messagesTotal": 1,
  "name": "text",
  "isGeneratedName": false,
  "followUp": [
    "text"
  ],
  "model": "gpt-3.5-turbo",
  "imageModel": "azure-gpt-image-1",
  "agent": "text",
  "customAgentId": "text",
  "customAgentName": "text",
  "customAgentCapabilities": {
    "ANY_ADDITIONAL_PROPERTY": {
      "enabled": true
    }
  },
  "customAgentPrompt": "text",
  "customAgentPromptId": "text",
  "customAgentModel": "text",
  "agentsConfig": {
    "ANY_ADDITIONAL_PROPERTY": {
      "capabilities": {
        "ANY_ADDITIONAL_PROPERTY": {
          "enabled": true
        }
      }
    }
  },
  "toolsConfig": [
    "text"
  ],
  "network": "text",
  "networkCapabilities": [
    "text"
  ],
  "selectedNotes": [
    "text"
  ],
  "knowledgeBase": "text",
  "knowledgeBasesDetail": [
    {
      "_id": "text",
      "createdAt": "2025-12-10T09:20:00.825Z",
      "modifiedAt": "2025-12-10T09:20:00.825Z",
      "name": "text",
      "slug": "text",
      "description": "text",
      "documentsCount": 0,
      "owner": "",
      "is_public": false,
      "embeddingModel": "azure-ada-002",
      "markedLanguages": [
        "text"
      ],
      "connected_type": "MANUAL",
      "connected_status": "connected",
      "isKBaseOwner": false,
      "ownerDetail": {
        "email": "text",
        "userId": "text",
        "firstName": "text",
        "lastName": "text",
        "fullName": "text",
        "iconUrl": "text"
      },
      "accessLevel": "mixed"
    }
  ],
  "strategies": [
    {
      "name": "text",
      "slug": "",
      "description": "",
      "icon": "",
      "actions": [
        {
          "name": "text",
          "slug": "",
          "description": "",
          "icon": "",
          "prompt": "text",
          "isDefault": true
        }
      ],
      "scopes": [
        "scope-user"
      ],
      "isDefault": true
    }
  ],
  "enableAutoResponse": false,
  "enableWebSearch": false,
  "webSearchType": "normal_web_search",
  "webSearchConfig": {
    "webSearchProvider": "linkup_normal_web_search",
    "isLinkupDeepSearch": false
  },
  "attachmentCount": 0,
  "language_response": "auto",
  "pinnedNotes": [
    "text"
  ],
  "workflows": [
    {
      "_id": "text",
      "createdAt": "2025-12-10T09:20:00.825Z",
      "modifiedAt": "2025-12-10T09:20:00.825Z",
      "name": "text",
      "description": "text",
      "active": false,
      "isDefault": false,
      "runModeDefault": "run_all_step",
      "mode": "step_by_step",
      "workflowSteps": [
        {
          "workflowId": "text",
          "stepType": "prompt",
          "name": "text",
          "runModeDefault": "run_all_step",
          "apiUrl": "https://example.com",
          "attachPreviousStepOutput": false,
          "auth": {
            "type": "basic",
            "username": "text",
            "password": "text"
          },
          "headers": [
            {
              "key": "text",
              "value": "text",
              "isActive": true
            }
          ],
          "payload": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "queryParams": [
            {
              "key": "text",
              "value": "text",
              "isActive": true
            }
          ],
          "method": "GET",
          "timeout": 10,
          "retries": 3,
          "_id": "text",
          "createdAt": "2025-12-10T09:20:00.825Z",
          "modifiedAt": "2025-12-10T09:20:00.825Z",
          "stepContext": {
            "workflowId": "",
            "workflowStepId": "",
            "contexts": [
              {
                "convoId": "text",
                "convoName": "text",
                "previousStepIds": [
                  "text"
                ],
                "type": "convo"
              }
            ]
          },
          "stepOutput": {
            "_id": "text",
            "createdAt": "2025-12-10T09:20:00.825Z",
            "modifiedAt": "2025-12-10T09:20:00.825Z",
            "workflowId": "",
            "workflowStepId": "",
            "convoId": "text",
            "convoName": "",
            "type": "convo"
          }
        }
      ],
      "workflowJob": {
        "_id": "text",
        "createdAt": "2025-12-10T09:20:00.825Z",
        "modifiedAt": "2025-12-10T09:20:00.825Z",
        "cronTrigger": {
          "year": 1,
          "month": 1,
          "day": 1,
          "week": 1,
          "day_of_week": 1,
          "hour": 1,
          "minute": 1,
          "second": 1,
          "start_date": "2025-12-10T09:20:00.825Z",
          "end_date": "2025-12-10T09:20:00.825Z",
          "utc_offset": 2
        },
        "status": "ready",
        "maxOccurrences": 1,
        "isSendNotificationEmail": false,
        "botId": "",
        "convoId": "",
        "workflowId": ""
      }
    }
  ],
  "continueGenerating": false,
  "knowledgeBaseDestinationInsight": [
    "text"
  ],
  "knowledgeBaseDestinationInsightDetail": [
    {
      "_id": "text",
      "createdAt": "2025-12-10T09:20:00.825Z",
      "modifiedAt": "2025-12-10T09:20:00.825Z",
      "name": "text",
      "slug": "text",
      "description": "text",
      "documentsCount": 0,
      "owner": "",
      "is_public": false,
      "embeddingModel": "azure-ada-002",
      "markedLanguages": [
        "text"
      ],
      "connected_type": "MANUAL",
      "connected_status": "connected",
      "isKBaseOwner": false,
      "ownerDetail": {
        "email": "text",
        "userId": "text",
        "firstName": "text",
        "lastName": "text",
        "fullName": "text",
        "iconUrl": "text"
      },
      "accessLevel": "mixed"
    }
  ],
  "currentRunTaskId": "text",
  "enableReranker": false,
  "enableAgentRetrieval": false,
  "lengthPreset": "automatic",
  "enableGenerateImage": true,
  "chatMode": "normal",
  "archivedAt": "2025-12-10T09:20:00.825Z",
  "dataRetentionConfig": {
    "isTemporary": true,
    "retentionPeriodDay": 1,
    "enableDataRetention": true,
    "isKeepUploadAttachments": true
  },
  "keysNotification": [
    "text"
  ],
  "enableGenerateVideo": true
}

Updating a Data Room

There are few aspects of a data room can be configured with a value, or leave as null to skip, see below table:

Parameter	Type	Description
name	string | null	The name of the data room
knowledgeBase	string[] | null	List of databases to connect to the data room
knowledgeBaseDestinationInsight	string[] | null	List of target databases to contribute knowledges to. See Contributing Knowledge
enableWebSearch	boolean | null	Enable the bot to perform web search with Tavily engine to provide knowledge from the internet to the bot context (this option overrides other types of knowledge sources e.g. databases, file injection, insights, ...)
enableReranker	boolean | null	Enable reranking function using ms-marco-TinyBERT-L-2-v2 to rerank the fetched documents, provide more concise and relevant knowledges to the AI Model while reducing the context window used. This option will, however, increase processing time to get a response
enableAgentRetrieval	boolean | null	Enable the intent agent to filter the most relevant databases / folder before performing the search method to retrieve knowledge

`enableAutoResponse` is deprecated and will be removed in the future releases

Update Convo Detail

patch

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

convo_idstringRequired

Body

application/json

nameany ofOptional

stringOptional

or

nullOptional

knowledgeBaseany ofOptional

string[] · max: 30Optional

or

nullOptional

enableAutoResponseany ofOptional

booleanOptional

or

nullOptional

knowledgeBaseDestinationInsightany ofOptional

string[]Optional

or

nullOptional

enableWebSearchany ofOptional

booleanOptional

or

nullOptional

webSearchTypeany ofOptional

string · enumOptionalPossible values:

or

nullOptional

webSearchConfigany ofOptional

or

nullOptional

enableRerankerany ofOptional

booleanOptional

or

nullOptional

enableAgentRetrievalany ofOptional

booleanOptional

or

nullOptional

modelany ofOptional

string · enumOptionalPossible values:

or

string · enumOptionalPossible values:

or

string · enumOptionalPossible values:

or

nullOptional

imageModelany ofOptional

string · enumOptionalPossible values:

or

nullOptional

agentany ofOptional

stringOptional

or

nullOptional

customAgentIdany ofOptional

stringOptional

or

nullOptional

agentConfigany ofOptional

or

nullOptional

toolsConfigany ofOptional

string[]Optional

or

nullOptional

networkany ofOptional

stringOptional

or

nullOptional

networkCapabilitiesany ofOptional

string[]Optional

or

nullOptional

enableGenerateImageany ofOptional

booleanOptional

or

nullOptional

enableGenerateVideoany ofOptional

booleanOptional

or

nullOptional

lengthPresetany ofOptional

string · enumOptionalPossible values:

or

nullOptional

chatModeany ofOptional

string · enumOptionalPossible values:

or

nullOptional

dataroomIdany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

patch

/cortex/conversation/{convo_id}

HTTPcURLJavaScriptPython

PATCH /cortex/conversation/{convo_id} HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 673

{
  "name": "text",
  "knowledgeBase": [
    "text"
  ],
  "enableAutoResponse": true,
  "knowledgeBaseDestinationInsight": [
    "text"
  ],
  "enableWebSearch": true,
  "webSearchType": "normal_web_search",
  "webSearchConfig": {
    "webSearchProvider": "linkup_normal_web_search",
    "isLinkupDeepSearch": false
  },
  "enableReranker": true,
  "enableAgentRetrieval": true,
  "model": "gpt-3.5-turbo",
  "imageModel": "openai-dall-e-3",
  "agent": "text",
  "customAgentId": "text",
  "agentConfig": {
    "capabilities": {
      "ANY_ADDITIONAL_PROPERTY": {
        "enabled": true
      }
    }
  },
  "toolsConfig": [
    "text"
  ],
  "network": "text",
  "networkCapabilities": [
    "text"
  ],
  "enableGenerateImage": true,
  "enableGenerateVideo": true,
  "lengthPreset": "automatic",
  "chatMode": "normal",
  "dataroomId": "text"
}

{
  "name": "text",
  "knowledgeBase": [
    {
      "_id": "text",
      "createdAt": "2025-12-10T09:20:00.825Z",
      "modifiedAt": "2025-12-10T09:20:00.825Z",
      "name": "text",
      "slug": "text",
      "description": "text",
      "documentsCount": 0,
      "owner": "",
      "is_public": false,
      "embeddingModel": "azure-ada-002",
      "markedLanguages": [
        "text"
      ],
      "connected_type": "MANUAL",
      "connected_status": "connected",
      "isKBaseOwner": false,
      "ownerDetail": {
        "email": "text",
        "userId": "text",
        "firstName": "text",
        "lastName": "text",
        "fullName": "text",
        "iconUrl": "text"
      },
      "accessLevel": "mixed"
    }
  ],
  "knowledgeBasesDetail": [
    {
      "_id": "text",
      "createdAt": "2025-12-10T09:20:00.825Z",
      "modifiedAt": "2025-12-10T09:20:00.825Z",
      "name": "text",
      "slug": "text",
      "description": "text",
      "documentsCount": 0,
      "owner": "",
      "is_public": false,
      "embeddingModel": "azure-ada-002",
      "markedLanguages": [
        "text"
      ],
      "connected_type": "MANUAL",
      "connected_status": "connected",
      "isKBaseOwner": false,
      "ownerDetail": {
        "email": "text",
        "userId": "text",
        "firstName": "text",
        "lastName": "text",
        "fullName": "text",
        "iconUrl": "text"
      },
      "accessLevel": "mixed"
    }
  ],
  "enableAutoResponse": true,
  "knowledgeBaseDestinationInsight": [
    {
      "_id": "text",
      "createdAt": "2025-12-10T09:20:00.825Z",
      "modifiedAt": "2025-12-10T09:20:00.825Z",
      "name": "text",
      "slug": "text",
      "description": "text",
      "documentsCount": 0,
      "owner": "",
      "is_public": false,
      "embeddingModel": "azure-ada-002",
      "markedLanguages": [
        "text"
      ],
      "connected_type": "MANUAL",
      "connected_status": "connected",
      "isKBaseOwner": false,
      "ownerDetail": {
        "email": "text",
        "userId": "text",
        "firstName": "text",
        "lastName": "text",
        "fullName": "text",
        "iconUrl": "text"
      },
      "accessLevel": "mixed"
    }
  ],
  "enableWebSearch": true,
  "webSearchType": "normal_web_search",
  "webSearchConfig": {
    "webSearchProvider": "linkup_normal_web_search",
    "isLinkupDeepSearch": false
  },
  "enableReranker": false,
  "enableAgentRetrieval": false,
  "enableGenerateImage": true,
  "enableGenerateVideo": true
}

Deleteing a Data Room

Deleting a dataroom removes all the chat history and injected files in that data room.

Deleting a data room is **NOT REVERSIBLE**. Proceed with caution.

Delete Convo

delete

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

convo_idstringRequired

Responses

200

Successful Response

application/json

422

Validation Error

application/json

delete

/cortex/conversation/{convo_id}

HTTPcURLJavaScriptPython

DELETE /cortex/conversation/{convo_id} HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "code": 1,
  "key": "text",
  "body": "text"
}