Examples

This article provides examples of how to query, sort, and filter results using the Content API.

This section of the documentation provides examples that show you how to query the API for content, filter the results and sort the results. Additionally, there are some more advanced query examples that show you how to query the API for content by creator, product or campaign.

In most of the below examples, you will see a limited number of data fields requested to keep the queries simple and easy to follow. You can always add more data to your queries from the full data definition.

Querying for content

The first and most basic example of using the content API is to simply request some content. By default the API will return both videos and photos.

{
    content {
        items {
            content_id
        }
    }
}

Request only video content

{
    content(
        filter: {
            content_type: video
        }
    ) {
        items {
            content_id
        }
    }
}

Request only photo content

{
    content(
        filter: {
            content_type: photo
        }
    ) {
        items {
            content_id
        }
    }
}

Paging

Changing pages and page size. By default, page = 1 and page_size = 10. Maximum page size = 500.

{
    content(
        filter: {
            content_type: video
        },
        page: 3,
        per_page: 20
    ) {
        items {
            content_id
        }
    }
}

Sorting content

Content can be sorted using 3 methods:

• Sort by most recent (the newest content on top)
• Sort by most viewed (the content that has the most views)
• Sort by highest converting (the content that resulted in the most product sales)

Most recent:

{
    content(
        sort: [
            { name: creation_date, direction: desc}
        ]
    ) {
        items {
            content_id
        }
    }
}

Most viewed:

{ 
    content( 
        sort: [ 
            { name: engagement, direction: desc} 
        ] 
    ) { 
        items { 
            content_id 
        } 
    }
} 

Highest converting:

{ 
    content( 
        sort: [ 
            { name: conversion, direction: desc} 
        ] 
    ) { 
        items { 
            content_id 
        } 
    } 
}

Searching for content

When searching for content, the syntax supports 3 options:

term, mode, source

{
    content(
        filter: { 
            search: {
                term: "Text Search",
                mode: flexible,
                source: simple
            }
        }
    ) {
        items {
            content_id
        }
    }
}

Term option

The term option is simply that, the term you wish to search for. This can be a word or phrase.

{
   content(filter: { search: { term: "Text Search" } }) {
       items {
           content_id
       }
   }
}

Mode option

By default the search is “flexible”. You can pass the option mode: strict to create a strict search (see definitions below).

{
    content(
        filter: {
            search:
            {
                term: "Text Search"
                mode: strict
            }
        }) {
        items {
            content_id
        }
    }
}

A flexible search is a query that matches each term, except for the last term, which is matched as a prefix query.

A strict search is a query that matches exact phrases or word proximity matches, but does a wildcard search on the final word.

Source option

Search your content using source: extended to get more matches across the content's title, description and creator's name source fields. By default the option source: simple is used, which only searches the title field.

{
   content(filter: { search: { term: "Haley", mode: strict, source: extended}}) {
       total
       items {
           content_id
           title
           page_url
           creator {
               full_name
               uri_stem
           }
       }
   }
}

Searching for content by creator

Filtering content by a creator can be a 1 or 2 step process, based on the context of your query. In order to filter by a creator, you must first know that creator’s unique ID.

Step 1: Search for the creator’s name. This returns any creators who match the search AND have content.

Step 2: You can use the creator’s ID to get all content from that creator.

If you are running a query on your site and already know the creator’s ID, then you can skip right to Step 2 and fetch that content directly, no need to do a lookup first.

Search for a creator:

{
    creators(filter: { search: {term: "Text Search"} }) {
        items {
            creator_id
        }
    }
}

Search for that creator’s content by creator_id:

{
    content(
        filter: { creator_id: 123456 }
    ) {
        items {
            content_id
        }
    }
}

Searching for content by product

In order to filter by a product, you must first know that product’s unique ID.

Using the product’s ID, you can get all content that has been matched with the product.

Search for content that is matched to a product, by the Product's ID from the ecommerce store:

{
   content(filter:{ product_reference: "8223198773570"}) {
       total,
       items {
           content_id
           title
           products {
               title
               reference_id
           }
       }
   }
}

Searching for content by search tag

Search tags are an excellent way to make specific keywords or phrases searchable on the API. As creators produce content they can tag that content with a predefined search tag or this can be done by you in a moderated manner.

