Folders API
Organize your links into folders for better management.
Folders are a flat way to group short links, for example by campaign, client or channel. A link sits in one folder or in none. The Folders API lists, creates, renames and deletes folders, and moves single links between them.
Deleting a folder never deletes its links. They move back to uncategorized. API keys always act on your personal workspace.
/api/v1/foldersList your folders with their link counts. When some links have no folder, the list starts with an "uncategorized" entry that counts them. That entry is not a real folder and cannot be renamed or deleted.
links:readRequest
curl https://trimlink.co/api/v1/folders \
-H "Authorization: Bearer tk_live_your_api_key"Response
{
"success": true,
"folders": [
{
"id": "uncategorized",
"name": "Uncategorized",
"linkCount": 3,
"createdAt": "1970-01-01T00:00:00.000Z"
},
{
"id": "1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d",
"name": "Marketing",
"linkCount": 24,
"createdAt": "2026-01-15T10:00:00.000Z"
}
]
}/api/v1/foldersCreate a folder.
links:writeParameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | 1 to 50 characters: letters, numbers, spaces, hyphens and underscores. |
Request
curl -X POST https://trimlink.co/api/v1/folders \
-H "Authorization: Bearer tk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"name": "Spring Campaign"}'Response
{
"success": true,
"folder": {
"id": "1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d",
"name": "Spring Campaign",
"createdAt": "2026-01-31T12:00:00.000Z"
}
}/api/v1/folders/:idRename a folder.
links:writeParameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | 1 to 50 characters: letters, numbers, spaces, hyphens and underscores. |
Request
curl -X PATCH https://trimlink.co/api/v1/folders/1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d \
-H "Authorization: Bearer tk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"name": "Campaigns 2026"}'Response
{
"success": true,
"folder": {
"id": "1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d",
"name": "Campaigns 2026"
}
}/api/v1/folders/:idDelete a folder. Its links move to uncategorized.
links:writeRequest
curl -X DELETE https://trimlink.co/api/v1/folders/1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d \
-H "Authorization: Bearer tk_live_your_api_key"Response
/api/v1/links/:id/moveMove a link into a folder, or out of all folders.
links:writeParameters
| Name | Type | Required | Description |
|---|---|---|---|
folderId | string | null | Yes | Target folder ID, or null to move the link to uncategorized. |
Request
curl -X PATCH https://trimlink.co/api/v1/links/9c8b7a6d-5e4f-4a3b-8291-0d1e2f3a4b5c/move \
-H "Authorization: Bearer tk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"folderId": "1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d"}'Response
{
"success": true,
"link": {
"id": "9c8b7a6d-5e4f-4a3b-8291-0d1e2f3a4b5c",
"folderId": "1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d"
}
}Errors
These endpoints use the standard error response format.
| Code | When it happens |
|---|---|
400 | The name is empty, longer than 50 characters, uses other characters, or matches an existing folder (ignoring case). Also an ID that is not a UUID. |
403 | The key lacks links:read or links:write, or the plan folder limit is reached (Pro 30, Growth 100, Teams and Enterprise unlimited). Limit errors include tier, limit and current. |
404 | The folder or link does not exist in your workspace. |