# Custom Tags

Labels and categorization

## POST /api/v1/custom-tags

Create custom tag

Create a new custom tag and link it to an item

**Permissions:** 🟢 `custom_tags.create`

Request body:

```ts
{
  itemId: number
  categoryHandle: string
  key: string
}
```

Response 201 — Default Response

```ts
{
  status: "success"
  data: {
    id: number
    key: string
    categoryHandle: string
    categoryId: number
    languageId: number
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## POST /api/v1/custom-tags/link

Link custom tag

Link an existing custom tag to an item

**Permissions:** 🟠 `custom_tags.update`

Request body:

```ts
{
  itemId: number
  customTagId: number
}
```

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    success?: boolean
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## GET /api/v1/custom-tags/search

Search custom tags

Search for custom tags by query string

**Permissions:** 🔵 `custom_tags.read`

Query parameters:
- `query` (string, required) — Search string (minimum 3 characters)

Response 200 — Default Response

```ts
{
  status: "success"
  data: Array<{
      id: number
      key: string
      categoryHandle: string
      categoryId: number
      languageId: number
    }>
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## POST /api/v1/custom-tags/unlink

Unlink custom tag

Unlink a custom tag from an item

**Permissions:** 🟠 `custom_tags.update`

Request body:

```ts
{
  itemId: number
  customTagId: number
}
```

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    success?: boolean
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```