content
Contents
Push a new piece of content to the Sailthru Content Library or update the metadata of an existing piece of content.
The content API is the preferred method for passing content to Sailthru 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 Sailthru’s 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 Content in Sailthru 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
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{
"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{
"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"
}
By URL
{
"key": "url", //unneeded but supported; default key type is url
"id": "http://example.com/product",
[add/update parameters here]
}
Show legacy method{
"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]
}
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 to Sailthru 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:
Note: |
"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
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 |