Skip to main content
API docs by Redocly

Wyng Content API (2.0)

Download OpenAPI specification:Download

The Content API is based on RESTful API conventions. Clients are identified and authenticated using access tokens, and responses are in HAL+JSON format.

Authentication & Authorization

You can obtain an access token from the Wyng dashboard, under More > APIs. That panel allows you to generate and revoke tokens, and whitelist originating web page domain(s) for Cross-Origin Resource Sharing (CORS).

There are 2 classes of token:

  • READ-ONLY or "Content API" tokens allow read-only access, though potentially sensitive information (e.g. PII) will not be returned if accessed with a READ-ONLY token. READ-ONLY tokens may be safely embedded in front-end code.
  • READ-WRITE or "Tag API" tokens allow read-write access, to post content, add or remove tags, etc. and will return all available public and private data. These tokens provide full access to all content library data and must not be exposed publicly.

For security, all requests to these API endpoints must:

  1. Use a valid access token
  2. Use HTTPS / TLS 1.2+ encrypted transport
  3. If originating from web pages, originate from whitelisted domain(s)

Typical Server Responses

  • 200 OK - The request was successful.
  • 201 Created - The request was successful and resulted in a new resource being created.
  • 204 No Content - The request was successful.
  • 400 Bad Request - The request could not be understood or was missing required parameters.
  • 403 Forbidden - Access denied.
  • 404 Not Found - Resource was not found.
  • 405 Method Not Allowed - Requested method is not supported for the specified resource.
  • 422 Unprocessable Entity
  • 429 Too Many Requests - Exceeded API rate limit.
  • 503 Service Unavailable - The service is temporary unavailable due to scheduled maintenance or downtime. Try again later.

If after reading this documentation you still have questions, contact us at support@wyng.com.

Content Filters

Filters are designed to share content with consumers, external parties, vendors, or anyone else who are potentially untrusted. Filters allow you to create a view into your content, and choose which items to reveal and in what order without revealing search criteria publicly. Return syntax is consistent with Content Queries. Content Filters and Content Queries may be used interchangeably.

Create Filter

Create Filter

query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe

Requires a READ-WRITE access token.

Request Body schema: application/json

Post the necessary fields for the API to create a new filter.

q
required
string

Query string to use for filter

sort_by
required
string

Item ordering

name
required
string

Name of the filter

Responses

Request samples

Content type
application/json
{
  • "q": "campaign:0242ac120002",
  • "sort_by": "created_on:asc",
  • "name": "Product Images"
}

List Filters

query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe

Requires a READ-WRITE access token.

page
number
Example: page=1

page of filters

page_size
number <= 100
Example: page_size=10

number of filters to return

Responses

Response samples

Content type
application/json
{
  • "total_results": 1,
  • "_embeded": [
    ]
}

Update Filter

query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe

Requires a READ-WRITE access token.

filter_id
required
number
Example: filter_id=12345
Request Body schema: application/json
q
required
string non-empty
sort_by
required
string non-empty

Responses

Request samples

Content type
application/json
{
  • "q": "campaign:0242ac120002",
  • "sort_by": "created_on:desc"
}

List Filter Items

path Parameters
filter_uuid
required
string
query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe

Requires a READ-WRITE access token.

page
number
Example: page=1

Where in a stream of results to start

page_size
number
Default: 50
Example: page_size=3

Number of results to return from a single request

info
number
Example: info=1

If 1 returns data on the filter not content

seed
number
Example: seed=19

Used as the seed for a random sort. Only relevant if sort_by=random

sort_by
string
Example: sort_by=created_on:desc

Sort to override the default sort.

favorite_tag
string
Example: favorite_tag=star-ugc

Prioritize content items with a particular tag. Boosts matching documents to the top of the query results. Any sort_by parameter, if supplied, will act as a secondary sort.

additional_query
string
Example: additional_query=approval_status:app

Additional criteria to append to the filter query with an AND operator

Responses

Response samples

Content type
application/json
{}

Delete Filter

path Parameters
filter_uuid
required
string
query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe

Requires a READ-WRITE access token.

Responses

Content Queries

Queries are a flexible mechanism for retrieving content in your library matching specific criteria.

