Home/Documents/Folders

Folders

Create, update, list, and delete folders for organizing documents. Folders can be nested by specifying a parent_id to create hierarchical structures.

Endpoints

GET	/api/v1/docs/folders	List folders
POST	/api/v1/docs/folders	Create a folder
GET	/api/v1/docs/folders/{id}	Get a folder
PATCH	/api/v1/docs/folders/{id}	Update a folder
DELETE	/api/v1/docs/folders/{id}	Delete a folder

GET/api/v1/docs/folders

List folders

Retrieve a list of folders in the organization.

Authentication required— Include session cookie or Bearer token

Query Parameters

Name	Type	Required	Description
parent_id	string	Optional	Filter by parent folder ID
limit	integer	Optional	Number of items to return (default: 50, max: 200)
offset	integer	Optional	Number of items to skip

Response Fields

Name	Type	Required	Description
	Folder[]	Optional	List of folders
total	integer	Optional	Total count
limit	integer	Optional	Number of items returned
offset	integer	Optional	Number of items skipped

Code Examples

curl "https://api.blueai.jp/api/v1/docs/folders" \
  -H "Cookie: better-auth.session_token=<token>"

Response Example

{
  "items": [
    {
      "id": "folder_01JQ3KABC",
      "organization_id": "org_01HZXYZ",
      "name": "Product Requirements",
      "parent_id": null,
      "created_by": "usr_01HZABC",
      "created_at": "2026-02-10T09:00:00Z",
      "updated_at": "2026-02-20T15:30:00Z"
    }
  ],
  "total": 5,
  "limit": 50,
  "offset": 0
}

POST/api/v1/docs/folders

Create a folder

Create a new folder. Specify parent_id to create a subfolder.

Authentication required— Include session cookie or Bearer token

Request Body

Name	Type	Required	Description
name	string	Required	Folder name
parentId	string	Optional	Parent folder ID (omit to create at root)

Response Fields

Name	Type	Required	Description
	Folder	Optional	Created folder

Code Examples

curl -X POST "https://api.blueai.jp/api/v1/docs/folders" \
  -H "Cookie: better-auth.session_token=<token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Design Specs",
  "parentId": "folder_01JQ3KABC"
}'

Response Example

{
  "folder": {
    "id": "folder_02JQ3KDEF",
    "organization_id": "org_01HZXYZ",
    "name": "Design Specs",
    "parent_id": "folder_01JQ3KABC",
    "created_by": "usr_01HZABC",
    "created_at": "2026-02-10T09:00:00Z",
    "updated_at": "2026-02-20T15:30:00Z"
  }
}

GET/api/v1/docs/folders/{id}

Get a folder

Retrieve details of the specified folder.

Authentication required— Include session cookie or Bearer token

Path Parameters

Name	Type	Required	Description
id	string	Optional	Folder ID

Response Fields

Name	Type	Required	Description
	Folder	Optional	Folder

Code Examples

curl "https://api.blueai.jp/api/v1/docs/folders/folder_123e4567e89b12d3a456426614174000" \
  -H "Cookie: better-auth.session_token=<token>"

Response Example

{
  "folder": {
    "id": "folder_01JQ3KABC",
    "organization_id": "org_01HZXYZ",
    "name": "Product Requirements",
    "parent_id": null,
    "created_by": "usr_01HZABC",
    "created_at": "2026-02-10T09:00:00Z",
    "updated_at": "2026-02-20T15:30:00Z"
  }
}

PATCH/api/v1/docs/folders/{id}

Update a folder

Update the folder name or parent folder.

Authentication required— Include session cookie or Bearer token

Path Parameters

Name	Type	Required	Description
id	string	Optional	Folder ID

Request Body

Name	Type	Required	Description
name	string	Optional	Folder name
parentId	string \| null	Optional	Parent folder ID (null to move to root)

Response Fields

Name	Type	Required	Description
	Folder	Optional	Updated folder

Code Examples

curl -X PATCH "https://api.blueai.jp/api/v1/docs/folders/folder_123e4567e89b12d3a456426614174000" \
  -H "Cookie: better-auth.session_token=<token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Product Requirements (Updated)"
}'

Response Example

{
  "folder": {
    "id": "folder_01JQ3KABC",
    "organization_id": "org_01HZXYZ",
    "name": "Product Requirements (Updated)",
    "parent_id": null,
    "created_by": "usr_01HZABC",
    "created_at": "2026-02-10T09:00:00Z",
    "updated_at": "2026-02-20T15:30:00Z"
  }
}

DELETE/api/v1/docs/folders/{id}

Delete a folder

Delete the specified folder. Documents inside the folder are moved to root.

Authentication required— Include session cookie or Bearer token

Path Parameters

Name	Type	Required	Description
id	string	Optional	Folder ID

Response Fields

Name	Type	Required	Description
success	boolean	Optional	Deletion success flag

Code Examples

curl -X DELETE "https://api.blueai.jp/api/v1/docs/folders/folder_123e4567e89b12d3a456426614174000" \
  -H "Cookie: better-auth.session_token=<token>"

Response Example

{
  "success": true
}