Vionlabs Docs
API Specs

Vionlabs Portal API

External docs:Swagger

List Smartlists

GET
/smartlists/

Retrieve a paginated list of published Smartlists for your organization. Filter by creator, purpose, AI-generated status, or search by title. Use pagination to handle large collections efficiently.

Authorization

BearerAuth
AuthorizationBearer <token>

Access token obtained via OAuth 2.0 Client Credentials flow from Stytch. Include as: Authorization: Bearer YOUR_ACCESS_TOKEN

In: header

Query Parameters

page?integer

Page number for pagination (starts at 1)

Default1
Range1 <= value <= 9007199254740991
limit?integer

Number of items per page (max: 100)

Default20
Range1 <= value <= 100
catalogId?integer

Filter by catalog ID. If not provided, returns smartlists from all accessible catalogs.

Range-9007199254740991 <= value <= 9007199254740991
catalogName?string

Filter by catalog name (exact match). More user-friendly than catalogId since catalog names are visible in the portal.

creator?string

Filter by creator email address

Match^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
Formatemail
purpose?string

Filter by smartlist purpose: editorial (curated collections), creative-lab (marketing campaigns), review-filter (quality control)

Value in"editorial" | "creative-lab" | "review-filter"
is_ai_generated?string

Filter by AI-generated smartlists (true) or manually curated (false)

Value in"true" | "false"
search?string

Search smartlists by title (case-insensitive partial match)

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/smartlists/"
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "title": "string",
      "description": "string",
      "type": "string",
      "publishing_state": "string",
      "purpose": [
        "string"
      ],
      "is_ai_generated": true,
      "creator": "user@example.com",
      "item_count": 0,
      "published_at": "string",
      "created_at": "string",
      "updated_at": "string",
      "_links": {
        "self": "http://example.com",
        "assets": "http://example.com"
      }
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 0,
    "total": 0,
    "total_pages": 0
  },
  "_links": {
    "catalogs": "http://example.com"
  }
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}

Get Smartlist Details

GET
/smartlists/{id}

Retrieve complete details for a specific Smartlist, including its full filter configuration. The filter configuration shows exactly which criteria (genres, release years, keywords, moods, ratings, etc.) define which assets belong to this collection.

Authorization

BearerAuth
AuthorizationBearer <token>

Access token obtained via OAuth 2.0 Client Credentials flow from Stytch. Include as: Authorization: Bearer YOUR_ACCESS_TOKEN

In: header

Path Parameters

id*string

Unique identifier of the Smartlist (UUID format)

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/smartlists/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "title": "string",
  "description": "string",
  "type": "string",
  "publishing_state": "string",
  "purpose": [
    "string"
  ],
  "is_ai_generated": true,
  "creator": "user@example.com",
  "item_count": 0,
  "published_at": "string",
  "created_at": "string",
  "updated_at": "string",
  "_links": {
    "self": "http://example.com",
    "assets": "http://example.com"
  },
  "catalog": "string",
  "filter": {
    "property1": null,
    "property2": null
  }
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}

Get Smartlist Assets

GET
/smartlists/{id}/assets

Retrieve a paginated list of all assets (movies and TV shows) that belong to a specific Smartlist. Each asset includes its position within the collection. Use pagination to efficiently handle large Smartlists.

Authorization

BearerAuth
AuthorizationBearer <token>

Access token obtained via OAuth 2.0 Client Credentials flow from Stytch. Include as: Authorization: Bearer YOUR_ACCESS_TOKEN

In: header

Path Parameters

id*string

Unique identifier of the Smartlist (UUID format)

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid

Query Parameters

page?integer

Page number for pagination (starts at 1)

Default1
Range1 <= value <= 9007199254740991
limit?integer

Number of assets per page (max: 100)

