How Can We Help?

Items API

The Items API allows our partners to manage which items are recommended to users through the Personalization API. The Items API can be used to fetch or update properties of a given item, allowing you to disable items from appearing in recommendations with the click of a button in your Content Management System.

All API requests should be made to api-us.vidora.com, using the methods listed below. Note that authentication is required for each of these methods.

List Items

Returns a list of recent items ingested in your account, ranked by recency of ingestion. The response has a limit, but the method provides an optional filter to search for items by URL.

Request

Method URL
GET /v1/api/items

Parameters

Param Required? Value Description
limit No integer The number of items to return. Default limit is 100.
url No string The URL of an item to search for. This may be helpful if you do not know the item’s id.

Example Request

http://api-us.vidora.com/v1/api/items?api_key=<YOUR_KEY>&limit=1&expires=2018-0101T00%3A00&signature=<YOUR_SIGNATURE>

Example Response

[{
    "id": "abc-xyz",
    "disabled": false,
    "release_time": "2018-01-18T18:59:08.000Z",
    "title": "My Article Title",
    "url": "http://www.example.com/articles/abc-xyz"
}]

The above example makes a signed call to List Items to retrieve the most recently ingested item. The response includes details for item “xyz”, including whether or not the item is disabled, and its release_time, title, and url.

Get Item

Fetches details for a given item. The specific details depend on which metadata you send to Cortex in association with your items.

Request

Method URL
GET /v1/api/items/<ITEM_ID>

Parameters

Param Required? Value Description
<ITEM_ID> Yes string The unique id of the item for which you would like to fetch details.

Example Request

http://api-us.vidora.com/v1/api/items/<ITEM_ID>?api_key=<YOUR_KEY>&limit=1&expires=2018-0101T00%3A00&signature=<YOUR_SIGNATURE>

Example Response

{
    "id": "abc-xyz",
    "disabled": false,
    "release_time": "2017-01-18T18:59:08.000Z",
    "title": "My Article Title",
    "url": "http://www.example.com/articles/abc-xyz"
}

The above example makes a signed call to List Items to retrieve details about item “xyz”. The response includes details for item “xyz”, including whether or not the item is disabled, and its release_time, title, and url.

Update Item

Updates properties of a given item. As of now, the only property available for updating is the disabled flag. If the disabled flag for an item is updated to ‘true’, it will not be available for recommendation to your users.

Request

Method URL
PUT /v1/api/items/<ITEM_ID>

Parameters

Param Required? Value Description
<ITEM_ID> Yes string The unique id of the item that you would like to update.

POST Body Parameters

Param Required? Value Description
disabled Yes boolean Whether the item should be disabled or not.

Example Request

curl -H 'Content-Type: application/json' -X PUT -d '{"disabled":true}' http://api-us.vidora.com/v1/api/items/<ITEM_ID>?api_key=<YOUR_KEY>&expires=2028-0101T00%3A00&signature=<YOUR_SIGNATURE>

Example Response

{
    "id": "abc-xyz",
    "disabled": true,
    "release_time": "2017-01-18T18:59:08.000Z",
    "title": "My Article Title",
    "url": "http://www.example.com/articles/abc-xyz"
}

The above example makes a signed call to Update Item to set the “disabled” flag to true for item “xyz”, preventing it from being served by the Personalization API. The response includes updated details including whether or not the item is disabled, and its release_time, title, and url.

Response Codes

Response Description
200 OK The request was successful.
400 Bad Request The request was invalid, possibly due to malformed parameters.
401 Unauthorized The api_key and/or signature was invalid.
404 Not Found The id used in the request was not found or the request URI does not exist.
500 Internal Error There was a server side error, and we cannot serve the request at the current time.

Related Links

Still have questions? Reach out to support@mparticle.com for more info!

Table of Contents