User Interactions¶

Create One User Interaction¶

POST users/<str:user_id>/interactions/<str:item_id>/¶

Note

Authorized Roles: root, manager, backend, frontend

This endpoint allows you to create a new interaction for a user and an item. An inferred rating will be created or updated for the tuple (user_id, item_id). The taste profile of the user will then be updated in real-time by the online machine learning algorithm.

Note: In case the session has already been resolved, the response will include a warning

Request JSON Object

interaction_type (string) – [max-length: 64] Interaction type
timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)
properties (object) – Optional. Additional data in interactions

EXAMPLE QUERY BODY¶

  {
      "interaction_type": "productView",
      "timestamp": 1588812345,
      "properties": {
          "revenue": 19.95
      }
  }

Response JSON Object

warnings (list-of-string) – Optional. List of warnings

Errors:

ServerUnavailable with error name DB_IMPLICIT_TO_EXPLICIT_PARAMS_NOT_FOUND if no “implicit-to-explicit” parameters have been set for this database

Create Interactions for a User in Bulk¶

POST users/<str:user_id>/interactions-bulk/¶

Note

Authorized Roles: root, manager, backend, frontend

Create a small bulk of interactions for a single user and many items. Inferred ratings will be created or updated for all tuples (user_id, item_id).

Request JSON Object

interactions (object-array) –
Interactions array
Inner fields
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
- interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type
- timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp
- properties (object-array) – (additional fields may be present) Additional data in interactions

