Create Folders

Use Folders to organization by project, topic, or knowledge domain.

BlockBrain organizes documents within databases using hierarchical Folders that enforce access rights across tenants, users, and groups. The system aligns with bot/conversation sharing patterns and maintains strict tenant isolation.

Create a new folder

Using the _id from our last step Create a Database, we now start creating subfolders to organize documents. The root folder is the baseline Knowledgebase parentPath here.

Create Folder

post

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

namestringRequired

descriptionany ofOptional

stringOptional

or

nullOptional

knowledgeBasestringRequired

parentPathstringRequired

Responses

200

Successful Response

application/json

_idstringOptional

createdAtstring · date-timeOptional

modifiedAtstring · date-timeOptional

namestringRequired

pathstringOptionalDefault: root

knowledgeBasestringRequired

user_idany ofOptional

stringOptional

or

nullOptional

accessModestring · enumOptionalDefault: restrictedPossible values:

isShareAllany ofOptionalDefault: false

booleanOptional

or

nullOptional

descriptionany ofOptional

stringOptional

or

nullOptional

archivedAtany ofOptional

string · date-timeOptional

or

nullOptional

sourceTypeany ofOptional

string · enumOptionalPossible values:

or

nullOptional

422

Validation Error

application/json

post

/folder

HTTPcURLJavaScriptPython

POST /folder HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 79

{
  "name": "text",
  "description": "text",
  "knowledgeBase": "text",
  "parentPath": "text"
}

{
  "_id": "text",
  "createdAt": "2026-04-03T12:32:58.803Z",
  "modifiedAt": "2026-04-03T12:32:58.803Z",
  "name": "text",
  "path": "root",
  "knowledgeBase": "text",
  "user_id": "text",
  "accessMode": "restricted",
  "isShareAll": false,
  "description": "text",
  "archivedAt": "2026-04-03T12:32:58.803Z",
  "sourceType": "FOLDER_UPLOAD"
}

When creating folders, we again get access to an _id property that can be used for further operations like moving or deleting folders. The path should be used as parentPath when creating more subfolders.

Delete a Folder

The delete method can either use one or several ids to remove folders inside of a Knowledgebase. Here we need to use our _id from the folder creation to delete a given folder again.

Remove Folder

delete

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

knowledge_basestringRequired

Body

application/json

Responses

200

Successful Response

application/json

codeany ofOptional

integerOptional

or

nullOptional

keyany ofOptional

stringOptional

or

nullOptional

bodyany ofOptional

stringOptional

or

nullOptional

422

Validation Error

application/json

delete

/folder/{knowledge_base}/remove

HTTPcURLJavaScriptPython

DELETE /folder/{knowledge_base}/remove HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 45

{
  "sourceItems": [
    {
      "id": "text",
      "type": "file"
    }
  ]
}

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

Next Steps

Now that we have our folder structure set up, time to Upload Documents to DBs.