2. Create and manage your Viewable

In the Magine Pro platform, a Viewable (metadata asset) is linked to a VOD (Playable) file to present content to end users. This linkage allows users to browse, view, and interact with content through the platform.

There are two approaches to creating this relationship:

• Option 1: Transcode the VOD first — the system will automatically generate a minimal Viewable.
• Option 2 (Recommended in this guide): Create the Viewable first, then associate it with a VOD.

This guide follows the second approach: creating the Viewable first.

1. Create a Viewable

To create a new Viewable, use the following API endpoint:

🔗 Create Viewable

In the response, you’ll receive a unique viewableId. This ID is required for subsequent steps, such as uploading images, triggering transcoding, or updating metadata.

2. Add Images to the Viewable

To associate images (e.g., posters, thumbnails) with your Viewable, use this endpoint:

🔗 Add or replace Image

Ensure you have the correct viewableId and imageType when making this request.

3. Update the Viewable

If you need to modify your Viewable after creation, use the PATCH endpoint:

🔗 Patch Viewable

⚠️

Important:

There is also a PUT endpoint available to update a Viewable. However, using PUT will overwrite the entire Viewable metadata, potentially removing data automatically added by the Magine Pro platform (such as internal flags or linked entities).

For partial updates, always use PATCH to avoid unintentional data loss.

📁 Example

Create viewable request

curl --request POST \
     --url https://platform-api.magine.com/api/v1/partner/viewables \
     --header 'Magine-AccessToken: 545bcd17-5a88-4311-a483-e4329ac06af3' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {JWT}' \
     --header 'content-type: application/json' \
     --data '
{
  "metadata": {
    "kind": "movie",
    "title": "Test 0001",
    "synopsis": "This is my test Movie",
    "genres": [
      "Test genre"
    ]
  }
}
'

Create viewable response

{
  "id": "075753f9-a410-467e-b7bb-0d9c50d015ad",
  "partnerId": "magine-pro-demo",
  "metadata": {
    "labels": [
      "genre_Test genre"
    ],
    "kind": "movie",
    "title": "Test 0001",
    "genres": [
      "Test genre"
    ],
    "synopsis": "This is my test Movie"
  },
  "createdAt": 1748421456,
  "modifiedAt": 1748421456,
  "publish": true
}