Items API

The Items API allows you to manage your item catalog in real-time.

Specifications

Add a new item to the catalog.

POST /{environment}/items/{item_type}

Parameters

Type Name Schema

Path

environment
required

string

Path

item_type
required

string

Body

body
optional

Responses

HTTP Code Description Schema

200

The item was succesfully inserted

No Content

401

Access token is missing or invalid

No Content

415

The item information provided does not match the item information specification

No Content

422

The body is not of the right type, JSON expected

No Content

Consumes

  • application/json

Tags

  • env

cURL Example

$ curl --location --request POST 'https://{customer_token}.froomle.com/api/{environment}/items/{item_type}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X' \
--data-raw '{
  "item_id": "client_item_id_001",
  "environment": "environment_1",
  "categories": [
    "category_1",
    "category_1_1",
    "category_2",
  ],
  "title": "Froomle title",
  "images": [
    "https://www.froomle.com/content/client_item_id_001.jpg",
    "https://www.froomle.com/content/client_item_id_001_2.jpg"
  ],
  "uri": "https://www.froomle.com/client_item_id_001",
  "tags": [
  	"has_image:true",
  	"has_thumb:true",
    "companies:Froomle",
    "people:Solution Architect",
    "locations:Antwerp"
  ],
  "item_attributes": {
    "content_full_width": false,
    "disableAd": false,
    "payment": false
  },
  "item_type": "article"
}'

Add or update an new or existing item to the catalog.

PUT /{environment}/items/{item_type}/{item_id}

Parameters

Type Name Schema

Path

environment
required

string

Path

item_type
required

string

Path

item_id
required

string

Body

body
optional

Responses

HTTP Code Description Schema

200

The item was succesfully updated

No Content

401

Access token is missing or invalid

No Content

404

The item id is not yet known in the system

No Content

415

The item information provided does not match the item information specification

No Content

422

The body is not of the right type, JSON expected

No Content

Consumes

  • application/json

Tags

  • env

cURL Example

$ curl --location --request PUT 'https://{customer_token}.froomle.com/api/{environment}/items/{item_type}/client_item_id_001' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X' \
--data-raw '{
  "item_id": "client_item_id_001",
  "environment": "environment_1",
  "categories": [
    "category_1",
    "category_1_1",
    "category_2",
  ],
  "title": "Froomle title",
  "images": [
    "https://www.froomle.com/content/client_item_id_001.jpg",
    "https://www.froomle.com/content/client_item_id_001_2.jpg"
  ],
  "uri": "https://www.froomle.com/client_item_id_001",
  "tags": [
  	"has_image:true",
  	"has_thumb:true",
    "companies:Froomle",
    "people:Solution Architect",
    "locations:Antwerp"
  ],
  "item_attributes": {
    "content_full_width": false,
    "disableAd": false,
    "payment": false
  },
  "item_type": "article"
}'

Delete an item from the catalog

DELETE /{environment}/items/{item_type}/{item_id}

Parameters

Type Name Schema

Path

environment
required

string

Path

item_type
required

string

Path

item_id
required

string

Responses

HTTP Code Description Schema

200

The item was succesfully disabled

No Content

401

Access token is missing or invalid

No Content

404

The item id is not yet known in the system

No Content

Tags

  • env

cURL Example

$ curl --location --request DELETE 'https://{customer_token}.froomle.com/api/{environment}/items/{item_type}/client_item_id_001' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X'

Enable the item, can be used to reenable a previously disabled item.

POST /{environment}/items/{item_type}/{item_id}/enable

Parameters

Type Name Description Schema

Path

environment
required

The environment for which you want to enable an item

string

Path

item_type
required

The item_type of the item to be enabled

string

Path

item_id
required

The item to enable

string

Responses

HTTP Code Description Schema

200

OK

No Content

400

Error in the request

No Content

500

Error in processing the request

No Content

cURL Example

$ curl --location --request POST 'https://{customer_token}.froomle.com/api/{environment}/items/{item_type}/client_item_id_001/enable' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X'

Disable the item, disabling an item means it won’t be recommended again, but its data can still be used for model training.

POST /{environment}/items/{item_type}/{item_id}/disable

Parameters

Type Name Description Schema

Path

environment
required

The environment for which you want to disable an item

string

Path

item_type
required

The item_type of the item to be disabled

string

Path

item_id
required

The item to disable

string

Responses

HTTP Code Description Schema

200

OK

No Content

400

Error in the request

No Content

500

Error in processing the request

No Content

cURL Example

$ curl --location --request POST 'https://{customer_token}.froomle.com/api/{environment}/items/{item_type}/client_item_id_001/disable' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X'

Definitions

Item

The body of the create POST and update PUT requests, as well as the return value of GET requests.

Name Description Schema

categories
optional

The relevant of the categories of the item.

< string > array

environment
required

The environment in which the item will reside

string

images
optional

< object > array

item_attributes
optional

item_id
required

The identifier of the item

string

item_type
required

The type of the entity (e.g. item, article, video, …). These types are Froomle-defined, please consult your solutions architect for the correct type.

enum ({item_type})

language
optional

string

tags
optional

< string > array

title
optional

string

uri
optional

string


ItemAttribute

Information that might be relevant for analysis, but not for the filtering of the recommendations.

Name Schema

name
optional

string

value
optional

object