EXAMPLE QUERY BODY¶

  {
      "interactions": [
          {"item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588854321, "properties": {"page": "pdp"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588811111, "properties": {"revenue": 19.95}}
      ]
  }

Response JSON Object

warnings (list-of-string) – Optional. List of warnings

Errors:

ServerUnavailable with error name DB_IMPLICIT_TO_EXPLICIT_PARAMS_NOT_FOUND if no “implicit-to-explicit” parameters have been set for this database

List Interactions of One User In Bulk¶

GET users/<str:user_id>/interactions-bulk/¶

Note

Authorized Roles: root, manager, backend

This endpoint allows you to list the interactions of one user. The response is paginated, you can control the response amount and offset using the query parameters amt and cursor.

Query Parameters

amt (int) – Optional. [min: 1] Maximal amount of interactions to return
cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

EXAMPLE QUERY PARAMS¶

  ?amt=3&cursor=F25pU1vHb1LjSEp...

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
has_next (bool) – Indicates whether or not there are more interactions to request
next_cursor (string) – Optional. Pagination cursor, to use in next request to get more interactions
interactions (object-array) –
User’s Interactions array
Inner fields
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
- interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type
- timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp
- properties (object-array) – (additional fields may be present) Additional data in interactions

EXAMPLE RESPONSE¶

  {
      "has_next": true,
      "next_cursor": "Q21vU1pHb1FjSEp...",
      "interactions": [
          {"item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588854321, "properties": {"page": "pdp"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588811111, "properties": {"page": "cart"}},
      ]
  }

Create Interactions for Many Users in Bulk¶

POST interactions-bulk/¶

Note

Authorized Roles: root, manager, backend

Create large bulks of interactions for many users and many items. Inferred ratings will be created or updated for all tuples (user_id, item_id).

Note: In case sessions id has already been resolved, they will be created and returned in warnings param

Request JSON Object

interactions (object-array) –
Interactions array
Inner fields
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
- interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type
- timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp
- properties (object-array) – (additional fields may be present) Additional data in interactions
- user_id (ID) – [see Flexible Identifiers], [max_length: 64] User ID

EXAMPLE QUERY BODY¶

  {
      "interactions": [
          {"user_id": 1234, "item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"user_id": 1234, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588854321, "properties": {"page": "pdp"}},
          {"user_id": 333, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588811111, "properties": {"revenue": 19.95}}
      ]
  }

Response JSON Object

warnings (list-of-string) – Optional. List of warnings

Errors:

ServerUnavailable with error name DB_IMPLICIT_TO_EXPLICIT_PARAMS_NOT_FOUND if no “implicit-to-explicit” parameters have been set for this database

List Interactions for All Users In Bulk¶

GET interactions-bulk/¶

Note

Authorized Roles: root, manager, backend

This endpoint allows you to list the interactions of one database. The response is paginated, you can control the response amount and offset using the query parameters amt and cursor.

Parameters start_timestamp and end_timestamp allow filtering out: interactions outside of a specified time frame.
Even when a small time-frame is specified, a full database scan is: performed; in this case, most batches will contain little to no interaction.

Query Parameters

amt (int) – Optional. [min: 1] Maximal amount of interactions to return
cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response
start_timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Start timestamp of interactions to fetch
end_timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] End timestamp of interactions to fetch

EXAMPLE QUERY PARAMS¶

  ?amt=10&cursor=F25pU1vHb1LjSEp...&start_timestamp=1588811110.9&end_timestamp=1588854321.1

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
has_next (bool) – Indicates whether or not there are more interactions to request
next_cursor (string) – Optional. Pagination cursor, to use in next request to get more interactions
interactions (object-array) –
Interactions array
Inner fields
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
- interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type
- timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp
- properties (object-array) – (additional fields may be present) Additional data in interactions
- user_id (ID) – [see Flexible Identifiers], [max_length: 64] User ID

EXAMPLE RESPONSE¶

  {
      "has_next": true,
      "next_cursor": "Q21vU1pHb1FjSEp...",
      "interactions": [
          {"user_id": 1234, "item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"user_id": 1234, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588854321, "properties": {"page": "pdp"}},
          {"user_id": 333, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588811111, "properties": {"revenue": 19.95}}
      ]
  }

Errors:

WrongData if both start_timestamp and end_timestamp are provided and start_timestamp >= end_timestamp

Delete Interactions and Ratings for Many Users¶

DELETE interactions-ratings-bulk/¶

Note

Authorized Roles: root, manager, backend

Delete all interactions and ratings for many users.

The deletion is done in a background task.

Response JSON Object

users_id (ID-array) – Users IDs

EXAMPLE QUERY BODY¶

  {
      "users_id": [
          "123e4567-e89b-12d3-a456-426614174000",
          "c3391d83-553b-40e7-818e-fcf658ec397d"
      ]
  }

Create One Anonymous Session Interaction¶

POST sessions/<str:session_id>/items/<str:item_id>/interactions/¶

Note

Authorized Roles: root, manager, backend, frontend

This endpoint allows you to create a new interaction for an anonymous session and an item.

Request JSON Object

interaction_type (string) – [max-length: 64] Interaction type
timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)
properties (object) – Optional. Additional data in interactions

EXAMPLE QUERY BODY¶

  {
      "interaction_type": "productView",
      "timestamp": 1588812345,
      "properties": {
          "revenue": 19.95
      }
  }

Response JSON Object

warnings (list-of-string) – Optional. List of warnings

Create Interactions for an Anonymous Session in Bulk¶

POST sessions/<str:session_id>/interactions-bulk/¶

Note

Authorized Roles: root, manager, backend, frontend

Create a small bulk of interactions for a single anonymous session and many items.

Request JSON Object

interactions (object-array) –
Interactions array
Inner fields
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
- interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type
- timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp
- properties (object-array) – (additional fields may be present) Additional data in interactions

EXAMPLE QUERY BODY¶

  {
      "interactions": [
          {"item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588854321, "properties": {"page": "pdp"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588811111, "properties": {"revenue": 19.95}}
      ]
  }

Response JSON Object

warnings (list-of-string) – Optional. List of warnings

List Interactions of one Anonymous Session In Bulk¶

GET sessions/<str:session_id>/interactions-bulk/¶

Note

Authorized Roles: root, manager, backend

This endpoint allows you to list the interactions of one anonymous session. The response is paginated, you can control the response amount and offset using the query parameters amt and cursor.

Query Parameters

amt (int) – Optional. [min: 1] Maximal amount of interactions to return
cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

EXAMPLE QUERY PARAMS¶

  ?amt=3&cursor=F25pU1vHb1LjSEp...

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
has_next (bool) – Indicates whether or not there are more interactions to request
next_cursor (string) – Optional. Pagination cursor, to use in next request to get more interactions
interactions (object-array) –
Anonymous Sessions Interactions array
Inner fields
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
- interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type
- timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp
- properties (object-array) – (additional fields may be present) Additional data in interactions
- session_id (ID) – [see Flexible Identifiers], [max_length: 64] Anonymous Session ID

EXAMPLE RESPONSE¶

  {
      "has_next": true,
      "next_cursor": "Q21vU1pHb1FjSEp...",
      "interactions": [
          { "item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588854321, , "properties": {"page": "pdp"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588811111, "properties": {"revenue": 19.95}}
      ]
  }

Create Interactions for Many Anonymous Sessions in Bulk¶

POST sessions-interactions-bulk/¶

Note

Authorized Roles: root, manager, backend

Create large bulks of interactions for many anonymous sessions and many items.

Request JSON Object

interactions (object-array) –
Anonymous Session Interactions array
Inner fields
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
- interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type
- timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp
- properties (object-array) – (additional fields may be present) Additional data in interactions
- session_id (ID) – [see Flexible Identifiers], [max_length: 64] Anonymous Session ID

EXAMPLE QUERY BODY¶

  {
      "interactions": [
          {"session_id": 1234, "item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"session_id": 1234, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588854321, "properties": {"page": "pdp"}},
          {"session_id": 333, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588811111, "properties": {"revenue": 19.95}}
      ]
  }

Response JSON Object

warnings (list-of-string) – Optional. List of warnings

List Interactions for All Anonymous Sessions In Bulk¶

GET sessions-interactions-bulk/¶

Note

Authorized Roles: root, manager, backend

List the anonymous session interactions of a database. The response being paginated, you control its size and offset using the query parameters amt and cursor.

Parameters start_timestamp and end_timestamp allow filtering out: interactions outside of a specified time frame.

Query Parameters

amt (int) – Optional. [min: 1] Maximal amount of interactions to return
cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response
start_timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Start timestamp of interactions to fetch
end_timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] End timestamp of interactions to fetch

EXAMPLE QUERY PARAMS¶

  ?amt=10&cursor=F25pU1vHb1LjSEp...&start_timestamp=1588811110.9&end_timestamp=1588854321.1

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
has_next (bool) – Indicates whether or not there are more interactions to request
next_cursor (string) – Optional. Pagination cursor, to use in next request to get more interactions
interactions (object-array) –
Anonymous Sessions Interactions array
Inner fields
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
- interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type
- timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp
- properties (object-array) – (additional fields may be present) Additional data in interactions
- session_id (ID) – [see Flexible Identifiers], [max_length: 64] Anonymous Session ID

EXAMPLE RESPONSE¶

  {
      "has_next": true,
      "next_cursor": "Q21vU1pHb1FjSEp...",
      "interactions": [
          {"session_id": 1234, "item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"session_id": 1234, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588854321, "properties": {"page": "pdp"}},
          {"session_id": 333, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588811111, "properties": {"revenue": 19.95}}
      ]
  }

Errors:

WrongData if both start_timestamp and end_timestamp are provided and start_timestamp >= end_timestamp

Resolve One Anonymous Session¶

POST sessions/<str:session_id>/resolve/¶

Note

Authorized Roles: root, manager, backend

This endpoint allows you to resolve an anonymous session with a user. One user can have many anonymous sessions, but an anonymous session can be resolved to a single user.

This endpoint is called from the backend only. When you need to send a new auth token to the frontend after an anonymous user logging-in, is it simpler to resolve and get a new token using POST login/service/ providing both the new frontend_user_id and the old frontend_session_id.

Request JSON Object

user_id (ID) – [see Flexible Identifiers], [max_length: 64] User ID
timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Resolved anonymous session timestamp. Default current time.

EXAMPLE QUERY BODY¶

  {
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "timestamp": 1588812345
  }

Errors:

WrongData if the anonymous session was previously resolved

List All Resolved Sessions In Pages¶

POST resolved-sessions/¶

Note

Authorized Roles: root, manager, backend

List anonymous sessions resolved. It is possible filter by users ids. The response being paginated, you control its size and offset using the query parameters amt and cursor.

Request JSON Object

users_id (ID-array) – Optional. Users IDs
amt (int) – Optional. [min: 1] Maximal amount per page
cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

EXAMPLE QUERY BODY¶

  {
      "users_id": [
          "123e4567-e89b-12d3-a456-426614174000",
          "c3391d83-553b-40e7-818e-fcf658ec397d"
      ],
      "amt": 10,
      "cursor": "F25pU1vHb1LjSEp..."
  }

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
resolved_sessions (object-array) –
Resolved Anonymous Sessions array
Inner fields
- session_id (ID) – [see Flexible Identifiers], [max_length: 64] Anonymous Session ID
- user_id (ID) – [see Flexible Identifiers], [max_length: 64] User ID
- timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Resolved timestamp
has_next (bool) – Indicates whether or not there are more anonymous sessions to request
next_cursor (string) – Optional. Pagination cursor, to use in next request to get more anonymous sessions

EXAMPLE RESPONSE¶

  {
      "has_next": true,
      "next_cursor": "Q21vU1pHb1FjSEp...",
      "resolved_sessions": [
          {"session_id": 1234, "user_id": "123e4567-e89b-12d3-a456-426614174000", "timestamp": 1588812345},
          {"session_id": 5678, "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "timestamp": 1588854321},
          {"session_id": 333, "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "timestamp": 1588811111}
      ]
  }