# Tags API * [Properties](#tags-properties) * [GET /api/tags](#GET-/api/tags) * [POST /api/tags](#POST-/api/tags) * [GET /api/tags/:tagId](#GET-/api/tags/tagId) * [GET /api/tags/:tagId/summaries](#GET-/api/tags/tagId/summaries) * [PUT /api/tags/:tagId](#PUT-/api/tags/tagId) * [DELETE /api/tags/:tagId](#DELETE-/api/tags/tagId) ## Tags Tags allow content to be categorized and filtered for better curation. They are more like blog tags or product swing tags and are not to be confused with hashtags. It is a form of profiling Social Tiles for grouping/association purposes. ### Properties | Field | Type | Value | POST | PUT | Definition | | --------------------- | --------- | ------------------------------------------------------------------------------------------------- | ----- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | integer | | **X** | **X** | Unique identifier for the Tag. **Example Values**: `12345` | | tag | tag | | ✔ | ✔ |

post: Required

Name and display title on the Tag.

Example Values: Editor's choice

| | slug | string | | ✔ | ✔ |

post: Required if custom\_slug is 0

Simplified and class-name-fiendly Tag identifier, most often auto-generated. On output this value is often used to set the class.

Example Values: editors-choice

| | custom\_slug | bool |

1 (true)
0 (false)

| ✔ | ✔ |

This value specifies if the slug field value is being auto-generated or overwritten by the user.

Example Values: 0

| | type | enum |

content
product
competition

| ✔ | ✔ |

post: Required

Specifies the type of the Tag

Example Values: content

| | publicly\_visible | bool |

1 (true)
0 (false)

| ✔ | ✔ |

post: Required

This value specifies if display renderers should display this Tag in display context

Example Values: 1

| | target | enum |

\_blank
\_self
\_parent
\_top

| ✔ | ✔ |

When rendered as a link, this will indicate the target attribute for the anchor tag when used with custom\_url

Example Values: \_blank

| | system\_tag | bool |

1 (true)
0 (false)

| **X** | **X** |

Indicates whether this Tag is a read-only tag created and managed by the system.

Example Values: 1

| | priority | integer | 1 (highest) - 5 (lowest) | ✔ | ✔ |

Specifies the sequential sort order in which this Tag should be displayed when being rendered for display. Default values is 3

Example Values: 3

| | custom\_url | string | | ✔ | ✔ |

URL that clicking on the Tag should take the user to. When type is product, this is the URL that the product click-through should be linked to

Example Values:

| | price | string | | ✔ | ✔ |

User provided price for Tags of type product.

Example Values: $399

| | ext\_product\_id | string | | ✔ | ✔ |

User provided reference to external product for Tags of type product. Should be a continous string, best if URL-friendly. When querying for a product by ID, this value can be prefixed with ext: to fetch by it.

Example Values: PROD-1234

| | description | string | | ✔ | ✔ |

User provided description for Tags of type product. Maximum length: 512 characters

Example Values: Long sleeve woven swing dress in animal print with roll neck and back zip fastening. 87cm length. 100% Viscose. Machine washable.

| | image\_small\_url | string | | ✔ | ✔ |

URL of the small (optimised for 300px x 300px) image PNG/JPG/JPEG/GIF image to be displayed. This should be a HTTPS URL to so that the Stack or widget can be served over HTTPS completely

Example Values:

| | image\_small\_width | integer | | ✔ | ✔ |

Width of the small image being used as the image\_small\_url, in pixels

Example Values: 250

| | image\_small\_height | integer | | ✔ | ✔ |

Height of the small image being used as the image\_small\_url, in pixels

Example Values: 200

| | image\_medium\_url | string | | ✔ | ✔ |

URL of the medium (optimised for 600px x 600px) image PNG/JPG/JPEG/GIF image to be displayed. This should be a HTTPS URL to so that the Stack or widget can be served over HTTPS completely

Example Values:

| | image\_medium\_width | integer | | ✔ | ✔ |

Width of the small image being used as the image\_medium\_url, in pixels

Example Values: 500

| | image\_medium\_height | integer | | ✔ | ✔ |

Height of the small image being used as the image\_medium\_url, in pixels

Example Values: 400

| | created\_at | timestamp | | **X** | **X** |

UTC timestamp of when this Tag was created

Example Values: 1372057752

| [Back to Top](#top) ### GET tags Retrieves all tags available in the Stack. #### Resource URL `https://api.stackla.com/api/tags` #### Resource Details Rate limited: Yes Access scope: User #### Request Parameters | Name | Mandatory | Request type | Description | | ------- | --------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | keyword | No | query | Keyword to search Tag ID, Name, Slug, External URL and External Product ID (prefixed with "ext:"). **Example Values**: `12345`, `ext:PROD-1234`, `my tag` | | type | No | query |

Comma-separated of type of tags to be derived. One or more of content, product, competition, system.

Example Values: content, product

| | page | No | query | Page number. Default value is 1 | | limit | No | query | Return limit define how many Tags will be return for each request. Default is 25. Maximum limit is 100. | [Back to Top](#top) ### POST tags Creates a new Tag in the Stack. #### Resource URL `https://api.stackla.com/api/tags` #### Resource Details Rate limited: Yes Access scope: User #### Request Parameters No additional request parameters are available. [Back to Top](#top) ### GET tags/:tagId Retrieves a specific Tag available in the Stack by its ID. #### Resource URL `https://api.stackla.com/api/tags/:tagId` #### Resource Details Rate limited: Yes Access scope: User #### Request Parameters | Name | Mandatory | Request type | Description | | ----- | --------- | ------------ | -------------------------------------------------------------------------------------------------------------- | | tagId | Yes | endpoint | ID of the Tag, or its External Product ID (prefixed with "ext:"). **Example Values**: `12345`, `ext:PROD-1234` | [Back to Top](#top) ### GET tags/:tagId/summaries Retrieves aggregated data of a specific Tags by its ID. #### Resource URL `https://api.stackla.com/api/tags/:tagId/summaries` #### Resource Details Rate limited: Yes Access scope: User #### Request Parameters | Name | Mandatory | Request type | Description | | ----- | --------- | ------------ | -------------------------------------------------------------------------------------------------------------- | | tagId | Yes | endpoint | ID of the Tag, or its External Product ID (prefixed with "ext:"). **Example Values**: `12345`, `ext:PROD-1234` | [Back to Top](#top) ### PUT tags/:tagId Updates a specific Tag available in the Stack by its ID. #### Resource URL `https://api.stackla.com/api/tags/:tagId` #### Resource Details Rate limited: Yes Access scope: User #### Request Parameters | Name | Mandatory | Request type | Description | | ----- | --------- | ------------ | -------------------------------------------------------------------------------------------------------------- | | tagId | Yes | endpoint | ID of the Tag, or its External Product ID (prefixed with "ext:"). **Example Values**: `12345`, `ext:PROD-1234` | [Back to Top](#top) ### DELETE tags/:tagId Deletes a specific Tag available in the Stack by its ID. #### Resource URL `https://api.stackla.com/api/tags/:tagId` #### Resource Details Rate limited: Yes Access scope: User #### Request Parameters | Name | Mandatory | Request type | Description | | ----- | --------- | ------------ | -------------------------------------------------------------------------------------------------------------- | | tagId | Yes | endpoint | ID of the Tag, or its External Product ID (prefixed with "ext:"). **Example Values**: `12345`, `ext:PROD-1234` | [Back to Top](#top)