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.

Therefore, you can define multiple datetime pairs for different periods, like [['MM/DD/YYYY H:i:s', 'MM/DD/YYYY H:i:s'], ['MM/DD/YYYY H:i:s', 'MM/DD/YYYY H:i:s'], ...]

If you’d like to specify particular weekdays for setting up the peroid of availability. You can use key-value to specify. Notice that the value ONLY contain H:i:s, for example, ['0': ['H:i:s', 'H:i:s'], '2': [['H:i:s', 'H:i:s'], ['H:i:s', 'H:i:s']], '5': ['H:i:s', 'H:i:s']]

“0”: Sunday, “1”: Monday, “2”: Tuesday, …, “6”: Saturday
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.

Therefore, you can define multiple time pairs for different periods, like [['H:i:s', 'H:i:s'], ['H:i:s', 'H:i:s'], ...]

If you’d like to specify particular weekdays for setting up the peroid of boosting. You can use key-value to specify, for example, ['0': ['H:i:s', 'H:i:s'], '2': ['H:i:s', 'H:i:s'], '5': [['H:i:s', 'H:i:s'], ['H:i:s', 'H:i:s']]]

“0”: Sunday, “1”: Monday, “2”: Tuesday, …, “6”: Saturday
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": 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-16 11:01:39.000000",
    "timezone_type": 3,
    "timezone": "UTC"
  }
}

Attributes

Parameter Description
id
integer
Unique identifier for the object.
name
string
Custom name of the object.
type
string
Indicates what kinds of engines for the object.
description
optional, default is null
An arbitrary string which you can attach to a engine object. It is displayed when in the web interface alongside the engine.

Retrieve an engine

Definition

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

Example Request

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

Example Response

{
  "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-16 11:01:39.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    }
  }
}

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

{
  "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"
      }
    },
    {...},
    {...}
  ]
}

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": 100131139421385,
  "name": "iPhone 8",
  "type": "item",
  "custom_id": "item-1",
  "property": null,
  "created_at": {
    "date": "2017-05-16 13:01:26.000000",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "updated_at": {
    "date": "2017-05-16 13:01:26.000000",
    "timezone_type": 3,
    "timezone": "UTC"
  }
}

Attributes

Parameter Description
id
integer
Unique identifier for the object.
name
string
Custom name of the object.
type
string, the value is item or user
Entity type of the object. Currently, the value supports item and user.
custom_id
string
Custom id of the object.
property
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=iPhone 8" \
  -d "custom_id=item-1" \
  -d "type=item"

Example Response

