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.

GET/api/v1/folders

List 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.

Scope: links:read

Request

curl https://trimlink.co/api/v1/folders \
  -H "Authorization: Bearer tk_live_your_api_key"

Response

200Response
{
  "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"
    }
  ]
}
POST/api/v1/folders

Create a folder.

Scope: links:write

Parameters

NameTypeRequiredDescription
namestringYes1 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

201Response
{
  "success": true,
  "folder": {
    "id": "1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d",
    "name": "Spring Campaign",
    "createdAt": "2026-01-31T12:00:00.000Z"
  }
}
PATCH/api/v1/folders/:id

Rename a folder.

Scope: links:write

Parameters

NameTypeRequiredDescription
namestringYes1 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

200Response
{
  "success": true,
  "folder": {
    "id": "1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d",
    "name": "Campaigns 2026"
  }
}
DELETE/api/v1/folders/:id

Delete a folder. Its links move to uncategorized.

Scope: links:write

Request

curl -X DELETE https://trimlink.co/api/v1/folders/1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer tk_live_your_api_key"

Response

204 No Content

Errors

These endpoints use the standard error response format.

CodeWhen it happens
400The 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.
403The 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.
404The folder or link does not exist in your workspace.