Vionlabs Docs
API Specs

Vionlabs Smartlist API

Programmatically access your organization's curated Smartlists - collections of movies and TV shows organized by themes, genres, moods, and custom filters.

Authentication

This API uses OAuth 2.0 Client Credentials flow with Stytch M2M tokens.

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
  3. Make API Calls: Include the access token in the Authorization header

Example Authentication

# Get Access Token
# Use https://api.stytch.com for production projects (project-live-*)
# Use https://test.stytch.com for test projects (project-test-*)
curl -X POST "https://api.stytch.com/v1/public/YOUR_PROJECT_ID/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"
  }'

# 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://0.0.0.0/smartlists"

Rate Limits

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

Support

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>

Stytch M2M access token obtained via OAuth 2.0 Client Credentials flow. 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
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"
publishing_state?string

Filter by publishing state (defaults to published only via API)

Value in"draft" | "published" | "in-review" | "archived" | "unpublished"
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://0.0.0.0/smartlists/?page=1&limit=20&creator=user%40example.com&purpose=editorial&publishing_state=draft&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
  }
}
{
  "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>

Stytch M2M access token obtained via OAuth 2.0 Client Credentials flow. 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://0.0.0.0/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>

Stytch M2M access token obtained via OAuth 2.0 Client Credentials flow. 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://0.0.0.0/smartlists/497f6eca-6276-4993-bfeb-53cbbbba6f08/assets?page=1&limit=20"
{
  "data": [
    {
      "asset_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
}

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

Authentication
Getting Started
Example Authentication
Rate Limits
Support