NAV Navbar
Logo
cURL

Introduction

The Rosetta API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors.

Authentication

To authorize, use this code:

curl -X GET \
  "https://api.rosetta.ai/engine" \
  -H "Authorization: Bearer meowmeowmeow"

Make sure to replace meowmeowmeow with your API token.

Authenticate your account when using the API by including your secret API token in the request. Your API token carry many privileges, so be sure to keep them secret! Do not share your secret API token in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API token as the basic auth username value. You do not need to provide a password.

Rosetta API expects for the API token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer meowmeowmeow

API requests without authentication will fail.

Versioning

Example Request

curl -X GET \
  "https://api.rosetta.ai/engine" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: Bearer meowmeowmeow"

Because we aren’t versioning the API in the URI we need to define an Accept header to request a specific version. The header is formatted like so.

Accept: application/vnd.dc-rosetta.v1+json

Especially, vnd.dc-rosetta is the subtype name of Rosetta API. It should be added in the Accept header like the above.

Following the subtype name we have the version we want. In the above example we’re requesting v1 of our API. This is then followed by a plus sign and the desired format. However, JSON is returned by all API responses, including errors. So, Accept header must define the json format.

Content Type

Example Request

curl -X GET \
  "https://api.rosetta.ai/engine" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: Bearer meowmeowmeow"

The PUT or PATCH method needs the Content-Type header, with the value application/x-www-form-urlencoded. Conveniently, we suggest you to add the header in each API request:

Content-Type: application/x-www-form-urlencoded

Pagination

Example Request

curl -X GET \
  "https://api.rosetta.ai/engine" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: Bearer meowmeowmeow" \

Example Response

