Skip to content
Ishvana Ishvana Docs

Search Folders

GET
/api/writing/folders/search

🔍 Search folders.

Searches folders by name and description.

Args: query: Search query string service: Injected DocumentCategoriesService instance

Returns: WritingFolderListResponse: List of matching folders

Raises: HTTPException 500: If search fails

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
query
required
Query

Search query

string

Search query

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

WritingFolderListResponse

Response model for folder list operations in Writing Studio.

Provides flat list of folders with total count for folder management operations. Used when tree structure is not needed or for administrative folder views.

Fields:

  • folders: List of WritingFolderResponse objects
  • total_count: Total number of folders returned

Usage: GET /api/creative/categories/folders returns this model.

JSON Example:

{
  "folders": [
    {"id": "folder_1", "name": "Drafts", ...},
    {"id": "folder_2", "name": "Published", ...}
  ],
  "totalCount": 2
}
object
folders
required
Folders

List of folders

Array<object>
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
totalCount
required
Totalcount

Total folder count

integer

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