Vionlabs Docs
API Specs

Vionlabs Portal API

External docs:Swagger

Programmatically access your organization's curated Smartlists, Recipes, and Creative Assets.

Smartlists

Collections of movies and TV shows organized by themes, genres, moods, and custom filters.

Recipes

Configuration templates for generating thumbnails and preview clips from your content catalog.

Creative Assets

Generated thumbnails and preview clips created from Recipes applied to your assets.

Catalogs

Your organization's available content catalogs.

Authentication

This API uses OAuth 2.0 Client Credentials flow for authentication via Stytch.

Getting Started

  1. Create API Keys: Log in to app.vionlabs.com → Settings → API Keys
  2. Get Access Token: Exchange your Client ID and Client Secret for an access token using the Stytch OAuth2 endpoint
  3. Make API Calls: Include the access token in the Authorization header

Example Authentication

# Get Access Token from Stytch
curl -X POST "https://api.stytch.com/v1/public/project-live-ad1e793c-f32e-485c-b5a0-144d5cf64be7/oauth2/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "client_credentials",
    "scope": "read:smartlist:published read:recipe:published read:creative-asset:published"
  }'

# Response includes access_token
{
  "access_token": "eyJhbGci...",
  "expires_in": 3600,
  "token_type": "bearer"
}

# Use Token in API Requests
curl -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://apis.prod.vionlabs.com/smartlists"

Rate Limits

  • 1000 requests per hour per organization
  • Rate limit headers included in all responses

Support

/smartlists/docs

GET
/smartlists/docs

Authorization

AuthorizationBearer <token>

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

In: header

Response Body

curl -X GET "https://apis.prod.vionlabs.com/smartlists/docs"
Empty

/smartlists/docs/{*}

GET
/smartlists/docs/{*}

Authorization

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

*string

Response Body

curl -X GET "https://apis.prod.vionlabs.com/smartlists/docs/string"
Empty

/smartlists/openapi.json

GET
/smartlists/openapi.json

Authorization

AuthorizationBearer <token>

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

In: header

Response Body

curl -X GET "https://apis.prod.vionlabs.com/smartlists/openapi.json"
Empty

Get Access Token

Exchange your Client ID and Client Secret for an access token. This token is required for all API requests.

POST
/auth/token

Authorization

AuthorizationBearer <token>

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

In: header

Request Body

clientIdstring

Your API client ID

clientSecretstring

Your API client secret

scopes?array<string>

list of scopes (e.g., [read:smartlist:published, read:recipe:published, read:creative-asset:published])

Response Body

curl -X POST "https://apis.prod.vionlabs.com/auth/token" \  -H "Content-Type: application/json" \  -d '{    "clientId": "string",    "clientSecret": "string"  }'
{
  "access_token": "string",
  "token_type": "bearer",
  "expires_in": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}
{
  "error": "string",
  "message": "string",
  "statusCode": 0
}

List 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.

GET
/smartlists/

Authorization

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

curl -X GET "https://apis.prod.vionlabs.com/smartlists/?page=1&limit=20&catalogId=-9007199254740991&catalogName=string&creator=user%40example.com&purpose=editorial&is_ai_generated=true&search=string"
{
  "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

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.

GET
/smartlists/{id}

Authorization

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

idstring

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

curl -X GET "https://apis.prod.vionlabs.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

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.

GET
/smartlists/{id}/assets

Authorization

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

idstring

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

curl -X GET "https://apis.prod.vionlabs.com/smartlists/497f6eca-6276-4993-bfeb-53cbbbba6f08/assets?page=1&limit=20"
{
  "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

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

GET
/catalogs/

Authorization

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

curl -X GET "https://apis.prod.vionlabs.com/catalogs/?page=1&limit=20"
{
  "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

Retrieve details for a specific catalog by its ID.

GET
/catalogs/{id}

Authorization

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

idinteger

Unique identifier of the Catalog (integer)

Range-9007199254740991 <= value <= 9007199254740991

Response Body

curl -X GET "https://apis.prod.vionlabs.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

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.

GET
/recipes/

Authorization

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

curl -X GET "https://apis.prod.vionlabs.com/recipes/?page=1&limit=20&type=thumbnails&creator=user%40example.com&search=string"
{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "title": "string",
      "description": "string",
      "status": "string",
      "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

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.

GET
/recipes/{id}

Authorization

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

idstring

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

curl -X GET "https://apis.prod.vionlabs.com/recipes/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "id": "string",
  "title": "string",
  "description": "string",
  "status": "string",
  "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

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

GET
/creative-assets/

Authorization

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

curl -X GET "https://apis.prod.vionlabs.com/creative-assets/?page=1&limit=20&recipeId=497f6eca-6276-4993-bfeb-53cbbbba6f08&inventoryId=string&type=thumbnail"
{
  "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",
      "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

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

GET
/creative-assets/{id}

Authorization

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

idstring

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

curl -X GET "https://apis.prod.vionlabs.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",
  "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 Scene-Level Video-Text Retrieval API

The Scene Retrieval API offers semantic search capabilities for scenes across video asset(s).

Vionlabs Tasks API

API Documentation

On this page

Smartlists
Recipes
Creative Assets
Catalogs
Authentication
Getting Started
Example Authentication
Rate Limits
Support