Once content has been tagged, you can then create an experience that allows a consumer to search and see tags that match their input. Upon selecting one of these tags, they can then see all of the content that was matched with that search tag.

Step 1: Receive user input (example a content search query “shoe”).

Step 2: Query the API to return matching search tags and display them to the user.

Step 3: User clicks on a specific search tag

Step 4: Query the API to return matching content for the selected search tag.

This lets a user browse through your tagged content in a highly specific and curated way.

Search for a specific search tag:

{
    search_tags(filter: { search: "Text Search" }) {
        items
    }
}

Search for content that is tagged with a search tag:

{
    content(
        filter: {
            search_tag: "gold"
        }
    ) {
        items {
            content_id
        }
    }
}

Content filters

Content can be filtered by content attributes or custom attributes. Below you will find a list of content filters supported by the Content API.

Campaign ID filter

Filter for content from a specific campaign. Useful for returning content that was created as part of a campaign.

{
  content(filter: { campaign_id: 123456 }) {
      total
      items {
          content_id
          title
      }
  }
}

Content ID filter

Filter for content by Content ID. Useful for retrieving a specific asset.

{
  content(filter: { content_id: 1234567890 }) {
      total
      items {
          content_id
          title
      }
  }
}

Content Type filter

Filter for content by type, either video or photo.

{
  content(filter: { content_type: video }) {
      total
      items {
          content_id
          title
      }
  }
}

Product filter

Filter for content by product. Provide the Product ID that in mapped to Creatable to return content that is matched to one of your products.

{
  content(filter: { product_reference: "bmw325i" }) {
      total
      items {
          content_id
          title
      }
  }
}

Tag filter:

Search the "tags" field of your content to filter content matches:

{
   content(filter: { tag: "renovation" }) {
       total
       items {
           content_id
           title
       }
   }
}

Custom content attribute filtering

Depending on how you have set up your account, you may have one or more custom content attributes. These attributes can be used to segment content for different purposes and enables a great deal of flexibility when it comes to selecting the right content for an experience.

For example, let’s say you want to flag specific pieces of content to be displayed on the homepage of your site in a carousel widget.

You would create a custom attribute (you can name this however you wish, but for this purpose we’ll call it “PDP Eligible”). Each piece of content that has “pdp_eligible” set to “Yes” will now be returned as a result.

The attributes for an item can be returned using the "attributes" parameter of the item as you can see below. The response from the query below will return an object containing all of the attributes for a given item.

{
    content(
        filter: {
            attribute: { code: "pdp_eligible" value: "yes"}
        }
    ) {
        items {
            content_id
               attributes(codes: ["pdp_eligible"]) {
               code
               value
           }
        }
    }
}

You can combine one or more custom attributes in your query to get the precise content for your needs.

Compound search filters

You can also query using more complex AND/OR rules for even more control over your queries. In all of the examples below "Filter N" refers to any of the above filters or searches.

AND

This allows you to combine one or more filters using the following syntax:

AND: [Filter 1, Filter 2, Filter 3]

OR

This allows you to combine one or more filters using the following syntax:

OR: [Filter 1, Filter 2, Filter 3]

NOT

This allows you to specific a negative filter "NOT" using the following syntax:

NOT: { Filter 1 }

The following is an example of a nested compound filter that can be useful in some cases:

{
    content(
        filter: {
            AND: [
                { attribute: { code: "pdp_eligible", value: "yes" } }
                { OR: [{ search: { term: "Dog" } }, { search: { term: "Cat" } }] }
            ]
        }
    ) {
        items {
            content_id
        }
    }
}

As you can see the AND / OR / NOT filtering capabilities are quite powerful when combined with searching and segmenting content.

Querying for Product Collections

Each Team creator has the ability to manage their own curated product collection. This data can be used to create a more personalized shopping experience for customers. Here is an example of how to retrieve a production collection via the Content API.

{
   product_collections(user_id: 000000, page: 1, per_page: 10) { 
      total, 
      items { 
         product_id,
         reference_id,
         title, 
         sale_price, 
         price
      }
   }
}

Have questions?

If you have any questions about how to use the Content API to search, sort or filter your content, please contact our support team.