Some sample queries:

  • Find a specific content item: id:43992816
  • Find all images and videos that are pending or approved: content.content_type:(image,video) AND approval_status:(app,pen)
  • Find all approved items tagged with "shirts" approval_status:app AND tags.marketer_tags.key:shirts
  • Find all rejected items: approval_status:rej
  • Find content items with an attached conversion unit with sku 123456: activate_units.id:123456
  • Find tweets posted from Chicago social_platform:twitter AND content.platform_data.location.name:Chicago

The query syntax is Lucene-compatible and supports expressions like:

  • Full-text search: some words to search
  • Field contains: field:value
  • Field contains one of several values: title:(quick OR brown)
  • Field contains an exact value: author:"John Smith"
  • Field missing or has empty value: _missing_:title
  • Field has any non-empty value: _exists_:title
  • Ranges:
    • All days in 2012: date:[2012-01-01 TO 2012-12-31]
    • Last 30 days: date:[now-30d TO *]
    • Numbers 1..5 count:[1 TO 5]
    • Tags between alpha and omega, excluding alpha and omega: tag:{alpha TO omega}
    • Numbers from 1 up to but not including 5: count:[1 TO 5}
  • Booleans:
    • The preferred operators are + (this term must be present) and - (this term must not be present). All other terms are optional. For example, the query quick brown +fox -news states that:
      • fox must be present
      • news must not be present
      • quick and brown are optional — their presence increases the relevance

Some other things to keep in mind

  • Pagination: As content may be added at any time, paging may return some duplicate data
  • Date Added vs. Date Posted: Due to the behaviors of some social network APIs creation date of content may be later than original post date
  • Caching: for scalability, latency, and performance, all API endpoints are served from a CDN layer, and may return data that is a few minutes old
  • Access tokens: If you have access to multiple accounts in Wyng, be careful to use access tokens scoped for the property you intend to access
  • Wildcards: Wildcard queries are not indexed and will take much longer to execute than other query types; they must not be used for high volume cases

Query Content Items

query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe
page
number
Example: page=1

Where in a stream of results to start

page_size
number
Default: 50
Example: page_size=3

Number of results to return from a single request

sort_by
string
Example: sort_by=created_on:desc

Sort to override the default sort.

favorite_tag
string
Example: favorite_tag=star-ugc

Prioritize content items with a particular tag. Boosts matching documents to the top of the query results. Any sort_by parameter, if supplied, will act as a secondary sort.

q
required
string
Example: q=approval_status:app AND activate_units.id:123456

Query String

Responses

Response samples

Content type
application/json
{}

Add Content Item

Add a content item to library

query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe

Requires a READ-WRITE access token.

Request Body schema: application/json
content_url
string

url to image or video you want to add, optional if ugc_type is "text"

video_thumbnail
string

required if content type is video

content_type
required
string
Enum: "image" "video" "text"

Type of uploaded content

caption
string

caption, required if `ugc_type`` is text

content_ref
string

caption, required if `ugc_type`` is text

object

An object to store fields from a submission form used to upload the content. This data is assumed to contain PII and will only be returned to API calls using READ-WRITE tokens. If a username and email are provided, an author will be derived if it is not explicit.

object
object

Author data, ignored if submission is specified

approval_status
string
Default: "pen"
Enum: "app" "rej" "pen"

Approval status of the content (Approved, Rejected or Pending)

Responses

Request samples

Content type
application/json
{
  • "content_url": "https://example.com/cat.jpg",
  • "video_thumbnail": "https://example.com/cat.jpg",
  • "content_type": "image",
  • "caption": "My cute cat",
  • "content_ref": "My cute cat",
  • "submission": {
    },
  • "tags": {
    },
  • "author": {
    },
  • "approval_status": "app"
}

Tagging

Add Tag to Content Items

Finds or creates a tag with the given namespace and key, and uses it to tag one or more UGC items.

query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe

Requires a READ-WRITE access token.

Request Body schema: application/json

Post the namespace, key, and UGC item ID(s)

ugc_ids
required
Array of integers

List of content items which we want to tag

namespace
required
string

Namespace in which to add the tag

key
required
string

Value to apply to the tag, only lowercase letters allowed

Responses

Request samples

Content type
application/json
{
  • "ugc_ids": [
    ],
  • "namespace": "marketer_tags",
  • "key": "shirts"
}

