Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/arrozet/caret/llms.txt

Use this file to discover all available pages before exploring further.

Folders are the organizational layer between workspaces and documents in Caret. They can be nested arbitrarily deep using the parent_folder_id field — a folder with parent_folder_id: null sits at the workspace root, while child folders reference a parent by UUID. This structure lets you model complex information hierarchies (teams, projects, epics, sprints) without any depth limit. The Folders API exposes endpoints for creating, listing, reordering, renaming, reparenting, and soft-deleting folders. All endpoints require a valid Supabase JWT passed as a Bearer token.
All endpoints are routed through the API Gateway. The gateway forwards /api/v1/folders* traffic to the internal document-service. Always target https://api.caret.page/api/v1/... from client code.

​
POST /api/v1/folders

Create a new folder inside a workspace. The folder is placed at the workspace root by default. Pass a parent_folder_id to nest it inside an existing folder. Optionally provide a sort_order value to control the folder’s position among its siblings. Request body
​
workspace_id
string
required
UUID of the workspace to create the folder in. The caller must be a member of this workspace.
​
name
string
required
Display name for the folder. Shown in the sidebar tree.
​
parent_folder_id
string | null
UUID of the parent folder. Pass null or omit to create the folder at the workspace root.
​
sort_order
number
Optional numeric sort order for manual ordering among sibling folders. Folders without a sort_order are ordered by created_at by default.
Response — 201 Created
​
id
string
UUID of the newly created folder.
​
workspace_id
string
UUID of the workspace this folder belongs to.
​
parent_folder_id
string | null
UUID of the parent folder, or null if the folder is at the workspace root.
​
name
string
Display name of the folder.
​
sort_order
number | null
Manual sort order, or null if not explicitly set.
​
created_by_user_id
string | null
UUID of the user who created the folder.
​
created_at
string
ISO 8601 timestamp of when the folder was created.
​
updated_at
string
ISO 8601 timestamp of the last update to the folder record.
curl -X POST https://api.caret.page/api/v1/folders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Product Specs",
    "parent_folder_id": null,
    "sort_order": 1
  }'

{
  "id": "f1a2b3c4-d5e6-f789-0abc-def123456789",
  "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "parent_folder_id": null,
  "name": "Product Specs",
  "sort_order": 1,
  "created_by_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
  "created_at": "2024-11-01T09:00:00.000Z",
  "updated_at": "2024-11-01T09:00:00.000Z"
}

​
GET /api/v1/folders

List folders in a workspace, optionally scoped to a specific parent folder. Use this endpoint to fetch the immediate children of a given folder when lazily building out a tree UI. Pass only workspace_id to retrieve all root-level folders (those with parent_folder_id: null), or also pass parent_folder_id to retrieve the children of a specific folder. Query parameters
​
workspace_id
string
required
UUID of the workspace to list folders from.
​
parent_folder_id
string
Optional UUID of the parent folder to scope results to. When omitted, returns folders at the workspace root (those with parent_folder_id: null).
​
limit
number
Maximum number of folders to return. Omit for unpaginated results.
​
offset
number
Number of folders to skip before returning results. Used together with limit for cursor-style pagination.
Response — 200 OK — array of FolderResponseDto Returns an array of folder objects. Each object has the same shape as the response documented in POST /api/v1/folders above. 
curl -X GET "https://api.caret.page/api/v1/folders?workspace_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <token>"

[
  {
    "id": "f1a2b3c4-d5e6-f789-0abc-def123456789",
    "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "parent_folder_id": null,
    "name": "Product Specs",
    "sort_order": 1,
    "created_by_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
    "created_at": "2024-11-01T09:00:00.000Z",
    "updated_at": "2024-11-01T09:00:00.000Z"
  },
  {
    "id": "f2b3c4d5-e6f7-a890-1bcd-ef2345678901",
    "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "parent_folder_id": null,
    "name": "Engineering RFCs",
    "sort_order": 2,
    "created_by_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
    "created_at": "2024-11-02T10:30:00.000Z",
    "updated_at": "2024-11-02T10:30:00.000Z"
  }
]

​
GET /api/v1/folders/all