Default20
Range1 <= value <= 100

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/smartlists/497f6eca-6276-4993-bfeb-53cbbbba6f08/assets"
{
  "data": [
    {
      "inventory_id": "string",
      "title": "string",
      "position": 0
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 0,
    "total": 0,
    "total_pages": 0
  },
  "_links": {
    "smartlist": "http://example.com"
  }
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}

List Catalogs

GET
/catalogs/

Retrieve a paginated list of all catalogs available to your organization. Use catalog IDs to filter smartlists by specific content catalogs.

Authorization

BearerAuth
AuthorizationBearer <token>

Access token obtained via OAuth 2.0 Client Credentials flow from Stytch. Include as: Authorization: Bearer YOUR_ACCESS_TOKEN

In: header

Query Parameters

page?integer

Page number for pagination (starts at 1)

Default1
Range1 <= value <= 9007199254740991
limit?integer

Number of items per page (max: 100)

Default20
Range1 <= value <= 100

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/catalogs/"
{
  "data": [
    {
      "id": 0,
      "name": "string",
      "status": "active",
      "account": "string",
      "created_at": "string",
      "updated_at": "string",
      "_links": {
        "self": "http://example.com",
        "smartlists": "http://example.com"
      }
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 0,
    "total": 0,
    "total_pages": 0
  },
  "_links": {
    "smartlists": "http://example.com"
  }
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}

Get Catalog Details

GET
/catalogs/{id}

Retrieve details for a specific catalog by its ID.

Authorization

BearerAuth
AuthorizationBearer <token>

Access token obtained via OAuth 2.0 Client Credentials flow from Stytch. Include as: Authorization: Bearer YOUR_ACCESS_TOKEN

In: header

Path Parameters

id*integer

Unique identifier of the Catalog (integer)

Range-9007199254740991 <= value <= 9007199254740991

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/catalogs/-9007199254740991"
{
  "id": 0,
  "name": "string",
  "status": "active",
  "account": "string",
  "created_at": "string",
  "updated_at": "string",
  "_links": {
    "self": "http://example.com",
    "smartlists": "http://example.com"
  }
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}

List Recipes

GET
/recipes/

Retrieve a paginated list of published Recipes for your organization. Filter by type, creator, or search by title. Use pagination to handle large collections efficiently.

Authorization

BearerAuth
AuthorizationBearer <token>

Access token obtained via OAuth 2.0 Client Credentials flow from Stytch. Include as: Authorization: Bearer YOUR_ACCESS_TOKEN

In: header

Query Parameters

page?integer

Page number for pagination (starts at 1)

Default1
Range1 <= value <= 9007199254740991
limit?integer

Number of items per page (max: 100)

Default20
Range1 <= value <= 100
type?string

Filter by recipe product type: thumbnails or preview-clips

Value in"thumbnails" | "preview-clips"
creator?string

Filter by creator email address

Match^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
Formatemail
search?string

Search recipes by title (case-insensitive partial match)

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/recipes/"
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "title": "string",
      "description": "string",
      "status": "draft",
      "type": "string",
      "creator": "user@example.com",
      "catalog": "string",
      "test_runs_count": 0,
      "published_at": "string",
      "created_at": "string",
      "updated_at": "string",
      "_links": {
        "self": "http://example.com"
      }
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 0,
    "total": 0,
    "total_pages": 0
  }
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}

Get Recipe Details

GET
/recipes/{id}

Retrieve complete details for a specific Recipe, including its full configuration. The configuration shows the parameters and settings used for generating thumbnails or preview clips.

Authorization

BearerAuth
AuthorizationBearer <token>

Access token obtained via OAuth 2.0 Client Credentials flow from Stytch. Include as: Authorization: Bearer YOUR_ACCESS_TOKEN

In: header

Path Parameters

id*string

Unique identifier of the Recipe (UUID format)

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/recipes/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "id": "string",
  "title": "string",
  "description": "string",
  "status": "draft",
  "type": "string",
  "creator": "string",
  "catalog": "string",
  "test_runs_count": 0,
  "config": {
    "property1": null,
    "property2": null
  },
  "version": 0,
  "published_at": "string",
  "created_at": "string",
  "updated_at": "string",
  "_links": {
    "self": "string"
  }
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}

List Creative Assets

GET
/creative-assets/

