Recommendations

This guide explains how to retrieve content recommendations from the Streamdiver API. Recommendations help users discover relevant media assets — videos, audio recordings, or documents — based on content similarity or personal viewing history.

What Is the Recommendation Engine?

The Streamdiver recommendation engine analyses the metadata, transcripts, and tags of your media library to suggest content that is contextually related to a given input. It supports two modes:

• Content-based — provide one or more media assets or sections as a seed, and the engine returns similar content.
• User-based — the engine uses the authenticated user's viewing history to compute personalised suggestions.

Both modes return results scoped to the channels and permissions of the requesting user, so recommendations never expose content the user is not allowed to see.

Section-level recommendations for smarter video consumption

Unlike traditional video recommendation systems that only suggest entire videos, Streamdiver recommends at the section level. Sections are created automatically by the platform's AI-powered auto-chaptering engine, which analyses transcripts and visual cues to segment a video into coherent, self-contained topics.

This means a 90-minute conference recording doesn't have to be recommended as a single block. Instead, the API can point users to the specific 5-minute segment that is relevant to what they are watching — enabling faster knowledge discovery and a significantly better viewing experience.

Content-Based Recommendations

Retrieve recommendations by passing one or more media asset IDs, section IDs, and optionally channel IDs as query parameters. The engine uses the metadata of the specified input to find related content.

curl 'https://api.streamdiver.com/v2/recommendations?mediaIds=8f8e0e9f-2ce8-4efd-8b07-9fc85db331e9&sectionIds=1a6ea046-6493-473e-914b-8894b6036076&channelIds=c3b1a7d2-45ef-4a12-b890-1234abcd5678' \
  --header 'Authorization: Bearer eyJh...20yA'

Query Parameters

Parameter	Description
mediaIds	One or more media asset IDs to use as seed for recommendations.
sectionIds	One or more media section IDs to use as seed for recommendations.
channelIds	Optional. Restrict recommendations to specific channels.
page	Page number for paginated results.
perPage	Number of recommendations per page.

You can repeat mediaIds, sectionIds, and channelIds to pass multiple values.

User-Based Recommendations

As an alternative to providing explicit input, you can retrieve personalised recommendations for the currently authenticated user. The engine analyses previously viewed content to suggest new, relevant assets.

note

This endpoint requires a registered and authenticated user. Anonymous or API-key-only requests will receive a 401 or 403 response.

curl 'https://api.streamdiver.com/v2/recommendations/users/current' \
  --header 'Authorization: Bearer eyJh...20yA'

Query Parameters

Parameter	Description
page	Page number for paginated results.
perPage	Number of recommendations per page.

Response Format

Both endpoints return the same response structure. Each recommended media asset includes its metadata, relevant sections (for audio and video), and the channels it belongs to. Sections are grouped under their parent asset so you can display recommendations in a structured way.

note

The API only recommends media assets that the current user has permission to access.

{
  "data": {
    "mediaAssets": [
      {
        "id": "09a40e8f-f561-4274-9337-9f148ec8ef22",
        "audit": { "...": "..." },
        "name": "Annual Product Launch Keynote",
        "description": "Recording of the annual product launch event, including feature demos, roadmap preview, and live Q&A session.",
        "type": "video",
        "slug": "annual-product-launch-keynote",
        "shortId": "7f734e6",
        "thumbnail": {
          "height": 1080,
          "width": 1920,
          "url": "https://api.streamdiver.com/v2/thumbnails/09a40e8f..."
        },
        "preview": {
          "url": "https://cdn.streamdiver.com/vod/09a40e8f-preview.mp4"
        },
        "tags": ["product-launch", "keynote", "roadmap"],
        "filesize": 524288000,
        "bitrate": 8000000,
        "duration": 2700.0,
        "usage": {
          "views": 1420,
          "downloads": 38
        },
        "videoHeight": 1080,
        "videoWidth": 1920,
        "channels": [
          {
            "id": "c3b1a7d2-45ef-4a12-b890-1234abcd5678",
            "name": "Public Events",
            "visibility": "public"
          }
        ],
        "sections": [
          {
            "sectionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "start": 120.5,
            "duration": 340.0,
            "title": "New Feature Demo: AI Transcription",
            "summary": "Live demonstration of the AI-powered transcription engine, covering multi-language support and speaker recognition.",
            "thumbnail": {
              "height": 1080,
              "width": 1920,
              "url": "https://api.streamdiver.com/v2/thumbnails/a1b2c3d4..."
            },
            "preview": {
              "url": "https://cdn.streamdiver.com/vod/a1b2c3d4-preview.mp4"
            }
          }
        ],
        "permissions": [
          "viewChannel"
        ]
      }
    ]
  },
  "status": "success"
}