Content API

Article author
Mike Matcke
  • Updated

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.

site_Search.png

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.

Mobile.jpg

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.

Stream 9b.png

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.

Macbook Pro 16.png

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:

content_api_explorer.jpg

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 “} }”.

syntax_highlighting.jpg

Once the error has been fixed, the editor will clear the error notice.

editor_no_errors.jpg

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.

editor_prettify.jpg

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)
  • description (the description of the asset)
  • content_type (the type of asset - either video or photo)
  • creation_date (the date the content was created)
  • products (an array of product objects)
    • product_id (the 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
    • Note: Depending on your account configuration you may or may not have custom attributes
  • 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)

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.

See Example

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.

See Example

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 {
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: { code: "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

Search the titles of your content to find matches:

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

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:

{
    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.