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

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

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

Name
Type
Comment
Default

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.

PreviousStatisticsNextTenant

Last updated