{
  "data": {
    "id": 100131139421385,
    "name": "iPhone 8",
    "type": "item",
    "custom_id": "item-1",
    "property": null,
    "created_at": {
      "date": "2017-05-16 13:01:26.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "updated_at": {
      "date": "2017-05-16 13:01:26.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    }
  }
}

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.
custom_id
required
Custom id of the object.
property
optional, JSON format
Custom properties of the object. It has to be JSON format.

Retrieve an entity

Definition

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

Example Request

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

Example Response

{
  "data": {
    "id": 100131139421385,
    "name": "iPhone 8",
    "type": "item",
    "custom_id": "item-1",
    "property": null,
    "created_at": {
      "date": "2017-05-16 13:01:26.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "updated_at": {
      "date": "2017-05-16 13:01:26.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    }
  }
}

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/100131139421385" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow" \
  -d "name=iPhone 10" \
  -d 'property={"provider": "Apple", "salable": false}'

Example Response

{
  "data": {
    "id": 100131139421385,
    "name": "iPhone 10",
    "type": "item",
    "custom_id": "item-1",
    "property": {
      "provider": "Apple",
      "salable": false
    },
    "created_at": {
      "date": "2017-05-16 13:01:26.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "updated_at": {
      "date": "2017-05-16 13:01:26.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    }
  }
}

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.
custom_id
optional
Custom id of the object.
property
optional, JSON format
Custom properties of the object. It has to be JSON format.

Delete an entity

Definition

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

Example Request

curl -X DELETE \
  "https://api.rosetta.ai/entity/100131139421385" \
  -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": 100131139421385,
      "name": "iPhone 10",
      "type": "item",
      "custom_id": "item-1",
      "property": {
        "provider": "Apple",
        "salable": false
      },
      "created_at": {
        "date": "2017-05-16 13:01:26.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2017-05-16 13:01:26.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      }
    },
    {
      "id": 100131585368796,
      "name": "Eren Yeager",
      "type": "user",
      "custom_id": "user-2",
      "property": null,
      "created_at": {
        "date": "2017-05-16 05:14:24.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2017-05-16 05:14:24.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}

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": 100141120229755,
  "event": "buy",
  "entity_id": 100131585368796,
  "target_id": 100131139421385,
  "created_at": {
    "date": "2017-05-16 13:01:26.000000",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "updated_at": {
    "date": "2017-05-16 13:01:26.000000",
    "timezone_type": 3,
    "timezone": "UTC"
  }
}

Attributes

Parameter Description
id
integer
Unique identifier for the object.
event
string
Custom event name of the object, such as view, click, search, buy, and so on.
entity_id
integer
Unique identifier of the entity which performs the event. The entity type must be user.
target_id
integer
Unique identifier of the entity which is interacted with.

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 "event=buy" \
  -d "entity_id=100131585368796" \
  -d "target_id=100131139421385"

Example Response

{
  "data": {
    "id": 100141120229755,
    "event": "buy",
    "entity_id": 100131585368796,
    "target_id": 100131139421385,
    "created_at": {
      "date": "2017-05-16 13:01:26.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "updated_at": {
      "date": "2017-05-16 13:01:26.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    }
  }
}

Create a new event object.

Arguments

Parameter Description
event
required
Custom event name of the object, such as view, click, search, buy, and so on.
entity_id
required
Unique identifier of the entity which performs the event. The entity type must be user.
target_id
required
Unique identifier of the entity which is interacted with.

Retrieve an event

Definition

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

Example Request

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

Example Response

{
  "data": {
    "id": 100141120229755,
    "event": "buy",
    "entity_id": 100131585368796,
    "target_id": 100131139421385,
    "created_at": {
      "date": "2017-05-16 13:01:26.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "updated_at": {
      "date": "2017-05-16 13:01:26.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    }
  }
}

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/100141120229755" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/vnd.rosetta-ai.v1+json" \
  -H "Authorization: meowmeowmeow" \
  -d "event=click" \
  -d "entity_id=100131585368796" \
  -d "target_id=100131139421385"

Example Response

{
  "data": {
    "id": 100141120229755,
    "event": "click",
    "entity_id": 100131585368796,
    "target_id": 100131139421385,
    "created_at": {
      "date": "2017-05-16 13:01:26.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "updated_at": {
      "date": "2017-05-16 13:01:26.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    }
  }
}

Arguments

Parameter Description
event_id
required
on url
The identifier of the event to be updated.
event
optional
Custom event name of the object, such as view, click, search, buy, and so on.
entity_id
optional
Unique identifier of the entity which performs the event. The entity type must be user.
target_id
optional
Unique identifier of the entity which is interacted with.

Delete an event

Definition

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

Example Request

curl -X DELETE \
  "https://api.rosetta.ai/event/100141120229755" \
  -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": 100141120229755,
      "event": "buy",
      "entity_id": 100131585368796,
      "target_id": 100131139421385,
      "created_at": {
        "date": "2017-05-16 13:01:26.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2017-05-16 13:01:26.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      }
    },
    {
      "id": 10014177303711,
      "event": "view",
      "entity_id": 100131585368796,
      "target_id": 100131139421385,
      "created_at": {
        "date": "2017-05-16 05:14:24.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2017-05-16 05:14:24.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}

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

{
  "user": {
    "id": 100131585368796,
    "name": "Eren Yeager",
    "entity_type": "user",
    "custom_entity_id": "user-2",
    "property": null,
  },
  "engine": {
    "id": 100112002230006,
    "type": "personalized rec",
    "description": null
  },
  "data": [
    {
      "id": 100131139421385,
      "name": "iPhone 10",
      "entity_type": "item",
      "custom_entity_id": "item-1",
      "property": {
        "provider": "Apple",
        "salable": false
      },
      "created_at": {
        "date": "2017-05-16 13:01:26.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2017-05-16 13:01:26.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      }
    },
    {
      "id": 100131267219982,
      "name": "Tesla Model S",
      "entity_type": "item",
      "custom_entity_id": "item-6",
      "property": {
        "provider": "Tesla",
        "salable": true
      },
      "created_at": {
        "date": "2017-05-16 13:01:26.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2017-05-16 13:01:26.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}

Attributes

Parameter Description
user
object
The entity object who receives the recommended entities.
Example use case: Personalized recommendation.
item
object
The entity object which relates to the recommended entities.
Example use case: Similar items.
engine
object
The engine object.
data
object
The array object contains entities which are recommended by the app.
meta
object
The pagination object.

Create an query

Definition

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

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=100131585368796"

Example Response

{
  "user": {
    "id": 100131585368796,
    "name": "Eren Yeager",
    "entity_type": "user",
    "custom_entity_id": "user-2",
    "property": null,
  },
  "engine": {
    "id": 100112002230006,
    "type": "personalized rec",
    "description": null
  },
  "data": [
    {
      "id": 100131139421385,
      "name": "iPhone 10",
      "entity_type": "item",
      "custom_entity_id": "item-1",
      "property": {
        "provider": "Apple",
        "salable": false
      },
      "created_at": {
        "date": "2017-05-16 13:01:26.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2017-05-16 13:01:26.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      }
    },
    {
      "id": 100131267219982,
      "name": "Tesla Model S",
      "entity_type": "item",
      "custom_entity_id": "item-6",
      "property": {
        "provider": "Tesla",
        "salable": true
      },
      "created_at": {
        "date": "2017-05-16 13:01:26.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2017-05-16 13:01:26.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 1,
      "links": []
    }
  }
}

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

Arguments

Parameter Description
engine_id
required
integer, on url
The identifier of the engine.
user
optional
integer
The identifier of the user who receives the recommended entities.
Example use case: Personalized recommendation.
item
optional
integer
The identifier of the item which relates the recommended entities.
Example use case: Similar items.

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=100131585368796" \
  -d "item=100131139421385"

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=100131585368796"

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=100131139421385"

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"

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"

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 "item=100131139421385"