content

Push a new piece of content to the Content Library or update the metadata of an existing piece of content.

The content API is the preferred method for passing content for both retailers and publishers, as you're able to update article or item information, such as inventory, in realtime. As an alternative, some publishers opt to enable the spidering functionality of the onsite JavaScript, which logs pages to the Content Library the first time each page is accessed, including metadata from the page. For more information, see Conten and Use Feeds and Other Content Data in Templates.

Endpoint URL: https://api.sailthru.com/content

GET Mode

Examples

Get by URL

{
 "url" : "http://example.com/path/product123.html"
}

Get by SKU

{
 "id":"123abc",
 "key":"sku"
}

Get Most Recent

{
"items":30
}

Optional Parameters

Parameter Description Example
id An identifier for the item (by default, the item's URL). http://example.com/product
key url or sku, to specify which identifier is being referenced in the id field. If unspecified, the default is url. ABC123
url For backward compatibility with an earlier version of the content API, you can reference an item by its URL using the url parameter. It is recommended that you instead use the id parameter to specify the URL. http://example.com/product
items If you have not specified a specific item id or url, this is the number of items to return, in order of recency. When not provided, the default is 20. 3

Return Value

Will return a data structure containing the content's metadata. If the url parameter is not provided, returns the 20 most recent pieces of content.
Note: Calls requesting more than 20,000 content items are not supported and may result in an error.

POST Mode

When you create the content item, the URL is required, though an SKU can also be submitted as a secondary key. For future POST updates on the same item, either the URL or SKU can be used to reference it.

Examples

Create a Content Item

With URL

{
    "key": "url", //unneeded but supported; default key type is url
    "id": "http://example.com/product",
    [optional parameters e.g. "title" here]
}
Show legacy method
Future support of this method may be limited:
{
    "url": "http://example.com/product",
    [optional parameters e.g. "title" here]
}

With URL & Additional Keys

{
    "key": "url", //unneeded but supported; default key type is url
    "id": "http://example.com/product",
    "keys": {
        "sku": "123abc"
    },
    [optional parameters e.g. "title" here]    
}
Show legacy method
Future support of this method may be limited:
{
    "url": "http://example.com/product",
    "keys": {
    "sku": "123abc"
    },
    [optional parameters e.g. "title" here]
}

Product Example

{
    "id": "http://example.com/product",
    "key": "url",
    "keys": {
        "sku": "123abc"
    },
    "title": "Product Name Here",
    "description": "Product info text goes here.",
    "price": 2099,
    "inventory": 42,
    "date": "2016-06-20 14:30:00 -0400",
    "tags": "blue, jeans, size-m",
    "vars": {
        "var1": "var 1 value"
    },
    "images": {
        "full": {
            "url": "http://example.com/images/product.jpg"
        }
    },
    "site_name": "Store"
}

Media Example

{
    "id": "http://example.com/article",
    "key": "url",
    "title": "Belichick named top coach in the NFL",
    "description": "Bill Belichick honored for role leading New England Patriots.",
    "date": "2016-06-20 14:30:00 -0400",
    "tags": "sports, football, nfl, new-england-patriots",
    "images": {
        "full": {
            "url": "http://example.com/images/story.jpg"
        }
    },
    "author": "Neil Smith"
}
Update a Content Item

By URL

{
    "key": "url", //unneeded but supported; default key type is url
    "id": "http://example.com/product",
    [add/update parameters here]
}
Show legacy method
Future support of this method may be limited:
{
    "url": "http://example.com/product",
    [add/update parameters here]
}

By URL to Add/Update SKU

{
    "key": "url", //unneeded but supported; default key type is url
    "id": "http://example.com/product",
    "keys": {
        "sku": "123abc"
    }
}

By SKU

{
    "key": "sku",
    "id": "123abc",
    [add/update parameters here]
}
Override Content Spidering Rules

By URL

{
     "key": "url",     
     "id": "http://example.com/excluded",
     "title": "Something That Doesn't Pass Spider Rules",
     "override_exclude": 1
}

Conditionally Required Parameters

Parameter Description Example
id An identifier for the item (by default, the item's URL). http://example.com/product
key url or sku, to specify which identifier is being referenced in the id field. If unspecified, the default is url. When you are creating an item, the key, if present, must be set to url. When you are updating an item, you can set the key to url or sku. ABC123
url For backward compatibility with an earlier version of the content API, you can reference an item by its URL using the url parameter. It is recommended that you instead use the id parameter to specify the URL. http://example.com/product

Optional Parameters

Parameter Description Example
keys Add or update the content's identifiers with an array specifying the key type and its value. Note: Currently, only sku is supported in the keys parameter; url is a key that cannot currently be changed. "keys": {"sku": "123abc"}
title The human-friendly title of the content Name of Product
date The created time of the content (if not provided, defaults to current time) 2012-09-20 14:30:00 -0400
expire_date Day the content should expire. Once this date is reached the content will not be recommended. Note: Scout and Concierge are also limited by the "date" parameter in conjunction with the "Hours Back" settings on your settings page. 2012-12-22 00:00:00 -0400
tags A list of tags applicable to the content blue, jeans, size-m
vars Any number of arbitrary variables to store for later use {"color":"blue","category":"men"}
images A map of image types full and thumb to objects specifying the URL for each image. Use the name "full" to denote the full-sized image, and "thumb" to denote the thumbnail-sized image. {"full" : { "url" : "http://example.com/f.jpg" }, "thumb" : { "url" : "http://example.com/t.jpg" } }
location Pass [latitude,longitude] to specify location of the content [40.697299,-74.003906]
price For pieces of content with a purchase value, this param should be used for the local price of the product, measured in cents. For example, a product that costs $172.99 should have price= 17299 14099
inventory Update current stock level for the product. Must be 0 or a positive integer. The stock record will decrement automatically as a result of Purchase API calls. 42
description Can be used for a brief summary-type description of the content A sentence or two that describes the content item.
site_name The name of the site that the content belongs to (useful for multiple brands) Publisher Site
author The name of the author of the piece of content Jane Doe
spider Pass 1 to force a respidering of the content within a few minutes 1
override_exclude By default, the content API filters content based on the URL Include and Exclude rules you set (https://my.sailthru.com/settings/spider). To pass content that violates your spidering rules, override the filter with this optional parameter. 1
availability The availability of a product. This can be one of the following:
  • "in stock"
  • "in_stock"
  • "out of stock"
  • "out_of_stock"
  • "preorder"
  • "backorder"
Note: "in_stock" and "out_of_stock" will be stored on the system side with spaces instead of underscores. They will also be returned with spaces replacing the underscores.
"in_stock"
sale_price For pieces of content with a purchase value, this param should be used for the sale price of the product, measured in cents. For example, a product with a sale price of $145.99 should have sale_price= 14599 14599

Return Value

Will return a data structure for the content containing all of the fields above. Note: If you push content via this call and it is not restricted by the URL Include/Exclude rules you applied, you can opt in by contacting Support or your CSM. To override a single request, pass "override_exclude": 1 as part of your request.

DELETE Mode

Remove a content item from the database, including all data associated with that content item. If you have the Personalization Engine JavaScript implemented, the URL will be re-spidered the next time a user accesses that URL.Note: To delete content in bulk, see the Job API endpoint's delete_content method.

Conditionally Required Parameters

Parameter Description Example
id An identifier for the item (by default, the item's URL). http://example.com/product
key url or sku, to specify which identifier is being referenced in the id field. If unspecified, the default is url. ABC123
url For backward compatibility with an earlier version of the content API, you can reference an item by its URL using the url parameter. It is recommended that you instead use the id parameter to specify the URL. http://example.com/product

Contact us

Top