# Folders and tags

Group Clikso links in folders and label them with tags through the API, then filter your links by folder or tag in one call.

> **In short:**
>
> A folder holds links, and each link sits in at most one folder. A tag is a coloured label, and a link can have many. You create both with the API, then send their ids when you create or update a link.

## You need

* **API key:** **Read** to list folders and tags. **Write** to create, change or delete them.
* **Role:** Editor or admin to make changes. Any member can read.
* **Plan:** Any plan, including Free. Each plan allows a set number of folders and tags.

## Create a folder

Folder names can be up to 20 characters.

```bash
curl -X POST "https://app.clik.so/api/folders" \
  -H "Authorization: Bearer $CLIKSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Campaigns"
  }'
```

Response 201:

```json
{
  "status": 201,
  "success": true,
  "message": "Created",
  "data": {
    "id": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
    "name": "Campaigns",
    "created_at": "2026-10-09T09:30:00.000Z",
    "updated_at": "2026-10-09T09:30:00.000Z",
    "link_count": 0
  }
}
```

Keep the `id`. You use it to put links in the folder.

## Create a tag

Tag names can be up to 10 characters. The colour is optional. If you send one, use a six-digit hex code like `#3b82f6`.

```bash
curl -X POST "https://app.clik.so/api/tags" \
  -H "Authorization: Bearer $CLIKSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "launch",
    "color": "#3b82f6"
  }'
```

Response 201:

```json
{
  "status": 201,
  "success": true,
  "message": "Created",
  "data": {
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "launch",
    "color": "#3b82f6",
    "created_at": "2026-10-09T09:30:00.000Z",
    "updated_at": "2026-10-09T09:30:00.000Z",
    "link_count": 0
  }
}
```

## File and tag a link

Send `folder_id` and `tags` when you [create a link](https://clik.so/docs/guides/create-links), or later with an update. `tags` is a list of tag ids.

```bash
curl -X PUT "https://app.clik.so/api/links/3f6c1a2e-9b4d-4e8f-a1c2-7d9e0f1a2b3c" \
  -H "Authorization: Bearer $CLIKSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_id": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
    "tags": [
      "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
    ]
  }'
```

The update answers with the whole link, now with its `folder_id` and full `tags`.

How the two fields behave on an update:

* `tags` replaces the link’s whole tag list. Send every tag the link should keep.
* `tags: []` removes all tags. Leave `tags` out, or send `null`, to keep them as they are.
* `folder_id: null` takes the link out of its folder.

### Move many links at once

To put up to 100 links in one folder, use a bulk update:

```bash
curl -X PATCH "https://app.clik.so/api/links/bulk" \
  -H "Authorization: Bearer $CLIKSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "3f6c1a2e-9b4d-4e8f-a1c2-7d9e0f1a2b3c",
      "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a"
    ],
    "folder_id": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e"
  }'
```

Response 200:

```json
{
  "status": 200,
  "success": true,
  "message": "Success",
  "data": {
    "updated_count": 2
  }
}
```

There is no bulk tagging. To tag many links, update them one by one.

## Find links by folder or tag

Filter the link list with `folder_id`, `tags`, or both. `tags` takes tag ids, separated by commas. A link matches if it has at least one of them.

```bash
curl "https://app.clik.so/api/links?folder_id=6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e&tags=1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d&limit=20" \
  -H "Authorization: Bearer $CLIKSO_API_KEY"
```

You get a page of links in `data`, and paging details in `meta`. See [Manage links](https://clik.so/docs/guides/manage-links) for paging.

## Rename and delete

Rename a folder or a tag with `PUT` and the new value:

```bash
curl -X PUT "https://app.clik.so/api/tags/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer $CLIKSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "promo",
    "color": "#16a34a"
  }'
```

Response 200:

```json
{
  "status": 200,
  "success": true,
  "message": "Success",
  "data": {
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "promo",
    "color": "#16a34a",
    "created_at": "2026-10-01T08:00:00.000Z",
    "updated_at": "2026-10-09T09:30:00.000Z",
    "link_count": 4
  }
}
```

Delete them like this:

```bash
curl -X DELETE "https://app.clik.so/api/folders/6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e" \
  -H "Authorization: Bearer $CLIKSO_API_KEY"
```

Deleting a folder keeps its links. They simply move out of the folder. Deleting a tag removes it from every link, and you cannot undo it.

## How many you can have

| Limit   | Free | Starter | Pro | Business |
| ------- | ---- | ------- | --- | -------- |
| Folders | 3    | 6       | 15  | 40       |
| Tags    | 5    | 10      | 20  | 50       |

An API key that tries to create one more than the plan allows gets `402 UPGRADE_REQUIRED`.

## What you get back

* **List calls** return an array in `data`, sorted by name. Each item has `id`, `name`, `created_at`, `updated_at` and `link_count`. Tags also have `color`.
* **Create** returns `201` and the new folder or tag, with `link_count: 0`.
* **Update** returns `200` and the changed folder or tag.
* **Delete** returns `204` with an empty body.

Tags always come with their real `link_count`. A single folder, from get or update, has no `link_count`, so use the list call to count a folder's links.

## Common errors

| Status | Code               | What it means                                                                                                                 | What to do                                                                                               |
| ------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| 402    | `UPGRADE_REQUIRED` | The workspace already has as many folders or tags as its plan allows.                                                         | Leave the field out, or upgrade the workspace.                                                           |
| 403    | `FORBIDDEN`        | The key has only Read permission, or its owner is a viewer.                                                                   | Check the key’s permission and your role. If you send `Workspace-Id`, it must match the key’s workspace. |
| 404    | `NOT_FOUND`        | No folder or tag with that id in this workspace.                                                                              | Check the id. Ids from another workspace are never found.                                                |
| 422    | `VALIDATION_ERROR` | The name is empty or too long, the colour is not `#rrggbb`, or a link update names a folder or tag id from another workspace. | Fix the field and send the request again.                                                                |

## Good to know

* Folders are flat. There are no folders inside folders.
* A link sits in at most one folder, but it can have any number of tags.
* Folders and tags only organise links. They do not limit who can see them. Every member of the workspace sees every link.
* The bulk call moves links between folders, archives them or deletes them. It cannot add tags.
* Each call costs one request from the key’s per-minute limit. See [Limits](https://clik.so/docs/limits).

---

Source: https://clik.so/docs/guides/folders-and-tags