Folders API

Folders are a flat (non-nested) way to group related short links — for example by campaign, client, or channel. The Folders API lets you list, create, rename, and delete folders, and move individual links between them. Folder membership also powers the folderId filter on the Links API.

Deleting a folder never deletes its links — they are simply moved back to uncategorized. Each list response includes a linkCount so you can show folder sizes without a second request.

List all folders with link counts.

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

{
  "success": true,
  "folders": [
    {
      "id": "4d3c2b1a-9f8e-4d7c-8b6a-5e4f3d2c1b0a",
      "name": "Marketing",
      "linkCount": 24,
      "createdAt": "2026-01-15T10:00:00Z"
    },
    {
      "id": "8e7d6c5b-4a3f-4e2d-9c1b-0a9f8e7d6c5b",
      "name": "Sales",
      "linkCount": 12,
      "createdAt": "2026-01-20T14:30:00Z"
    }
  ]
}

Create a new folder.

curl -X POST https://trimlink.co/api/v1/folders \
  -H "Authorization: Bearer tk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing Campaigns"}'

{
  "success": true,
  "folder": {
    "id": "1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d",
    "name": "Marketing Campaigns",
    "createdAt": "2026-01-31T12:00:00Z"
  }
}

Update a folder name.

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"}'

{
  "success": true,
  "folder": {
    "id": "1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d",
    "name": "Campaigns 2026",
    "updatedAt": "2026-01-31T14:00:00Z"
  }
}

Delete a folder. Links in the folder are moved to uncategorized.

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

Move a link to a different folder.

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"}'

{
  "success": true,
  "data": {
    "id": "9c8b7a6d-5e4f-4a3b-8291-0d1e2f3a4b5c",
    "folderId": "1f2e3d4c-5b6a-4798-8c9d-0e1f2a3b4c5d"
  }
}

Errors

These endpoints use the standard error response format. Common folder-specific failures:

Usage Notes

• Folders are flat — there is no nesting. Model hierarchy in the folder name (e.g. Q3 / Email) if you need it.
• Pass folderId: null to the move endpoint to pull a link back out into uncategorized.
• Deleting a folder is non-destructive to links; they are reassigned to uncategorized, not deleted.