Visual UGC Docs
Search
⌃K

Content

Overview

Visual UGC's Content API plugin provides a data rich endpoint, containing all respective Tile data in an easily consumable JSON format, which is optimised for fast delivery in front and backend integrations.

Usage

Key Features
  • Produces a simple JSON data structure.
  • Speed and robustness of content delivery.
  • Uses a simple URI query structure with default values to match Visual UGC's most common use-cases.
  • Prioritises cached data results with simple cache times; 3 or 6 minutes.
  • No API rate limits.
  • Open access via configurable CORS security headers.
Designed for
  • Powering content for websites and browser based apps.
  • Syncing content to external data stores.

Installing and configuring the Content API plugin

To use the content plugin, please contact your sales or customer success representative to ensure you have access to the feature. Once installed, follow the steps below.

Finding your plugin Unique identifier (Plugin ID)

The identifier {Plugin ID}and API Endpoint are generated when the Content API plugin is installed and configured in the Visual UGC admin portal.
  1. 1.
    Login to the Visual UGC admin portal.
  2. 2.
    On the sidebar, click "View all plugins".
  3. 3.
    Filter by Visual UGC plugins by clicking "Visual UGC" in the middle tab bar.
  4. 4.
    Click "Configure".

Content filters

By default, the Content API can be configured to output content from a specific filter. This is configured within the admin portal.
To output content from all filters, you can set the configured filter to latest (assuming this filter hasn't been customised). In this configuration, the Content API plugin can access any content within a Stack and, using tags, can target specific items or groups of items.
Dynamically setting the override filter to the ID of the latest filter when the tags parameter is used is a helpful method to ensure any content with those tags are returned, not just the content from the configured filter.
Your Stack's filter ID's can be found on the filter's page in your Stack admin portal. Click Curate > Filters on the side navigation bar.

Security

Access control

Each Content API plugin has a unique identifier, making each URL private by default.
Visual UGC's Content API is designed to be open to access and does not implement any access control mechanisms. Sharing the private URL, making it publicly known or using it within Javascript on a website will allow all the below requests to be made by anybody. Keep this in mind when designing integrations with this plugin.
NOTE: To generate a new unique identifier, the plugin will have to be reinstalled from within the Visual UGC admin portal.

Allowed domains

When making requests to the API in a browser via AJAX, a pre-flight HTTP OPTIONS request will be made to validate the Cross-Origin Resource Sharing (CORS) policy.
By default, the Access-Control-Allow-Origin response will allow all domains. e.g. *
A comma separated list of allowed domains can be configured in the plugin configuration page. Adding domains to this list will change the API's response to any pre-flight HTTP OPTIONS requests made by the browser to contain only the domain(s) specified.
NOTE: This does not restrict access to the Content API, or it's output. It simply limits its usage from within unauthorised websites using modern browsers built-in protections.
Read more about CORS here.

Example Requests

The following example requests illustrate some common use cases of the Content API, using the available request parameters.

Content Type

The Content API outputs data in the JSON format. Valid responses containing JSON will always include the HTTP header Content-Type: application/json. This should be used to validate the output of the Content API in case of an unexpected error (see below).

Available request parameters

Name
Text
Expected Value
limit
​
Integer
page
​
Integer
filter_id
​
Integer
tags
​
Comma separated string of tag IDs

Error handling

The Content API is designed to be robust as possible. It does not follow the REST API pattern or utilise HTTP error code conventions to communicate the state of the response.
The following rules are used to handle issues;
Invalid parameter names or values types will be ignored
  • The request will continue to process.
  • No 400 codes or error messages will be returned on invalid requests.
Valid parameter types with values outside the expected range will default to their _minimum_** values**
  • See expected ranges below.
There is no fallback/default content for filters or tags requests which return empty results
Some requests will still return HTTP errors
  • Requests using invalid plugin IDs will return a 404 page.
  • Service errors will still return 5xx errors.
  • Requests flagged as security violations may return 4xx errors.

Basic Requests

  • Configured filter can default to query all content, using thelatest filter ID.
  • Response data is always cached for 3 minutes based on query structure.
  • Limit range: 1-50 items.
  • Page range: 1-999 pages.

Default request

Return 50 items from the default filter configured in the admin portal.
https://plugins.stackla.com/content_api/{Plugin ID}

Limits & Pages

Return 10 items from configured filter.
https://plugins.stackla.com/content_api/{Plugin ID}?limit=10
Return 3 items from the second page (items 4, 5 & 6) from configured filter.
https://plugins.stackla.com/content_api/{Plugin ID}?limit=3&page=2

Complex Requests

  • Configured filter can default to query all content, using thelatest filter ID.
  • Response data is always cached for 6 minutes based on query structure.
  • Item range: 1-100 items.
  • Page range: 1-999 pages.
  • Tag limit: 0-20 tag IDs.
  • Filter limit: 0-1 filter IDs.

Limits & Pages

Return 100 items from configured filter.
https://plugins.stackla.com/content_api/{Plugin ID}?limit=100
Return 100 items from configured filter, starting at page 3 (items 300-400).
https://plugins.stackla.com/content_api/{Plugin ID}?limit=100&page=3

Override Default Filter with Custom Filter

Return 50 items from filter 123.
https://plugins.stackla.com/content_api/{Plugin ID}?filter_id=123
Return 75 items from filter 123.
https://plugins.stackla.com/content_api/{Plugin ID}?filter_id=123&limit=75

Override Default Filter with Custom Filter and tags

Return 50 items matching tags 123, 456 and 678 from filter 123.
https://plugins.stackla.com/content_api/{Plugin ID}?filter_id=123&tags=123,456,678
Return 10 items from the 10th page, matching tags 123, 456 and 678 from filter 123.
https://plugins.stackla.com/content_api/{Plugin ID}?filter_id=123&limit=10&page=10&tags=123,456,678

External Product tags

Note: External tags must use the ext: prefix to differentiate them from internal tag IDs. External tag IDs can be strings.
Return 30 items matching product tags using external ID abc123 from configured filter.
https://plugins.stackla.com/content_api/{Plugin ID}?limit=30&tags=ext:abc123
Return 50 items matching product tags using external ID abc123 and xyz987 from filter 123.
https://plugins.stackla.com/content_api/{Plugin ID}?filter_id=123&tags=ext:abc123,ext:xyz987
Previous
API Docs
Next
Google Analytics Widget Events
Last modified 2mo ago