Tags API Reference

Tags

Tags allow content to be categorised and filtered for better curation. They are more like blog tags or product swing-tags and 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

Unique identifier for the Tag.

Example Values:
12345

tag string

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)

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:
https://www.google.com.au/?q=stackla

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:
https://stackla.com/images/product_small.jpg

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:
https://stackla.com/images/product_medium.jpg

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

UTC timestamp of when this Tag was created

Example Values:
1372057752

Back to 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

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

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

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

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

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