{
  "meta": {
    "pagination": {
      "total": 48,
      "count": 10,
      "per_page": 10,
      "current_page": 2,
      "total_pages": 5,
      "links": {
        "previous": "https://api.rosetta.ai/engine?page=1",
        "next": "https://api.rosetta.ai/engine?page=3"
      }
    }
  },
  "data": [
    {
      "id": "100112002230006",
      "name": "My first engine",
      "type": "personalized rec",
      "description": null,
      "created_at": {
        "date": "2017-05-15 12:33:16.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2017-05-15 12:33:16.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      }
    },
    {
      "id": "100112026097891",
      "name": "popular",
      "type": "popular items",
      "description": "engine to provide recommendation of popular items",
      "created_at": {
        "date": "2017-05-15 12:33:20.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2017-05-15 12:33:20.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      }
    },
    {...},
    {...}
  ]
}

All top-level API resources have support for bulk fetches via “list” API methods. For instance, as an authenticated user with Authorization header, you can list engines, list entities, and list events. These list API methods share a common structure, taking one parameter: page.

See the example code to learn more about the response format of list. The pagination response format is as below:

Attributes

Parameter Description
total
integer		 the total number of the resources.
count
integer		 the amount of the data shown in current page.
per_page
integer		 the default amount of the data shown in each page.
current_page
integer		 the number of current page.
total_pages
integer		 the amount of pages.
links
object		 previous is the link of the previous page, if existing.
next is the link of the next page, if existing.

Errors

The Rosetta API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Stripe’s servers (these are rare).

HTTP Response Codes

Code Meaning
400 Bad Request – Your request sucks.
401 Unauthorized – Your API token is wrong or not authenticated.
403 Forbidden – The resource is hidden for administrators only.
404 Not Found – The specified resource could not be found.
405 Method Not Allowed – You tried to access a resource with an invalid method.
406 Not Acceptable – You requested a format that isn’t json.
410 Gone – The resource has been removed from our servers.
418 I’m a teapot
422 Unprocessable Entity – The request was well-formed but was unable to be followed due to semantic errors, such as validation fails.
429 Too Many Requests – You’re requesting too many kittens! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Input Data Format

Labels

Label Meaning
required The attribute is required.
recommended The attribute is recommended to have.
experiment The attribute is in experiment and only provides the effect for our cooperation customers. You can contact us for the further cooperation and remember to choose the radio button: Looking for business or techique cooperation.

User Attributes

Suggested Attribute Meaning
id
required
integer, or string 		Unique identifier of the user.
name
recommended
string 		The user’s full name.
first_name
string 		The user’s first name.
middle_name
string 		The user’s middle name.
last_name
string 		The user’s last name.
age
experiment
integer 		The user’s age.
birthday
experiment
date 		The user’s birthday. This is a fixed format string, like MM/DD/YYYY. However, due to sparse issue of data collection, this string can be only the year (YYYY) or the month + day (MM/DD)
gender
experiment
string 		The user’s gender, only two kinds of values, male or female.
group
experiment
string, or string array 		You can define the user belongs to one or many groups, such as campaign-1, subscriber or ['subscriber', 'consumer', 'young']

Item Attributes

Suggested Attribute Meaning
id
required
integer, or string 		Unique identifier of the item.
name
required
string 		The item’s name, or its title.
sub_name
string 		The item’s secondary name, or its subtitle.
link
recommended
string 		The item’s specific link.
image_link
recommended
string, or string array 		The link or link set of item’s image.
audio_link
string, or string array 		The link or link set of item’s audio.
video_link
string, or string array 		The link or link set of item’s video.
description
recommended
string 		The item’s description, which is the content of a paragraph or an article to describe or explain the item.
price
recommended
number 		The item’s price.
currency
recommended
string 		The currency of item’s price. This is a fixed format string, like USD, EUR, or SGD.
amount
integer 		The item’s amount.
Taxonomy
learn more

TBA
category
recommended
string, or string array 		The item’s category.
category_tree
experiment
string 		In some cases, you might define hierachical category. This is a fixed format string, like XX/YY/..., for example, Food/Italian cuisine/Dessert.
set_by_name
experiment
string, or string array 		You can set up some items in the same package or set by the name of package or set, for example, summer exclusive or ['on sales', 'festival'].
set_by_id
experiment
integer array, or string array 		You can set up some items in the same package or set by the unique identifier, id, of items, for example, [122, 303].
group
experiment
string 		The unique string of the item’s group.

In general, item often has type, size, or color etc. individually (Ref. Specification section below).

You can use this attribute, group, to define some items which have different specifications are the same product.
family
experiment
string 		The unique string of the item’s family.

In some cases, items might be the same series or family tree. You can use this attribute to define it.
tag
string array 		The item’s customized tags, for example, ['electronics', 'laptop'].
Geoinfo
learn more

TBA
location
string, or string array 		The item’s location if necessary.
latitude
decimal 		The item’s latitude.
longitude
decimal 		The item’s longitude.
altitude
decimal 		The item’s altitude.
Provider
learn more

TBA
vendor_id
integer, or string 		The unique identifier of the item’s vendor.
vendor_name
string, or string array 		The name of the item’s vendor.
Specification
learn more

TBA
type
experiment
string 		The item’s type.
size
string 		The item’s size.
color
string 		The item’s color.
material
experiment
string 		The item’s material.
ingredient
experiment
string, or array 		The item’s ingredient.
Accessibility
learn more

TBA
conflict_vendor
experiment
integer array 		In certain special case, some vendors conflict each other. If necessary, you can use this attribute to define. The format is the array of unique identifiers of vendors.
conflict_item
experiment
integer array 		In certain special case, some items conflict each other. If necessary, you can use this attribute to define. The format is the array of unique identifiers of items.
is_featured
recommended
boolean 		Determine if the item is featured.
is_short
recommended
boolean 		Determine if the item is out of stock now.
available_period
datetime array 		The period of item’s availability. This is a fixed format datetime array, like ['MM/DD/YYYY H:i:s', 'MM/DD/YYYY H:i:s']. The first datetime string is the start datetime, and the second datetime string is the end datetime.
expiration
datetime 		The item’s expiration. This is a fixed format datetime string, like MM/DD/YYYY H:i:s.
is_boosted
boolean 		Determine if the item is boosted.
boost_period
experiment
time 		The period to boost the item. This is a fixed format datetime array, like ['H:i:s', 'H:i:s']. The first time string is the start time, and the second time string is the end time.
is_adult_exclusive
experiment
boolean 		Determine if the item is adult exclusive.
is_timezone_exclusive
experiment
boolean 		Determine if the item is timezone exclusive.
preferred_timezone
experiment
string, or string array 		The item’s preferred timezone to boost.

If is_timezone_exclusive is true, this attribute will peform as exclusive timezone.
is_location_exclusive
experiment
boolean 		Determine if the item is location exclusive.
preferred_location
experiment
string, or string array 		The item’s preferred location to boost.

If is_location_exclusive is true, this attribute will peform as exclusive location.

Engine

Engines are the recommendation scenarios you wanna provide on your products (e.g. web, apps, or any products/services).

Each engine has a specific id, and the type of engine is NOT changeable once the engine launched.

The engine object

Example Response

{
  "id": "eng_GgrWlZz535kxfBV7YX3YAkvp",
  "status": "on",
  "created_at": 1536278400,
  "scenario": {
    "id": "sc_WdzyVx77xXxPUA66P3AnyWvx",
    "name": "Recommend Just for You",
    "category": "personalization"
  }
}

Attributes

Parameter Description
id
string		 Unique identifier for the object.
status
string		 The on/off status of the engine.
scenario
object		 The scenario that the engine is created from.

Retrieve an engine

Definition

GET https://api.rosetta.ai/engine/{ENGINE_ID}

Example Request

curl -X GET \
  "https://api.rosetta.ai/engine/eng_GgrWlZz535kxfBV7YX3YAkvp" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow" \

Example Response

{
  "id": "eng_GgrWlZz535kxfBV7YX3YAkvp",
  "status": "on",
  "created_at": 1536278400,
  "scenario": {
    "id": "sc_WdzyVx77xXxPUA66P3AnyWvx",
    "name": "Recommend Just for You",
    "category": "personalization"
  }
}

Retrieves the details of an existing engine. You need only supply the unique engine identifier.

Arguments

Parameter Description
engine_id
required
on url		 The identifier of the engine to be retrieved.

Returns

Returns an engine object if a valid identifier was provided. When requesting the ID of an engine that has been deleted or is not existing, it will return 404 code.

List all engines

Definition

GET https://api.rosetta.ai/engine

Example Request

curl -X GET \
  "https://api.rosetta.ai/engine" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow"

Example Response

{
  "data": [
    {
      "id": "eng_GgrWlZz535kxfBV7YX3YAkvp",
      "status": "on",
      "created_at": 1536278400,
      "scenario": {
        "id": "sc_WdzyVx77xXxPUA66P3AnyWvx",
        "name": "Recommend Just for You",
        "category": "personalization"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}

Returns a list of your engines. The engines are returned sorted by creation date, with the most recent engines appearing first.

Arguments

Parameter Description
page
optional		 The page number of the list of your engines.

Entity

Entity: it’s the real world object involved in the events. The entity may perform the events, or interact with other entity (which became target_id in an event).

For example, your engine may have users and some items which the user can interact with. Then you can model them as two entity type: user and item, and the entity_id can uniquely identify the entity within each type, for example, user with ID 1 (i.e. user-1), item with ID 1 (i.e. item-1).

The entity object

Example Response

{
  "id": "ent_3vq1n5QPAwOLs2zAmeMLnmvV",
  "type": "item",
  "properties": {
    "local_id": "14823",
    "name": "Colorful Umbrella",
    "type": "item"
  },
  "created_at": 1536457952,
  "lists": {
    "data": [
      {
        "id": "ls_kvj1w7KRjMxAU2py9A4r11gG",
        "type": "product",
        "name": "my-product-list",
        "created_at": 1536278400
      }
    ]
  }
}

Attributes

Parameter Description
id
integer		 Unique identifier for the object.
type
string, the value is item or user		 Entity type of the object. Currently, the value supports item and user.
properties
string, JSON format		 Custom properties of the object. It has to be JSON format.

Create an entity

Definition

POST https://api.rosetta.ai/entity

Example Request

curl -X POST \
  https://api.rosetta.ai/entity \
  -H Content-Type: application/x-www-form-urlencoded \
  -H Accept: application/vnd.rosetta-ai.v1+json \
  -H Authorization: meowmeowmeow \
  -d name=Colorful Umbrella \
  -d local_id=14823 \
  -d type=item

Example Response

{
  "id": "ent_3vq1n5QPAwOLs2zAmeMLnmvV",
  "type": "item",
  "properties": {
    "local_id": "14823",
    "name": "Colorful Umbrella",
    "type": "item"
  },
  "created_at": 1536457952,
  "lists": {
    "data": [
      {
        "id": "ls_kvj1w7KRjMxAU2py9A4r11gG",
        "type": "product",
        "name": "my-product-list",
        "created_at": 1536278400
      }
    ]
  }
}

Create a new entity object.

Arguments

Parameter Description
name
required		 Custom name of the object.
type
required		 Entity type of the object. Currently, the value supports item and user.
local_id
required		 Local id of the object.

Retrieve an entity

Definition

GET https://api.rosetta.ai/entity/{ENTITY_ID}

Example Request

curl -X GET \
  "https://api.rosetta.ai/entity/ent_3vq1n5QPAwOLs2zAmeMLnmvV" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow"

Example Response

{
  "id": "ent_3vq1n5QPAwOLs2zAmeMLnmvV",
  "type": "item",
  "properties": {
    "local_id": "14823",
    "name": "Colorful Umbrella",
    "type": "item"
  },
  "created_at": 1536457952,
  "lists": {
    "data": [
      {
        "id": "ls_kvj1w7KRjMxAU2py9A4r11gG",
        "type": "product",
        "name": "my-product-list",
        "created_at": 1536278400
      }
    ]
  }
}

Retrieves the details of an existing entity. You need only supply the unique entity identifier that was returned upon entity creation.

Arguments

Parameter Description
entity_id
required
on url		 The identifier of the entity to be retrieved.

Returns

Returns an entity object if a valid identifier was provided. When requesting the ID of an entity that has been deleted or is not existing, it will return 404 code.

Update an entity

Definition

PUT https://api.rosetta.ai/entity/{ENTITY_ID}

Example Request

curl -X PUT \
  "https://api.rosetta.ai/entity/ent_3vq1n5QPAwOLs2zAmeMLnmvV" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow" \
  -d "name=Blue Umbrella" \
  -d "category=Home life"

Example Response

{
  "id": "ent_3vq1n5QPAwOLs2zAmeMLnmvV",
  "type": "item",
  "properties": {
    "local_id": "14823",
    "name": "Blue Umbrella",
    "type": "item",
    "category": "Home life"
  },
  "created_at": 1536457952,
  "lists": {
    "data": [
      {
        "id": "ls_kvj1w7KRjMxAU2py9A4r11gG",
        "type": "product",
        "name": "my-product-list",
        "created_at": 1536278400
      }
    ]
  }
}

Updates the specified entity by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Arguments

Parameter Description
entity_id
required
on url		 The identifier of the entity to be updated.
name
optional		 Custom name of the object.
type
optional		 Entity type of the object. Currently, the value supports item and user.
local_id
optional		 Local id of the object.

Delete an entity

Definition

DELETE https://api.rosetta.ai/entity/{ENTITY_ID}

Example Request

curl -X DELETE \
  "https://api.rosetta.ai/entity/ent_3vq1n5QPAwOLs2zAmeMLnmvV" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow"

Permanently deletes a entity. It cannot be undone.

Arguments

Parameter Description
entity_id
required
on url		 The identifier of the entity to be deleted.

Returns

204 No Content, if successed.

List all entities

Definition

GET https://api.rosetta.ai/entity

Example Request

curl -X GET \
  "https://api.rosetta.ai/entity" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow"

Example Response

{
  "data": [
    {
      "id": "ent_3vq1n5QPAwOLs2zAmeMLnmvV",
      "type": "item",
      "properties": {
        "local_id": "14823",
        "name": "Blue Umbrella",
        "type": "item",
        "category": "Home life"
      },
      "created_at": 1536457952,
      "lists": {
        "data": [
          {
            "id": "ls_kvj1w7KRjMxAU2py9A4r11gG",
            "type": "product",
            "name": "my-product-list",
            "created_at": 1536278400
          }
        ]
      }
    },
    {
      "id": "ent_qJOqbeV4mX4GIGQzzO2B4EvV",
      "type": "item",
      "properties": {
        "local_id": "product-1563",
        "name": "Beauty Shoes",
        "type": "item"
      },
      "created_at": 1536457950,
      "lists": {
        "data": [
          {
            "id": "ls_kvj1w7KRjMxAU2py9A4r11gG",
            "type": "product",
            "name": "my-product-list",
            "created_at": 1536278400
          }
        ]
      }
    },
    {...},
    {...},
    {...}
  ],
  "meta": {
    "pagination": {
      "total": 13806,
      "count": 10,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 1381,
      "links": {
        "next": "https://api.rosetta.develop/entity?page=2"
      }
    }
  }
}

Returns a list of the entities. The entities are returned sorted by creation date, with the most recent entities appearing first.

Arguments

Parameter Description
page
optional		 The page number of the list of the entities.

Event

Rosetta API measures the actual correlations of events to understand those that correlate. And those that do not correlate will have little or no effect on recommendations.

The event is the action which user entity performs.

The event object

Example Response

{
  "id": "ev_Dgk2yBO02QPycQjxNeP4WBJy",
  "action": "click",
  "created_at": 1546040940,
  "actor": {
    "id": "ent_Qdb2Ay9V0yEriDNLkzEoy8dM",
    "type": "user",
    "properties": {
      "name": "John Titor",
      "type": "user",
      "local_id": "local-user-001"
    },
    "created_at": 1546040818,
    "lists": {
      "data": [
        {
          "id": "ls_nvB2ZeXj3yZptGXwjGoZjpvM",
          "type": "enduser",
          "name": "my-consumer-list",
          "created_at": 1536278400
        }
      ]
    }
  },
  "target": {
    "id": "ent_3vq1n5QPAwOLs2zAmeMLnmvV",
    "type": "item",
    "properties": {
      "local_id": "14823",
      "name": "Blue Umbrella",
      "type": "item",
      "category": "Home life"
    },
    "created_at": 1536457952,
    "lists": {
      "data": [
        {
          "id": "ls_kvj1w7KRjMxAU2py9A4r11gG",
          "type": "product",
          "name": "my-product-list",
          "created_at": 1536278400
        }
      ]
    }
  }
}

Attributes

Parameter Description
id
string		 Unique identifier for the event object.
action
string		 The event name, such as, click, search, buy, etc.
actor
object		 The object of the actor.
target
object		 The object of the target entity.

Create an event

Definition

POST https://api.rosetta.ai/event

Example Request

curl -X POST \
  "https://api.rosetta.ai/event" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow" \
  -d "actor=ent_Qdb2Ay9V0yEriDNLkzEoy8dM" \
  -d "action=click" \
  -d "target=ent_3vq1n5QPAwOLs2zAmeMLnmvV"

Example Response

{
  "id": "ev_Dgk2yBO02QPycQjxNeP4WBJy",
  "action": "click",
  "created_at": 1546040940,
  "actor": {
    "id": "ent_Qdb2Ay9V0yEriDNLkzEoy8dM",
    "type": "user",
    "properties": {
      "name": "John Titor",
      "type": "user",
      "local_id": "local-user-001"
    },
    "created_at": 1546040818,
    "lists": {
      "data": [
        {
          "id": "ls_nvB2ZeXj3yZptGXwjGoZjpvM",
          "type": "enduser",
          "name": "my-consumer-list",
          "created_at": 1536278400
        }
      ]
    }
  },
  "target": {
    "id": "ent_3vq1n5QPAwOLs2zAmeMLnmvV",
    "type": "item",
    "properties": {
      "local_id": "14823",
      "name": "Blue Umbrella",
      "type": "item",
      "category": "Home life"
    },
    "created_at": 1536457952,
    "lists": {
      "data": [
        {
          "id": "ls_kvj1w7KRjMxAU2py9A4r11gG",
          "type": "product",
          "name": "my-product-list",
          "created_at": 1536278400
        }
      ]
    }
  }
}

Create a new event object.

Arguments

Parameter Description
action
required
string		 The event name, such as, click, search, buy, etc.
actor
required
string		 Unique identifier of the user entity which performs the event.
target
required
string		 Unique identifier of the item entity which is acted.

Retrieve an event

Definition

GET https://api.rosetta.ai/event/{EVENT_ID}

Example Request

curl -X GET \
  "https://api.rosetta.ai/event/ev_Dgk2yBO02QPycQjxNeP4WBJy" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow"

Example Response

{
  "id": "ev_Dgk2yBO02QPycQjxNeP4WBJy",
  "action": "click",
  "created_at": 1546040940,
  "actor": {
    "id": "ent_Qdb2Ay9V0yEriDNLkzEoy8dM",
    "type": "user",
    "properties": {
      "name": "John Titor",
      "type": "user",
      "local_id": "local-user-001"
    },
    "created_at": 1546040818,
    "lists": {
      "data": [
        {
          "id": "ls_nvB2ZeXj3yZptGXwjGoZjpvM",
          "type": "enduser",
          "name": "my-consumer-list",
          "created_at": 1536278400
        }
      ]
    }
  },
  "target": {
    "id": "ent_3vq1n5QPAwOLs2zAmeMLnmvV",
    "type": "item",
    "properties": {
      "local_id": "14823",
      "name": "Blue Umbrella",
      "type": "item",
      "category": "Home life"
    },
    "created_at": 1536457952,
    "lists": {
      "data": [
        {
          "id": "ls_kvj1w7KRjMxAU2py9A4r11gG",
          "type": "product",
          "name": "my-product-list",
          "created_at": 1536278400
        }
      ]
    }
  }
}

Retrieves the details of an existing event. You need only supply the unique event identifier that was returned upon event creation.

Arguments

Parameter Description
event_id
required
on url		 The identifier of the event to be retrieved.

Update an event

Definition

PUT https://api.rosetta.ai/event/{EVENT_ID}

Example Request

curl -X PUT \
  "https://api.rosetta.ai/event/ev_Dgk2yBO02QPycQjxNeP4WBJy" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow" \
  -d "actor=ent_Qdb2Ay9V0yEriDNLkzEoy8dM" \
  -d "action=buy" \
  -d "target=ent_3vq1n5QPAwOLs2zAmeMLnmvV"

Example Response

{
  "id": "ev_Dgk2yBO02QPycQjxNeP4WBJy",
  "action": "buy",
  "created_at": 1546040940,
  "actor": {
    "id": "ent_Qdb2Ay9V0yEriDNLkzEoy8dM",
    "type": "user",
    "properties": {
      "name": "John Titor",
      "type": "user",
      "local_id": "local-user-001"
    },
    "created_at": 1546040818,
    "lists": {
      "data": [
        {
          "id": "ls_nvB2ZeXj3yZptGXwjGoZjpvM",
          "type": "enduser",
          "name": "my-consumer-list",
          "created_at": 1536278400
        }
      ]
    }
  },
  "target": {
    "id": "ent_3vq1n5QPAwOLs2zAmeMLnmvV",
    "type": "item",
    "properties": {
      "local_id": "14823",
      "name": "Blue Umbrella",
      "type": "item",
      "category": "Home life"
    },
    "created_at": 1536457952,
    "lists": {
      "data": [
        {
          "id": "ls_kvj1w7KRjMxAU2py9A4r11gG",
          "type": "product",
          "name": "my-product-list",
          "created_at": 1536278400
        }
      ]
    }
  }
}

Arguments

Parameter Description
event_id
required
on url		 The identifier of the event to be updated.
action
optional, string		 The event name, such as, click, search, buy, etc.
actor
optional, string		 Unique identifier of the user entity which performs the event.
target
optional, string		 Unique identifier of the item entity which is acted.

Delete an event

Definition

DELETE https://api.rosetta.ai/event/{EVENT_ID}

Example Request

curl -X DELETE \
  "https://api.rosetta.ai/event/ev_Dgk2yBO02QPycQjxNeP4WBJy" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow"

Permanently deletes a entity. It cannot be undone.

Arguments

Parameter Description
event_id
required
on url		 The identifier of the event to be deleted.

Returns

204 No Content, if successed.

List all events

Definition

GET https://api.rosetta.ai/event

Example Request

curl -X GET \
  "https://api.rosetta.ai/event" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow"

Example Response

{
  "data": [
    {
      "id": "ev_Dgk2yBO02QPycQjxNeP4WBJy",
      "action": "buy",
      "created_at": 1546040940,
      "actor": {
        "id": "ent_Qdb2Ay9V0yEriDNLkzEoy8dM",
        "type": "user",
        "properties": {
          "name": "John Titor",
          "type": "user",
          "local_id": "local-user-001"
        },
        "created_at": 1546040818,
        "lists": {
          "data": [
            {
              "id": "ls_nvB2ZeXj3yZptGXwjGoZjpvM",
              "type": "enduser",
              "name": "my-consumer-list",
              "created_at": 1536278400
            }
          ]
        }
      },
      "target": {
        "id": "ent_3vq1n5QPAwOLs2zAmeMLnmvV",
        "type": "item",
        "properties": {
          "local_id": "14823",
          "name": "Blue Umbrella",
          "type": "item",
          "category": "Home life"
        },
        "created_at": 1536457952,
        "lists": {
          "data": [
            {
              "id": "ls_kvj1w7KRjMxAU2py9A4r11gG",
              "type": "product",
              "name": "my-product-list",
              "created_at": 1536278400
            }
          ]
        }
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "pagination": {
      "total": 65514,
      "count": 10,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 6552,
      "links": {
        "next": "https://api.rosetta.develop/event?page=2"
      }
    }
  }
}

Returns a list of the events belonging to an app. The events are returned sorted by creation date, with the most recent events appearing first.

Arguments

Parameter Description
page
optional		 The page number of the list of the events.

Query

The query object

Example Response

{
  "id": "q_Qdb8j0rEoww8cRMAkZLY9zgM",
  "data": [
    {
      "item": "ent_mvZeRkZpQG5qhlmyM214Keg7",
      "score": 1
    },
    {
      "item": "ent_YJpaRA1kb2bMukmlzeoOKmgQ",
      "score": 0.7130801687763713
    },
    {
      "item": "ent_4d8RORL9V8W9FNl1DlrxBQgR",
      "score": 0.6624472573839663
    },
    {
      "item": "ent_3vqknQrVk17rf4MKLw37jLJV",
      "score": 0.6075949367088608
    },
    {
      "item": "ent_kgDBjkMlDGMxtMx3WqBR0mdo",
      "score": 0.540084388185654
    },
    {...},
    {...},
  ],
  "created_at": 1546041381,
  "engine": {
    "id": "eng_GgrWlZz535kxfBV7YX3YAkvp",
    "status": "on",
    "created_at": 1536278400,
    "scenario": {
      "id": "sc_WdzyVx77xXxPUA66P3AnyWvx",
      "name": "Recommend Just for You",
      "category": "personalization"
    }
  }
}

Attributes

Parameter Description
id
string		 The identifier of the query object.
data
array		 The array contains entities which are recommended by the engine.
engine
object		 The engine object.

Create an query

Definition

POST https://api.rosetta.ai/engine/{ENGINE_ID}/query

Example Request

curl -X POST \
  "https://api.rosetta.ai/engine/eng_GgrWlZz535kxfBV7YX3YAkvp/query" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow" \
  -d "user=ent_aXK3m2sK2B0cKD7oL1npPQC" \
  -d "item=ent_VCpakk8EbCHSiaQ2DkeONdklU"

Example Response

{
  "id": "q_Qdb8j0rEoww8cRMAkZLY9zgM",
  "data": [
    {
      "item": "ent_mvZeRkZpQG5qhlmyM214Keg7",
      "score": 1
    },
    {
      "item": "ent_YJpaRA1kb2bMukmlzeoOKmgQ",
      "score": 0.7130801687763713
    },
    {
      "item": "ent_4d8RORL9V8W9FNl1DlrxBQgR",
      "score": 0.6624472573839663
    },
    {
      "item": "ent_3vqknQrVk17rf4MKLw37jLJV",
      "score": 0.6075949367088608
    },
    {
      "item": "ent_kgDBjkMlDGMxtMx3WqBR0mdo",
      "score": 0.540084388185654
    },
    {...},
    {...},
  ],
  "created_at": 1546041381,
  "engine": {
    "id": "eng_GgrWlZz535kxfBV7YX3YAkvp",
    "status": "on",
    "created_at": 1536278400,
    "scenario": {
      "id": "sc_WdzyVx77xXxPUA66P3AnyWvx",
      "name": "Recommend Just for You",
      "category": "personalization"
    }
  }
}

Create a new query object. (Make a query.)

Arguments

Parameter Description
engine_id
required
string, on url		 The identifier of the engine.
user
required
string		 The identifier of the user who receives the recommended entities.
item
required, for non-popularity engines
string		 The identifier of the item which relates the recommended entities.

Personalization

Delight your audience with an experience they will love.

Scenarios

Recommend Just for You

Every customer will see “Just for you page”, which is similar to “You May Also Like”. It will predict everyone’s preferences and recommends something they probably like according to records which are based on their browsing history.

Example Request of Contextually Personalize with Similar Items

curl -X POST \
  "https://api.rosetta.ai/engine/100112002230006/query" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow" \
  -d "user=ent_Qdb8EZlp52KoSmDkDZwBn9gM" \
  -d "item=ent_PgWaWLyXqrjpHDqbGyq8kldB"

Contextually Personalize with Similar Items

When customers are browsing merchandises, this engine will continuously recommend them with items that have similar attributes, such as color, size and brands based on their viewing history.

Personalize the Display Order of Catalog

The category navigation bar on the website, like Fashion, Food, Electronics, will be sorted by the categories customers are most interested in according to their preferences.

Personalize the Display Order of Menu Items

Change the display order in dropdown lists to meet customer’s preferences. For example, if a customer likes to play games, the subcategory “Games” in the Electronics will be sorted out first.

Personalize the Display Order of Page Items

On a travel website, travel plans for Italy will be sorted in the front for customers who likes art; Plans for Paris will be listed for customers who love shopping.

Create an query

Except Contextually Personalize with Similar Items, only need to add user argument.

Example Request

curl -X POST \
  "https://api.rosetta.ai/engine/100112002230006/query" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow" \
  -d "user=ent_Qdb8EZlp52KoSmDkDZwBn9gM"

Similarity

Discover things that are fresh to users don’t know ever.

Scenarios

Provide similar product recommendations according to the customer’s browsing history on the website.

Similar Items by Attributes

When customers are viewing or selecting products, the engine will recommend something highly relevant to the current product to increase merchandise exposures.

Present the product pages or articles that users’ have visited recently along with featured and related items.

Viewed/Clicked This Also View/Click Those

The user who has viewed or click something also will have seen or click the other thing to trigger users to browse or click more.

Liked This Also Like Those

The user who likes this item also desires the others. This engine will trigger the user likes more things.

Selected This Also Select Those

Take something into the shopping cart; they also will select the other things. It makes customers buy more.

Bought This Also Buy Those

The customer who buys something will also buy another thing. It can let your customers buy more.

Downloaded/Saved This Also Download/Save Those

Download, save or collect the video or music; they also take the others.

Played This Also Play Those

The customers download or collect the video; they also take those other videos.

Create an query

Must add item argument.

Example Request

curl -X POST \
  "https://api.rosetta.ai/engine/100112002230006/query" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow" \
  -d "item=ent_PgWaWLyXqrjpHDqbGyq8kldB"

Popularity

Stand out the items that are the most attractive to people.

Scenarios

Recommend from the cumulated number of Indicator behavior, like click, like, share, etc. You can set to focus on one or multiple behavior analysis.

Recommend based on the average growth rate of the number of indicator behavior(s) accumulated over a period.

Hot Items

The recommendation based on the difference in the average growth rate (Trending) of the indicator behavior over a period.

Best Selling

Recommend based on purchase amount.

Most Viewed

Recommend based on number of views.

Most Liked

Recommend based on like amount.

Stay Long

Recommend based on the amount of time spend on a given page.

Create an query

Without any argument.

Example Request

curl -X POST \
  "https://api.rosetta.ai/engine/100112002230006/query" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow" \
  -d "user=ent_Qdb8EZlp52KoSmDkDZwBn9gM"

Miscellaneous

Figure out results across categories, behaviors, and contexts.

Scenarios

Frequently Bought Together

Recommend the combinations of products that are frequently bought together according to the product which the customer is viewing or put in the shopping cart.

Viewed This Buy That

Some customers browsed bags, clothing, and accessories, but eventually bought shoes. It’s a recommendation can solve this “Shopping behavior”.

Example Request of Browsing History with Ranking

curl -X POST \
  "https://api.rosetta.ai/engine/100112002230006/query" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow" \
  -d "user=ent_Qdb8EZlp52KoSmDkDZwBn9gM"

Browsing History with Ranking

Sort things that have been viewed in the past according to their preferences and reach the reminder function.

Just Viewed/Clicked

When a user just clicks or browses, it’ll recommend more related products or articles.

Just Selected

When customers just add a commodity to the shopping cart, the engine will recommend them to buy more related products.

Just Bought

When the customer has just completed the order, the engine will recommend users to buy more related products.

Create an query

Must add item argument.

Example Request

curl -X POST \
  "https://api.rosetta.ai/engine/100112002230006/query" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow" \
  -d "user=ent_Qdb8EZlp52KoSmDkDZwBn9gM" \
  -d "item=ent_PgWaWLyXqrjpHDqbGyq8kldB"
cURL