.png?height=120&name=Creatable_logo_white%20(1).png){kind=logo}
Overview
The Creatable Content API is a powerful way to access your content and all related metadata, including creator data, product data, and campaign data.
Use case: Content in your site search
Enhance the search function of your website with Content and Creator results from the Creatable API. Creatable, through the relation of Content to Products generates a powerful Index that easily allows you to populate search results with creators and/or content for your product search results, or to populate creator and content specific search results for any search term.
Use case: Create a custom experience on your e-commerce site
Create a custom, shoppable experience on your site that enables your customers to engage with the content and/or creator most likely to positively influence their purchase decision regardless of who they are, or where they are in your funnel. Experiences can be populated with all available product, content, and creator metadata, which is accessible through the Creatable API via any matched product, content, or creator data.
Use case: Content on your PDP
Optimize conversion on your product pages with the Creatable Content API by dynamically surfacing the content most likely to lead to a sale for each product. Integrate content seamlessly to meet your brand guidelines and ensure that it is easily accessible to all customers at the moment they need it most to positively influence buying decisions. For a non-developer method of getting content on to your PDP, see our article on PDP widgets.
Use case: Searching on your gallery
Enhance your content search results by enabling industry and/or brand specific search results on your Gallery through brand-customizable search tags. These tags allow your customers to easily browse creators and content through both high level product search terms as well as search terms and marketing tags specific to your business.
Use Case: Data-driven Intelligence
Utilize the Creatable API to sort and query content based on first party performance metrics (see data dictionary for all metrics generated on the Creatable platform). Ensure that the highest performing content (by engagement, conversion, etc.) is surfaced for any given scenario.
Getting Started
Our Content API is available to all brand clients and can be accessed via the platform. From the main navigation menu, towards the bottom, click on Content API Explorer. 🪄Magic! 🪄
When you initially open the explorer, you’ll see something like this:
There are 2 buttons at the top. Documentation is what you are reading now and Examples are for anyone who is too impatient to read any further.
The explorer is unique to your account, if you notice the API URL in the explorer, that is specific for you.
The left panel is your working area, where you can construct, test and troubleshoot queries to the API.
The right panel is your results area. This is where you will see data responses or error messages based on your query from the left panel.
To execute a query, paste or write it into the left panel, then hit the PLAY button in between both panels.
The tabs at the top allow you to work with many queries at the same time without having to lose any work.
For convenience, you can click “COPY CURL” and this will allow you to paste a command into a standard unix/linux terminal to execute the query to our API using a generic CURL command.
Error handling
There are 2 kinds of errors that you may encounter when using the explorer.
The first kind is a basic syntax error, meaning that the query in the left panel is somehow misconstructed. This is generally easy to fix and the error will be highlighted in red, on the left side of the row where the error exists. If you hover over the portion of the query statement, there will be a hint about the problem. In this case, the editor can see that this query is missing 2 closing curly brackets “} }”.
Once the error has been fixed, the editor will clear the error notice.
If you’ve been making a lot of edits to your query and it is syntactically correct, but looks like a mess, you can select the whole query and click the button “PRETTIFY” and it will make your query look much better.
The second kind of error you may receive is if your query is syntactically correct, but the format is not understood by the schema of the API. The solution for this may require some additional help, so please feel free to reach out to our support team for assistance.
Data definitions
This section of the documentation covers all of the data fields that can be returned by the API as well as defines the filtering capabilities exposed in the API for selecting the right content for the right experience.
Content data structure:
- content_id (the unique ID of the asset)
- title (the title of the asset)
- reference_id (the shared unique ID of the asset)
- description (the description of the asset)
- content_type (the type of asset - either video or photo)
- creation_date (the date the content was created)
- modified_date (the date the content was last modified)
- tags (comma separated string of keywords/phrases, returned as an array)
- products (an array of product objects)
- product_id (the unique ID of the product)
- reference_id (the shared unique ID of the product)
- title (the title of the product)
- link (the link to the product page on your ecommerce site)
- image (the thumbnail image of the product)
- price (the price of the product)
- sale_price (the sale price of the product, if provided)
- attributes(codes:["custom_attribute_code1", "custom_attribute_code2"])
- code (the code of the custom attribute)
- value (the stored value)
- creator
- creator_id (the unique ID of the creator)
- first_name (the first name of the creator)
- last_name (the last name of the creator)
- full_name (the full name of the creator)
- thumbnail (the profile image of the creator)
- uri_stem (the path the creator's storefront if it exists)
- asset
- Object of asset information based on type (video, photo or youtube), see example below.
Here is an example of a query that will return a "kitchen sink" of data to work with, as an example:
{
content {
items {
content_id
title
reference_id
modified_date
creation_date
page_url
uri_stem
products {
product_id
title
link
}
attributes(codes: ["hide_from_grid"]) {
code
value
}
asset {
asset_type
photo {
sources {
height
width
url
}
}
video {
sources {
hls
dash
mp4 {
height
width
url
}
}
thumbnails {
height
width
url
}
cc {
label
lang
url
default
}
transcript
}
youtube {
youtube_id
height
width
duration
thumbnail
youtube_url
}
}
}
}
}
Content filters
Content can be filtered by a search term, content attribute or custom attribute. A search term filter operates against the content’s title attribute.
{
content(filter: { search: { term: "Text Search" } }) {
items {
content_id
}
}
}
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.
Creator filters
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.
Product filters
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 tags
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.
See Example
Custom content attributes
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.
Additionally, you can also query using more complex AND/OR rules for even more control over your queries.
{
content(
filter: {
AND: [
{ attribute: { code: "pdp_eligible", value: "yes" } }
{ OR: [{ search: { term: "Dog" } }, { search: { term: "Cat" } }] }
]
}
) {
items {
content_id
}
}
}
Examples
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.
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
}
}
}
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
}
}
}
Filtering content
Content can be filtered by any content attribute (system provided or custom).
{
content(
filter: {
attribute: { codes: "pdp_eligible" value: "yes"}
}
) {
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
The "source" parameter can be used to explicitly define the field grouping that will be searched. You can choose from "simple" or "extended". By default the "simple" option is used.
Simple: When using the "simple" source, you are searching the title field from content.
Extended: When using the "extended" source, you are searching the title, description and creator's name, with priority for the title and creator's name.
Search the titles of your content to find matches (using "source: simple" by default):
{
content(filter: { search: { term: "Text Search" } }) {
items {
content_id
}
}
}
Search the "tags" field of your content to find content matches:
{
content(filter: { tag: "renovation" }) {
total
items {
content_id
title
page_url
tags
}
}
}
Search your content using "source: extended" to get more matches across the content's title, description and creator's name source fields.
{
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
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
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
}
}
}
}
Search for content that is matched to a product, explicitly by the product's ID in the platform:
{
content(
filter: {
product: 225633381
}
) {
items {
content_id
}
}
}
Searching for content by search tag
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
}
}
}
Support
For additional questions about how to use the API, please email support@creatable.io and we’ll do our best to answer your questions! In your email, please include any relevant queries from the Content API Explorer and your API request URL.
Frequently asked questions
Q: How do I get results in the API explorer?
A: Check out the Getting started section of this documentation, it explains how to use the explorer and provides a few example queries you can play around with. These queries may require additional input values in order to properly search or filter within your account, as every account is different. Also, if your account doesn’t have any content yet, then you won’t see any results.
Q: Can I use this API on my site?
A: Yes. This API was designed to be used on production websites that wish to display customized shoppable content experiences.