Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ptshen/timeful-plus/llms.txt
Use this file to discover all available pages before exploring further.
Folders let users group their events into named, optionally color-coded collections. All folder endpoints are scoped to the authenticated user: a user can only read and modify their own folders.
All folder endpoints require authentication. Requests without a valid session cookie receive 401 Unauthorized.
List All Folders
Returns all folders belonging to the signed-in user. If the user has no folders, an empty array is returned.
Response 200 OK: Array of Folder objects (without event contents).
curl -s -b cookies.txt http://localhost:3002/api/user/folders
[
{
"_id": "64b3f1a2c9e77f001234ffff",
"userId": "64b3f1a2c9e77f001234aaaa",
"name": "Work",
"color": "#4f46e5",
"eventIds": []
}
]
Create Folder
Creates a new folder for the signed-in user.
Display name for the folder (e.g. "Work", "Personal").
Optional hex color code for the folder label (e.g. "#4f46e5").
201 Created: Returns an object containing the new folder’s ObjectID:
{ "id": "64b3f1a2c9e77f001234ffff" }
curl -s -X POST http://localhost:3002/api/user/folders \
-b cookies.txt \
-H "Content-Type: application/json" \
-d '{ "name": "Work", "color": "#4f46e5" }'
Get Folder
GET /api/user/folders/:folderId
| Parameter | Type | Description |
|---|
folderId | string | MongoDB ObjectID of the folder |
200 OK: A Folder object with eventIds populated.
Response 404 Not Found: { "error": "Folder not found" } — folder does not exist or belongs to a different user.
curl -s -b cookies.txt \
http://localhost:3002/api/user/folders/64b3f1a2c9e77f001234ffff
{
"_id": "64b3f1a2c9e77f001234ffff",
"userId": "64b3f1a2c9e77f001234aaaa",
"name": "Work",
"color": "#4f46e5",
"eventIds": [
"64b3f1a2c9e77f001234abcd",
"64b3f1a2c9e77f001234efgh"
]
}
Update Folder
PATCH /api/user/folders/:folderId
| Parameter | Type | Description |
|---|
folderId | string | MongoDB ObjectID of the folder |
New display name for the folder.
New hex color code (e.g. "#10b981").
200 OK: No body.
curl -s -X PATCH http://localhost:3002/api/user/folders/64b3f1a2c9e77f001234ffff \
-b cookies.txt \
-H "Content-Type: application/json" \
-d '{ "name": "Work Projects", "color": "#10b981" }'
Delete Folder
DELETE /api/user/folders/:folderId
| Parameter | Type | Description |
|---|
folderId | string | MongoDB ObjectID of the folder |
200 OK: No body.
curl -s -X DELETE http://localhost:3002/api/user/folders/64b3f1a2c9e77f001234ffff \
-b cookies.txt
Assigning Events to Folders
Use POST /api/user/events/:eventId/set-folder from the User API to add or remove events from a folder.
Worked example — create a folder and assign an event:
Create the folder
curl -s -X POST http://localhost:3002/api/user/folders \
-b cookies.txt \
-H "Content-Type: application/json" \
-d '{ "name": "Q3 Planning", "color": "#f59e0b" }'
# Response: { "id": "64b3f1a2c9e77f001234ffff" }
Assign an event to the folder
curl -s -X POST \
http://localhost:3002/api/user/events/64b3f1a2c9e77f001234abcd/set-folder \
-b cookies.txt \
-H "Content-Type: application/json" \
-d '{ "folderId": "64b3f1a2c9e77f001234ffff" }'
# Response: 200 OK
Verify the folder contents
curl -s -b cookies.txt \
http://localhost:3002/api/user/folders/64b3f1a2c9e77f001234ffff
# Response: Folder object with eventIds populated
Remove the event from the folder
curl -s -X POST \
http://localhost:3002/api/user/events/64b3f1a2c9e77f001234abcd/set-folder \
-b cookies.txt \
-H "Content-Type: application/json" \
-d '{ "folderId": null }'
# Response: 200 OK
Folder Object Reference
MongoDB ObjectID of the folder.
ObjectID of the owning user.
Display name of the folder.
Optional hex color string (e.g. "#4f46e5"). Absent when not set.
When true, the folder has been soft-deleted. Soft-deleted folders are excluded from GET /api/user/folders results.
Array of event ObjectIDs contained in this folder. Only populated by GET /api/user/folders/:folderId; empty array otherwise.