Fetch all folders across the entire workspace as a single flat array, regardless of nesting depth. This is the preferred endpoint for building a full sidebar folder tree in one round-trip — load all folders at once, then construct the tree client-side by grouping on parent_folder_id. This avoids the recursive requests that GET /api/v1/folders with per-level scoping would require.
Use this endpoint on initial page load to populate the full folder tree in one request. For subsequent lazy-loading of deep subtrees, use GET /api/v1/folders?workspace_id=...&parent_folder_id=... scoped to the expanded folder.
Query parameters
​
workspace_id
string
required
UUID of the workspace to list all folders from.
​
limit
number
Maximum number of folders to return. Omit for unpaginated results.
​
offset
number
Number of folders to skip before returning results. Used together with limit for cursor-style pagination.
Response — 200 OK — array of FolderResponseDto Returns a flat array of all folder objects in the workspace, at all nesting levels. Use parent_folder_id to reconstruct the tree client-side. 
curl -X GET "https://api.caret.page/api/v1/folders/all?workspace_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <token>"

[
  {
    "id": "f1a2b3c4-d5e6-f789-0abc-def123456789",
    "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "parent_folder_id": null,
    "name": "Product Specs",
    "sort_order": 1,
    "created_by_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
    "created_at": "2024-11-01T09:00:00.000Z",
    "updated_at": "2024-11-01T09:00:00.000Z"
  },
  {
    "id": "f3c4d5e6-f7a8-b901-2cde-f34567890123",
    "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "parent_folder_id": "f1a2b3c4-d5e6-f789-0abc-def123456789",
    "name": "Mobile",
    "sort_order": 1,
    "created_by_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
    "created_at": "2024-11-03T11:00:00.000Z",
    "updated_at": "2024-11-03T11:00:00.000Z"
  },
  {
    "id": "f4d5e6f7-a8b9-c012-3def-456789012345",
    "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "parent_folder_id": "f1a2b3c4-d5e6-f789-0abc-def123456789",
    "name": "Web",
    "sort_order": 2,
    "created_by_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
    "created_at": "2024-11-03T11:05:00.000Z",
    "updated_at": "2024-11-03T11:05:00.000Z"
  }
]

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

Update a folder’s name, parent, or sort order. All fields are optional — only fields you include will be modified. Use this endpoint to rename a folder, move it to a different parent (or to the workspace root), or reposition it among siblings.
The gateway spec uses PATCH for this operation (partial update semantics). Sending parent_folder_id: null explicitly moves the folder to the workspace root. Omitting parent_folder_id entirely leaves the current parent unchanged.
Path parameters
​
id
string
required
UUID of the folder to update.
Request body — all fields optional
​
name
string
New display name for the folder.
​
parent_folder_id
string | null
Move the folder to a different parent. Pass a folder UUID to nest under another folder, or null to move to the workspace root.
​
sort_order
number | null
Update the manual sort order. Pass null to clear the sort order and revert to default created_at ordering.
Response — 200 OK — FolderResponseDto Returns the full updated folder object. 
curl -X PATCH https://api.caret.page/api/v1/folders/f1a2b3c4-d5e6-f789-0abc-def123456789 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Specifications",
    "sort_order": 0
  }'

{
  "id": "f1a2b3c4-d5e6-f789-0abc-def123456789",
  "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "parent_folder_id": null,
  "name": "Product Specifications",
  "sort_order": 0,
  "created_by_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
  "created_at": "2024-11-01T09:00:00.000Z",
  "updated_at": "2024-11-06T15:45:00.000Z"
}

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

Soft-delete a folder. The folder is marked with a deleted_at timestamp and will no longer appear in any list or get responses. Nested child folders and documents within the folder are also implicitly inaccessible after the parent is deleted. Only workspace owners or the folder creator can perform this operation.
Deleting a folder is a soft delete that cascades implicitly — all nested child folders and documents become inaccessible. The underlying records are retained in the database with deleted_at set on the folder. This action cannot be reversed through the API.
Path parameters
​
id
string
required
UUID of the folder to delete.
Response — 204 No Content No response body is returned on successful deletion. 
curl -X DELETE https://api.caret.page/api/v1/folders/f1a2b3c4-d5e6-f789-0abc-def123456789 \
  -H "Authorization: Bearer <token>"

Build docs developers (and LLMs) love

Get started for freeTalk to us