# TagController

## Overview

* [Description](#description)
* [Tag JSON object](#tag-json-object)
  * [JSON Fields](#json-fields)
  * [CSV Fields](#csv-fields)
* [API Reference](#api-reference)
  * [GET /](#get-)
  * [POST /](#post-)
  * [GET /:id](#get-id)
  * [PUT /:id (json)](#put-id-json)
  * [PUT /:id (multipart)](#put-id-multipart)
  * [DELETE /:id](#delete-id)
  * [DELETE /:id/:assetType](#delete-idassettype)
  * [GET /:id/items](#get-iditems)
  * [GET /:id/materials](#get-idmaterials)
  * [GET /:id/components](#get-idcomponents)
  * [GET /:id/parentTags](#get-idparenttags)
  * [GET /:id/tagConnections](#get-idtagconnections)
  * [POST /:id/tagConnections/:tagId](#post-idtagconnectionstagid)
  * [PUT /:id/tagConnections/:tagId](#put-idtagconnectionstagid)
  * [DELETE /:id/tagConnections/:tagId](#delete-idtagconnectionstagid)
  * [GET /:id/itemConnections](#get-iditemconnections)
  * [POST /:id/itemConnections/:itemCombinedId](#post-iditemconnectionsitemcombinedid)
  * [PUT /:id/itemConnections/:itemCombinedId](#put-iditemconnectionsitemcombinedid)
  * [DELETE /:id/itemConnections/:itemCombinedId](#delete-iditemconnectionsitemcombinedid)
  * [POST /:id/pngIcon](#post-idpngicon)
  * [POST /:id/svgIcon](#post-idsvgicon)
  * [POST /:id/inspirationImage](#post-idinspirationimage)

## Description

Path /v2/tags

Handles all requests regarding tags: creating, updating, deleting.

## Tag JSON object

An example for a tag JSON object.

```json
{
    "id": "products",
    "global": true,
    "created": "2016-08-01T14:35:53.000Z",
    "updated": "2016-11-28T16:48:34.000Z",
    "links": {
        "items": "/tags/products/items",
        "materials": "/tags/products/materials",
        "parentTags": "/tags/products/parentTags"
    },
    "catalog": "roomle_white_furniture",
    "label": "Products",
    "language": "en",
    "items": ["roomle_white_furniture:door"],
    "tags": [
        "product_beds",
        "product_lighting",
        "product_miscellaneous",
        "product_mockup",
        "product_seating",
        "product_storage",
        "product_tables"
    ],
    "parents": [
        "roomle_white_furniture_root"
    ],
    "hidden": false,
    "visibilityStatus": 0
}
```

Responses are usually wrapped in a meta object, which contains additional information about the response and may contain a single tag or a list of tags.

```
{
    "tag": 
        {tagObject},
    "tags": [
        {tagObject1},
        {tagObject2},
        ...
    ],
    "meta": {
        "lastUpdated": "2018-01-23T09:15:39.000Z",
        "cached": false,
        "total": 2,
        "serverTime": "2019-03-14T12:29:08.549Z"
    }
}
```

### JSON Fields

* id
* global
* created
* updated
* links - list of links to related resources
  * items
  * materials
  * components
  * parentTags
* catalog - the catalog this tag belongs to
* label
* language
* items - list of item ids connected to this tag
* tags - list of child tag ids connected to this tag
* parents - list of parent tag ids connected to this tag
* hidden - **deprecated since 2.88.0** - superseded by visibilityStatus
* visibilityStatus : possible values
  * 0 : SHOWN (visible everywhere)
  * 1 : SHOWN\_IN\_CMS (visible only in cms context)
  * 2 : ARCHIVED (hidden everywhere)

### CSV fields

* id: identifier of a tag - **deprecated since 2.88.0** - use tag\_id instead
* tag\_id : identifier of the tag
* Translations can be multiple, we always return all the available translations in the form of multiple column pairs. If no translations are available, we insert in the CSV reference columns label\_en and description\_en.
* label\_{languageCode}: languageCode in ISO standard can be "en" or "de" for example and will be the current value of this language in the TagTranslation.
* description\_{languageCode}: languageCode in ISO standard can be "en" or "de" for example and will be the current value of this language in the TagTranslation.
* png\_icon: current png icon for this tag
* svg\_icon: current svg icon for this tag
* inspiration\_image: current inspiration image for this tag
* global: is the tag global visible?
* hidden: **deprecated since 2.88.0** - superseded by visibilityStatus
* visibilityStatus : possible values
  * 0 : SHOWN (visible everywhere)
  * 1 : SHOWN\_IN\_CMS (visible only in cms context)
  * 2 : ARCHIVED (hidden everywhere)
* sort: can be an integer or null, if there is no value for this field
* material\_ids: all connected material combined ids separated by ' ' (whitespace)
* item\_ids: all connected item combined ids separated by ' ' (whitespace)
* component\_ids: all connected component combined ids separated by ' ' (whitespace)
* parent\_tag\_ids: ids of parent tags separated by ' ' (whitespace)

## API Reference

#### GET /

List of all tags matching the filter and visible to the Client

Generates: application/json

Response (200 OK): Returns a list of [Tag JSON object](#tag-json-object).

Query Parameters

| Name        | Type            | Comment                                            |
| ----------- | --------------- | -------------------------------------------------- |
| ids\[]      | List of strings | filters the result to the given tag ids            |
| catalogs\[] | List of strings | filters the result to the given catalog ids        |
| global      | Boolean         | If true returns only global tags, default is false |

#### POST /

Creates a new tag in the catalog provided in the body.

Accepts: application/json Generates: application/json

Body: [Tag JSON object](#tag-json-object)

Response (201 CREATED): [Tag JSON object](#tag-json-object)

#### GET /:id

Returns a specific tag.

Generates: application/json

Response (200 OK): [Tag JSON object](#tag-json-object)

#### PUT /:id (json)

Updates a specific tag. Assets needs to be uploaded explicitly (using [PUT /:id (multipart)](#put-id-multipart)).

Accepts: application/json Generates: application/json

Body: [Tag JSON object](#tag-json-object)

Response (200 OK): Updated [Tag JSON object](#tag-json-object)

#### PUT /:id (multipart)

updates assets on an tag

Accepts: multipart-formdata Generates: application/json

parameters:

* the data, either as file or as URL. if both are provided, the URL is used
  * file : datafile to be uploaded
  * fileUrl: the publicly available url to the datafile
* type: type of the asset

possible types are

* "svgIcon"
* "pngIcon"
* "inspirationImage"

Response (200 OK): updated [Tag JSON object](#tag-json-object) with updated asset

For more information on the assets, please check [ElementAssets](https://docs.roomle.com/rubens/rest-api/rest-api-reference/elementassets#uploadable-types)

#### DELETE /:id

Deletes a specific tag.

Response (204 NO CONTENT): deleted

#### DELETE /:id/:assetType

deletes an asset on a specific tag

possible types are

* "svgIcon"
* "pngIcon"
* "inspirationImage"

Response (204 NO CONTENT): deleted

For more information on the assets, please check [ElementAssets](https://docs.roomle.com/rubens/rest-api/rest-api-reference/elementassets#uploadable-types)

### Links

#### GET /:id/items

Generates: application/json

Returns all items which are assigned to this tag.

Response (200 OK): List of [Item JSON object](https://docs.roomle.com/rubens/rest-api/rest-api-reference/item#item-json-object)

#### GET /:id/materials

Generates: application/json

Returns all materials which are assigned to this tag.

Query Parameters

| Name          | Type    | Comment                                      | Default |
| ------------- | ------- | -------------------------------------------- | ------- |
| embedTextures | Boolean | If true, embeds texture data in the response | false   |

Response (200 OK): List of [Material JSON object](https://docs.roomle.com/rubens/rest-api/rest-api-reference/material#material-json-object)

#### GET /:id/components

Generates: application/json

Returns all components which are assigned to this tag.

Response (200 OK): List of [Component JSON object](https://docs.roomle.com/rubens/rest-api/rest-api-reference/component#component-json-object)

#### GET /:id/parentTags

Generates: application/json

Returns all parent tags of this tag.

Response (200 OK): List of [Tag JSON object](#tag-json-object)

### Tag Connections

#### Tag Connections JSON object

An example for a Tags2Tags connection object.

```json
{
    "id": "products:product_beds",
    "parentTagId": "products",
    "tagId": "product_beds",
    "created": "2016-08-01T14:35:53.000Z",
    "updated": "2016-11-28T16:48:34.000Z",
    "sort": 5
}
```

Responses are usually wrapped in a meta object, which contains additional information about the response and may contain a single item or a list of items.

```json
{
    "tagConnection": <Tag Connection Object>
    "tagConnections": [
        <Tag Connection Object 1>,
        <Tag Connection Object 2>,
        ...
    ],
    "meta": {
        "lastUpdated": "2018-01-23T09:15:39.000Z",
        "cached": false,
        "total": <number of tagConnections>,
        "serverTime": "2019-03-14T12:29:08.549Z"
    }
}
```

**JSON Fields:**

* id
* tagId - the id of the parent tag
* childTagId - the id of the child tag
* created - date of creation
* updated - date of last update
* sort - optional sort index for ordering the child tags in this parent tag

#### GET /:id/tagConnections

Generates: application/json

Returns all tag connections (child tags) for this tag.

Response (200 OK): List of [Tag Connection Object](#tag-connection-object)

#### POST /:id/tagConnections/:tagId

Creates a new tag connection between a parent tag and child tag.

Accepts: application/json Generates: application/json

**Note**: Requires CMS context.

Body: [Tag Connection Object](#tag-connection-object)

Response (201 CREATED): Created [Tag Connection Object](#tag-connection-object)

#### PUT /:id/tagConnections/:tagId

Updates an existing tag connection between a parent tag and child tag.

Accepts: application/json Generates: application/json

**Note**: Requires CMS context.

Body: [Tag Connection Object](#tag-connection-object)

Response (200 OK): Updated [Tag Connection Object](#tag-connection-object)

#### DELETE /:id/tagConnections/:tagId

Deletes a tag connection between a parent tag and child tag.

**Note**: Requires CMS context.

Response (204 NO CONTENT): deleted

### Item Connections

#### Item Connections JSON object

An example for a Tags2Items connection object.

```json
{
    "id": "products_roomle_white_furniture:door",
    "tagId": "products",
    "itemCombinedId": "roomle_white_furniture:door",
    "created": "2016-08-01T14:35:53.000Z",
    "updated": "2016-11-28T16:48:34.000Z",
    "sort": 5
}
```

Responses are usually wrapped in a meta object, which contains additional information about the response and may contain a single item or a list of items.

```json
{
    "itemConnection": <Item Connection Object>
    "itemConnections": [
        <Item Connection Object 1>,
        <Item Connection Object 2>,
        ...
    ],
    "meta": {
        "lastUpdated": "2018-01-23T09:15:39.000Z",
        "cached": false,
        "total": <number of itemConnections>,
        "serverTime": "2019-03-14T12:29:08.549Z"
    }
}
```

**JSON Fields:**

* id
* tagId - the id of the tag
* itemCombinedId - the combined id of the item (catalogId:itemId)
* created - date of creation
* updated - date of last update
* sort - optional sort index for ordering the items in this tag

#### GET /:id/itemConnections

Generates: application/json

Returns all item connections for this tag.

Response (200 OK): List of [Item Connection Object](#item-connection-object)

#### POST /:id/itemConnections/:itemCombinedId

Creates a new connection between a tag and an item.

Accepts: application/json Generates: application/json

**Note**: Requires CMS context.

Body: [Item Connection Object](#item-connection-object)

Response (201 CREATED): Created [Item Connection Object](#item-connection-object)

#### PUT /:id/itemConnections/:itemCombinedId

Updates an existing connection between a tag and an item.

Accepts: application/json Generates: application/json

**Note**: Requires CMS context.

Body: [Item Connection Object](#item-connection-object)

Response (200 OK): Updated [Item Connection Object](#item-connection-object)

#### DELETE /:id/itemConnections/:itemCombinedId

Deletes a connection between a tag and an item.

**Note**: Requires CMS context.

Response (204 NO CONTENT): deleted

#### POST /:id/pngIcon

**Deprecated since 2.49.0 - February 2025** - Use [PUT /:id (multipart)](#put-id-multipart) with type "pngIcon" instead.

#### POST /:id/svgIcon

**Deprecated since 2.49.0 - February 2025** - Use [PUT /:id (multipart)](#put-id-multipart) with type "svgIcon" instead.

#### POST /:id/inspirationImage

**Deprecated since 2.49.0 - February 2025** - Use [PUT /:id (multipart)](#put-id-multipart) with type "inspirationImage" instead.