Document folders
List, create, trash, and restore document folders.
Folders under /api/v1/document-folders. Any valid bearer API key for the workspace. Missing token → 401 { "error": "Valid bearer API key is required" }.
No cursor pagination. No Idempotency-Key. Session copies: /api/document-folders.
Endpoints
| Method | Path | Envelope |
|---|---|---|
| GET | /api/v1/document-folders | { folders[] } |
| POST | /api/v1/document-folders | 201 { folder } |
| PATCH | /api/v1/document-folders/{id} | { folder } |
There is no v1 GET-by-id or DELETE. Attach documents with Documents (folderId).
Folder object
id, workspaceId, optional parentId, name, createdAt, optional trashedAt.
List and create
GET returns non-trashed folders for the key workspace (includeTrashed is not accepted on this route). Ordered by createdAt ascending in the durable store.
POST JSON:
| Field | Notes |
|---|---|
name | Required after trim. Empty → 400 { "error": "Folder name is required." } |
parentId | Optional. If set and not found in the workspace → 404 { "error": "Parent folder not found." } |
Trash and restore
PATCH body must include boolean trashed. Missing/non-boolean → 400 { "error": "Folder trash state is required." }. Wrong workspace → 404 { "error": "Folder not found" } (no trailing period). In-memory missing ids also 404. A missing Prisma row throws "Folder not found in database store." from the service (the v1 route does not catch it).
trashed: true sets trashedAt; false restores. Trashed folders drop out of GET until restored. This does not rename, move, or hard-delete.
Known gaps
- No rename, parent change, or hard delete on v1.
- No
?includeTrashed=on the list (unlike documents). - Duplicate names under the same parent are allowed.
- Nested trash does not cascade via this route; child folders are independent rows.