# Tags

> Tags and tag categories: list, create, update, delete. Per-trade tag assignment lives on the Trades page.
> Source: https://help.tradavity.com/api-docs/tags
> Category: Resources

---

Manage your tag catalog and tag categories. To assign tags to a specific trade, see [PUT /trades/{n}/tags](https://help.tradavity.com/api-docs/trades).

## GET /tag-categories

**Scope:** `read:tags`

Your tag categories.

## GET /tags

**Scope:** `read:tags`

Your tags. Optional filters: `category_id`, `type` (`mistake` or `custom`).

---

## POST /tag-categories

**Scope:** `write:tags`

Create a tag category. Body: `{ "name": string (1–50 chars) }`. Names must be unique within your account; duplicates return `409 duplicate_name`.

```bash
curl -X POST https://app.tradavity.com/api/v1/tag-categories \
  -H "Authorization: Bearer tvty_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"name": "Setup quality"}'
```

## PATCH /tag-categories/{id}

**Scope:** `write:tags`

Rename. Body: `{ "name": string }`.

## DELETE /tag-categories/{id}

**Scope:** `write:tags`

Hard delete. Refuses with `409 category_has_tags` if any tag still belongs to it — move or delete the tags first.

## POST /tags

**Scope:** `write:tags`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `category_id` | int | yes | Must be a category you own. |
| `name` | string (1–100) | yes | Unique within your account. |
| `color` | hex string | no | `#RRGGBB` format. Defaults to `#3b82f6`. |

```bash
curl -X POST https://app.tradavity.com/api/v1/tags \
  -H "Authorization: Bearer tvty_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"category_id": 6, "name": "A+ Setup", "color": "#10b981"}'
```

## PATCH /tags/{id}

**Scope:** `write:tags`

Update any subset of `name`, `category_id`, `color`. Renaming to a name that already exists on another tag returns `409 duplicate_name`.

## DELETE /tags/{id}

**Scope:** `write:tags`

Hard delete. The `jrnl_trade_tags` rows referencing this tag cascade-delete via FK, so the tag is also removed from every trade.