Retrieve a paginated list of Creative Assets for your organization. Filter by recipe, asset, status, or type. Use pagination to handle large collections efficiently.

Authorization

BearerAuth
AuthorizationBearer <token>

Access token obtained via OAuth 2.0 Client Credentials flow from Stytch. Include as: Authorization: Bearer YOUR_ACCESS_TOKEN

In: header

Query Parameters

page?integer

Page number for pagination (starts at 1)

Default1
Range1 <= value <= 9007199254740991
limit?integer

Number of items per page (max: 100)

Default20
Range1 <= value <= 100
recipeId?string

Filter by recipe ID

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
inventoryId?string

Filter by customer's asset inventory ID

type?string

Filter by creative asset type

Value in"thumbnail" | "preview" | "thumbnail-vertical" | "preview-vertical"

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/creative-assets/"
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "title": "string",
      "type": "string",
      "status": "string",
      "recipe_id": "fa7d15d4-7670-4586-a94b-5079ed028135",
      "recipe_title": "string",
      "inventory_id": "string",
      "asset_title": "string",
      "image_uri": "string",
      "image_url": "string",
      "small_image_uri": "string",
      "small_image_url": "string",
      "video_uri": "string",
      "video_url": "string",
      "start_time": 0,
      "stop_time": 0,
      "metadata": {
        "property1": null,
        "property2": null
      },
      "logo_data": {
        "has_logo": true,
        "coordinates": [
          0
        ],
        "size": 0,
        "logo_image": "string",
        "logo_name": "string",
        "score": 0
      },
      "created_at": "string",
      "updated_at": "string",
      "_links": {
        "self": "http://example.com",
        "recipe": "http://example.com"
      }
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 0,
    "total": 0,
    "total_pages": 0
  }
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}

Get Creative Asset Details

GET
/creative-assets/{id}

Retrieve complete details for a specific Creative Asset, including URIs, asset information, and recipe information.

Authorization

BearerAuth
AuthorizationBearer <token>

Access token obtained via OAuth 2.0 Client Credentials flow from Stytch. Include as: Authorization: Bearer YOUR_ACCESS_TOKEN

In: header

Path Parameters

id*string

Unique identifier of the Creative Asset (UUID format)

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/creative-assets/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "title": "string",
  "type": "string",
  "status": "string",
  "recipe_id": "fa7d15d4-7670-4586-a94b-5079ed028135",
  "recipe_title": "string",
  "inventory_id": "string",
  "asset_title": "string",
  "image_uri": "string",
  "image_url": "string",
  "small_image_uri": "string",
  "small_image_url": "string",
  "video_uri": "string",
  "video_url": "string",
  "start_time": 0,
  "stop_time": 0,
  "metadata": {
    "property1": null,
    "property2": null
  },
  "logo_data": {
    "has_logo": true,
    "coordinates": [
      0
    ],
    "size": 0,
    "logo_image": "string",
    "logo_name": "string",
    "score": 0
  },
  "created_at": "string",
  "updated_at": "string",
  "_links": {
    "self": "http://example.com",
    "recipe": "http://example.com"
  },
  "run_number": 0,
  "asset_index": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}

Vionlabs Recommender API

The Vionlabs Recommender API delivers content recommendations for movies and series, powered by Vionlabs' proprietary content-understanding technology. ## Endpoints The API exposes three recommendation strategies, each designed for a distinct UI placement: | Endpoint | Signal | Typical UI placement | |---|---|---| | **POST /for-you** | Full viewing history (behavioral) | Personalized "Top picks for you" row | | **POST /because-you-watched** | Single anchor item (behavioral) | "Because you watched *Title*" row | | **POST /more-like-this** | Single anchor item (content similarity) | "More like this" on a detail page | **`/for-you`** and **`/because-you-watched`** leverage aggregate viewing patterns across users — the items people watch *and the order in which they watch them* — to surface behaviorally relevant recommendations. **`/more-like-this`** is purely content-based: results depend only on the anchor item's attributes (genre, mood, narrative style, etc.) and require no user-level data.