Vionlabs Recommender API

Recommended For You

Generate personalized recommendations from a user's full viewing history.

Uses behavioral signals — both which items were watched and in what order — to recommend content tailored to the individual user.

Authorization

AuthorizationBearer <token>

Stytch access token authentication. Requires BOTH:

Authorization: Bearer ACCESS_TOKEN
catalog query parameter

Example: Authorization: Bearer ACCESS_TOKEN ?catalog=my_catalog

In: header

Query Parameters

version?|

Recommender product version to use. Defaults to a version pre-configured in Vionlabs systems if omitted.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

asset_type?|

Catalog item type to restrict results to: standalone (e.g. movies) or series. If omitted, all types are returned. May return fewer than k results when the catalog has few items of the requested type.

inventory_ids*array<string>

List of inventory IDs representing user viewing history

k?K

Number of recommendations to return

Default10

Range1 <= value <= 100

exclude_ids?array<string>

Inventory IDs to exclude from the results (e.g. items the user has already watched or that are already displayed in other carousels). Excluded items will never appear in the recommendations list.

include_ids?array<string>|

Inventory IDs that define the candidate pool. When set, recommendations are ranked only among these items instead of the full catalog.

user_id?|

Stable customer-provided user identifier. Used to improve recommendation quality over time. Does not influence ranking today but will enable per-user tuning in future versions. Must not contain direct PII (for example email or phone). Customers may send their own internal user IDs when those IDs do not contain PII. For stronger privacy, customers may send a deterministic pseudonymous token such as HMAC_SHA256(customer_secret, internal_user_id).

device_type?|

Coarse device category of the client making the request. Used to improve recommendation quality over time. Does not influence ranking today but will enable device-aware tuning in future versions.

Response Body

`application/json`

curl -X POST "https://example.com/results/recommender/v1/for-you" \  -H "Content-Type: application/json" \  -d '{    "inventory_ids": [      "string"    ]  }'

{
  "version": "string",
  "recommendations": [
    {
      "inventory_id": "string"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Because You Watched

Recommend content anchored on a single item, informed by behavioral data.

Unlike /more-like-this, this endpoint leverages viewing patterns across users (e.g. "users who watched X also watched Y") rather than pure content similarity. The order of items in aggregate viewing sequences influences the results.

Typical use: a home-screen row whose heading cites the anchor title, for example the Because you watched … pattern common in streaming apps.

Authorization

AuthorizationBearer <token>

Stytch access token authentication. Requires BOTH:

Authorization: Bearer ACCESS_TOKEN
catalog query parameter

Example: Authorization: Bearer ACCESS_TOKEN ?catalog=my_catalog

In: header

Query Parameters

version?|

Recommender product version to use. Defaults to a version pre-configured in the Vionlabs system if omitted.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

asset_type?|

inventory_id*Inventory Id

Anchor item to base behavioral recommendations on

k?K

Number of recommendations to return

Default10

Range1 <= value <= 100

exclude_ids?array<string>

Inventory IDs to exclude from the results (e.g. items the user has already watched or that are already displayed in other carousels). Excluded items will never appear in the recommendations list.

include_ids?array<string>|

Inventory IDs that define the candidate pool. When set, recommendations are ranked only among these items instead of the full catalog.

user_id?|

device_type?|

Coarse device category of the client making the request. Used to improve recommendation quality over time. Does not influence ranking today but will enable device-aware tuning in future versions.

Response Body

`application/json`

curl -X POST "https://example.com/results/recommender/v1/because-you-watched" \  -H "Content-Type: application/json" \  -d '{    "inventory_id": "string"  }'

{
  "version": "string",
  "recommendations": [
    {
      "inventory_id": "string"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

More Like This

Return items most similar to a single anchor item based on content attributes.

Purely item-based: results depend only on the anchor item's properties (genre, mood, narrative style, etc.) and do not use any behavioral or user-level data.

Typical use: a "More like this" section on a detail page.

Authorization

AuthorizationBearer <token>

Stytch access token authentication. Requires BOTH:

Authorization: Bearer ACCESS_TOKEN
catalog query parameter

Example: Authorization: Bearer ACCESS_TOKEN ?catalog=my_catalog

In: header

Query Parameters

version?|

Recommender product version to use. Defaults to a version pre-configured in the Vionlabs system if omitted.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

asset_type?|

inventory_id*Inventory Id

Anchor item to find content-similar items for

k?K

Number of similar items to return

Default10

Range1 <= value <= 100

exclude_ids?array<string>

Inventory IDs to exclude from the results (e.g. items the user has already watched or that are already displayed in other carousels). Excluded items will never appear in the recommendations list.

include_ids?array<string>|

Inventory IDs that define the candidate pool. When set, recommendations are ranked only among these items instead of the full catalog.

Response Body

`application/json`

curl -X POST "https://example.com/results/recommender/v1/more-like-this" \  -H "Content-Type: application/json" \  -d '{    "inventory_id": "string"  }'

{
  "version": "string",
  "recommendations": [
    {
      "inventory_id": "string"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Vionlabs Recommender API

200application/json

422application/json

200application/json

422application/json

200application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`