# Create a tag

`POST https://app.clik.so/api/tags`

> **In short:** Makes a new tag. Attach it to links by sending its id in `tags` when you create or update a link.

## You need

* **API key permission:** `write`
* **Workspace role:** editor or higher
* **Plan:** some fields need a paid plan — see "Plan-gated fields" below.

## Example

```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
  }
}
```

## Request body

| Field   | Type   | Required | Description                                                  |
| ------- | ------ | -------- | ------------------------------------------------------------ |
| `name`  | string | yes      | The tag's name, up to 10 characters. 1–10 characters         |
| `color` | string | no       | Optional colour, like `#3b82f6`. Pattern `^#[0-9a-fA-F]{6}$` |

## Plan-gated fields

| Field  | Feature | Lowest plan                                                                    |
| ------ | ------- | ------------------------------------------------------------------------------ |
| `name` | tags    | A new tag past the plan's tag count (Free 5, Starter 10, Pro 20, Business 50). |

## Common errors

| Status | Code               | When                                                                            |
| ------ | ------------------ | ------------------------------------------------------------------------------- |
| 401    | `UNAUTHORIZED`     | The API key is missing, malformed or unknown.                                   |
| 402    | `UPGRADE_REQUIRED` | The workspace already has as many tags as its plan allows.                      |
| 403    | `FORBIDDEN`        | The key only has Read permission, or its creator is a viewer in this workspace. |
| 422    | `VALIDATION_ERROR` | `name` is missing or longer than 10 characters, or `color` is not `#rrggbb`.    |
| 429    | `RATE_LIMITED`     | The key went over its per-minute request limit.                                 |

## Good to know

* The name can be up to 10 characters. Spaces at the start and end are removed.
* `color` is optional and must be a 6-digit hex colour like `#3b82f6`.
* Each plan allows a number of tags: Free 5, Starter 10, Pro 20, Business 50. Past it you get `402 UPGRADE_REQUIRED`.

---

Source: https://clik.so/docs/api/tags/create-tag