Folders API

Organize short links into named, color-coded folders

Folders let you group related short links together for easier management. Free accounts can create up to 3 folders; Pro and higher accounts get unlimited folders. Each folder can optionally have a color for visual organization in the dashboard.

Base URL

https://awsys.co

Authentication

All folder endpoints require a valid API key passed as a Bearer token. See the Authentication page for details.

Authorization: Bearer YOUR_API_KEY

List Folders

GET /api/folders

Returns all folders belonging to your account along with your tier's folder limit.

Response

{
  "folders": [
    {
      "id": "folder_abc123",
      "name": "Marketing",
      "color": "#3B82F6",
      "createdAt": "2026-05-01T10:00:00Z",
      "linkCount": 12
    }
  ],
  "limit": 3,
  "canCreate": true
}

curl example

curl https://awsys.co/api/folders \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a Folder

POST /api/folders

Request body

{
  "name": "Marketing",
  "color": "#3B82F6"
}

Response — 201 Created

{
  "id": "folder_abc123",
  "name": "Marketing",
  "color": "#3B82F6",
  "createdAt": "2026-05-29T12:00:00Z",
  "linkCount": 0
}

curl example

curl -X POST https://awsys.co/api/folders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing", "color": "#3B82F6"}'

Update a Folder

PATCH /api/folders/:folderId

Rename a folder or change its color. Only the fields provided are updated.

Request body

{
  "name": "Marketing — Q3",
  "color": "#10B981"
}

curl example

curl -X PATCH https://awsys.co/api/folders/folder_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing — Q3"}'

Delete a Folder

DELETE /api/folders/:folderId

Deletes the folder. Links that were inside the folder are not deleted — they are simply unassigned.

Response — 200 OK

{ "success": true }

curl example

curl -X DELETE https://awsys.co/api/folders/folder_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Assign a Link to a Folder

POST /api/link/:short/folder

Move a link into a folder. Pass folderId: null to remove a link from any folder.

Request body

{
  "folderId": "folder_abc123"
}

Response — 200 OK

{ "success": true, "folderId": "folder_abc123" }

curl example

curl -X POST https://awsys.co/api/link/abc123/folder \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folderId": "folder_abc123"}'

Tier Limits

Error Codes