Remove Tag from Content Items

Deletes a tag mapping from a single piece of content.

path Parameters
namespace
required
string
Example: marketer_tags

Namespace for search

key
required
string
Example: shirt

Key to search

ugc_id
required
string
Example: 43992816

UGC item ID to remove tag from

query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe

Requires a READ-WRITE access token.

Responses

Get Tag Info

Returns data on a tag including a list of content items with that tag.

Note: This endpoint may only be used for content management and other low volume use cases. For display and all high volume use cases, use /v2/content/items or /v2/content/filters endpoints instead.

path Parameters
namespace
required
string
Example: marketer_tags

Tag namespace

key
required
string
Example: shirt

Tag to remove

query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe

Responses

Response samples

Content type
application/json
{}

Get Tags associated with a content item

Returns a list of all tags associated with a specific content item.

Note: This endpoint may only be used for content management and other low volume use cases. For display and all high volume use cases, use /v2/content/items instead.

path Parameters
ugc_id
required
string
Example: 43992816

ID of a UGC item

query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe

Responses

Response samples

Content type
application/json
{}

Conversion Units

Conversion Units are actions that can be associated with content items, to drive purchase, signup, or other scenarios. Common Use-Cases involving Conversion Units:

  • Filtering UGC based on Conversion Unit
  • Categorizing UGC by Conversion Unit
  • Driving actions from custom UGC displays

List all conversion units

Get a list of all conversion units in the library

query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe

Responses

Response samples

Content type
application/json
{}

Get conversion unit

Get details for a conversion unit.

Note: This endpoint may only be used for content management and other low volume use cases. For display and all high volume use cases, use /v2/content/items or /v2/content/filters instead.

path Parameters
id
required
string
Example: 33173

ID of the Conversion Unit

query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe

Responses

Response samples

Content type
application/json
[]

UGC Item

Retrieve a single UGC item by id. Note: This endpoint is deprecated. Use /v2/content/items instead.

Get UGC Item Deprecated

Retrieve a single UGC item by id.

path Parameters
ugc_id
required
number
Example: 43992816

ID of the UGC item

query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe

Requires a READ or READ-WRITE access token.

Responses

Response samples

Content type
application/json
{}

UGC Collection

Retrieve UGC items collected by a single campaign. Note: This endpoint is deprecated. Use /v2/content/filters instead.

Get UGC Collection Deprecated

path Parameters
collection_id
required
number
Example: 16252

ID of your Content collection.

query Parameters
access_token
required
string
Example: access_token=lifUzxEAWau9VBhcqcOkinZtgyqQYe
page
number
Default: 1
Example: page=1

Page or offset within the content list

page_size
number <= 100
Default: 8
Example: page_size=10

Number of items returned per page

approval_status
string
Enum: "app" "rej" "pen"
Example: approval_status=app,rej,pen

Filters items by status defined under Curate.

Can include 1 or more comma-separated values

social_platform
string
Enum: "twitter" "vinetweet" "instagram" "facebook" "tumblr" "direct"
Example: social_platform=twitter,instagram

Filters items by social platform.

Can include 1 or more comma-separated values

claimed
string
Enum: "yes" "no"
Example: claimed=yes

Filters items by claimed status.

Can include 1 or more comma-separated values

order
string
Default: "random_sort"
Enum: "random_sort" "date_asc"
Example: order=date_asc

Sorts data in order desired

seed
string

A seed value for initializing random ordering, to ensure consistent pagination.

media_type
string
Enum: "video" "image" "text"
Example: media_type=video,image

Filters data by media type.

Can include 1 or more comma-separated values

has_activate_units
string
Enum: "yes" "no"
Example: has_activate_units=yes

Filters data by UGC with assigned conversion units.

Can include 1 or more comma-separated values

external_id
string

Filters items associated with a specific Conversion Unit identified by an external id.

activate_unit_id
string

Filters items associated with a specific Conversion Unit.

namespace
string

Filters items tagged with a specific namespace.

Must be combined with tags_required.

tags_required
string

Filters items tagged with a specific key.

Must be combined with namespace.

author_id
string

Filters items posted by a particular author.

e.g. Instagram or Twitter username.

Responses

Response samples

Content type
application/json
{}