TagController
Overview
Description
Path /v2/tags
Handles all requests regarding tags: creating, updating, deleting.
Tag JSON object
An example for a tag JSON object.
{
"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.
Query Parameters
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
Response (201 CREATED): Tag JSON object
GET /:id
Returns a specific tag.
Generates: application/json
Response (200 OK): Tag JSON object
PUT /:id (json)
Updates a specific tag. Assets needs to be uploaded explicitly (using PUT /:id (multipart)).
Accepts: application/json Generates: application/json
Body: Tag JSON object
Response (200 OK): Updated 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 with updated asset
For more information on the assets, please check ElementAssets
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
Links
GET /:id/items
Generates: application/json
Returns all items which are assigned to this tag.
Response (200 OK): List of Item JSON object
GET /:id/materials
Generates: application/json
Returns all materials which are assigned to this tag.
Query Parameters
embedTextures
Boolean
If true, embeds texture data in the response
false
Response (200 OK): List of 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
GET /:id/parentTags
Generates: application/json
Returns all parent tags of this tag.
Response (200 OK): List of Tag JSON object
Tag Connections
Tag Connections JSON object
An example for a Tags2Tags connection object.
{
"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.
{
"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
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
Response (201 CREATED): Created 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
Response (200 OK): Updated 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.
{
"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.
{
"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
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
Response (201 CREATED): Created 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
Response (200 OK): Updated 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) with type "pngIcon" instead.
POST /:id/svgIcon
Deprecated since 2.49.0 - February 2025 - Use PUT /:id (multipart) with type "svgIcon" instead.
POST /:id/inspirationImage
Deprecated since 2.49.0 - February 2025 - Use PUT /:id (multipart) with type "inspirationImage" instead.
Last updated