Skip to content
Ishvana Ishvana Docs

Create Folder

POST
/api/writing/folders

📁 Create a new folder.

Creates a new folder in the document organization hierarchy.

Args: request: Folder creation request with name, parent_id, color, icon, description service: Injected DocumentCategoriesService instance

Returns: WritingFolderResponse: Created folder with all metadata

Raises: HTTPException 400: If parent folder not found HTTPException 500: If folder creation fails

Request Body required

Section titled “Request Body required ”
FolderCreateRequest
object
name
required
Name
string
parent_id
Any of:
string
color
Color
string
default: #6366f1
icon
Icon
string
default: folder
description
Description
string
""

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

WritingFolderResponse

Response model for a single document folder in Writing Studio.

Provides complete folder information including metadata, display properties, and document count statistics. Used by document categories/folder endpoints for folder CRUD operations and listing.

Fields:

  • id: Unique folder identifier (UUID string)
  • name: Folder display name (1-100 characters)
  • parent_id: Parent folder ID (null for root-level folders)
  • color: Folder color in hex format (default: #6366f1 indigo)
  • icon: Folder icon name from icon library (default: folder)
  • description: Folder description for organization (optional)
  • created_at: ISO 8601 timestamp of folder creation
  • updated_at: ISO 8601 timestamp of last modification
  • order: Sort order position within parent folder
  • document_count: Number of documents in this folder

Usage:

  • GET /api/creative/categories/folders/{folder_id} returns this model
  • POST /api/creative/categories/folders returns this model
  • PUT /api/creative/categories/folders/{folder_id} returns this model
  • Used in folder lists and tree structures

JSON Example:

{
  "id": "folder_abc123",
  "name": "Drafts",
  "parentId": null,
  "color": "#f59e0b",
  "icon": "file-edit",
  "description": "Work in progress documents",
  "createdAt": "2025-12-04T10:00:00Z",
  "updatedAt": "2025-12-04T10:00:00Z",
  "order": 0,
  "documentCount": 15
}

Integration:

  • DocumentCategoriesService: Provides folder data
  • Frontend FolderTree: Displays folder hierarchy
  • Drag-and-drop UI: Uses order for positioning
object
id
required
Id

Unique folder identifier

string
name
required
Name

Folder display name

string
>= 1 characters <= 100 characters
parentId
Any of:
string
color
Color

Folder color (hex)

string
default: #6366f1
icon
Icon

Folder icon name

string
default: folder
description
Description

Folder description

string
""
createdAt
required
Createdat

Creation timestamp (ISO 8601)

string
updatedAt
required
Updatedat

Last update timestamp (ISO 8601)

string
order
Order

Sort order position

integer
0
documentCount
Documentcount

Documents in folder

integer
0

422

Section titled “422 ”

Validation Error

HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object