Managing assets

Use the REST API to do bulk mutation of assets when the Media library UI is not an efficient option. For example, to upload assets as part of a project to migrate content from a legacy system to Prepr CMS.

Before calling a REST API endpoint to manage the assets, go to Settings > Access tokens to create an access token with REST API scopes defined below.

If you already have an access token for a related mutation in the same workflow, for example, a content migration project, simply add the relevant REST API scopes to this access token.

The Asset object

When uploading or updating an asset, you can include some additional information about the asset in the body of your request like in the example below.

{
  "name": "Example cover image", 
    // If the name is not filled, the API will use the file name in this field. 
  "body": "This is an asset that I uploaded using REST API.",
    // A description for this asset. 
  "author": "Image Designer",
    // The author of the asset. 
  "reference_id": "12345678",
    // An external Id for the asset, for example an Id from a legacy system.
  "tags": { // Include a list of related keywords to find the asset easily
   // For each tag, set either the Id, body or slug
    "items": [
      {
        "id": "3dbf4dbe-9c87-4bae-9b23-7ae685655ea1"
        // Id of an existing tag in Prepr
      },
      {
        "body": "dynamic"
        // If this tag doesn't exist, it will automatically be created
      },
      {
        "slug": "dynamic-page"
        // If this tag doesn't exist, it will automatically be created
      }
    ]
  }
  "collections": { // Add this asset to a collection of similar assets
    "items": [
      {
        "id": "ebc7fd2c-2458-4f2f-b7f5-5487f63d412a", 
        // Id of an existing collection. Check out the Collections doc for more details.
      }
    ]
  }
}

Upload new files

Add the REST API scopes assets and assets_publish to the access token. The event asset.created will be fired when a new asset is created.

Upload Image + Document + Audio

To upload documents, photos or audio files send a POST request to the https://api.eu1.prepr.io/assets endpoint.

• If the files are available locally, add the source parameter to specify a file like in the example below. Make sure the Content-Type in the header is set to multipart/form-data to send a valid asset file.

{
  "source": "/Users/mike/images/hero.jpg"
}

curl --location 'https://api.eu1.prepr.io/assets' \
--header 'Authorization: Bearer ae1f665960cc3d14522c1377482b86b41172' \
--form 'source=@"/Users/mike/images/cover.jpg"'

• If the assets are located on a different server, set the url parameter to the URL location of the file like in the example code below. In this case, make sure the Content-Type in the header is set to application/json. You can upload files up to 25MB using the url parameter.

{
  "url": "https://placehold.co/800x800?text=Page%header%20image"
}

curl --location 'https://api.eu1.prepr.io/assets' \
--header 'Authorization: Bearer ae1f665960cc3d14522c1377482b86b41172' \
--form 'url="https://placehold.co/800x800?text=Page%header%20image"'

Upload Video

To upload videos follow the steps below to upload each video in chunks. Make sure to handle errors and resume the upload of any remaining chunks before finishing the upload of a video.

Step 1: Split the video into chunks

First split each video into 25MB (26214400 bytes) chunks using the bash command below.

split -b25m {filename}

Step 2: Start an upload session

Start a resumable upload by initializing a new asset object. To make a start request and create a video upload session, send a POST request to the https://api.eu1.prepr.io/assets endpoint. Set the parameters as shown in the example below.

{
  "label": "Video",
  "upload_phase": "start",
  "file_size": "8308859" 
    /*  
      The file size of the whole video file in bytes.
      It should match the size of the file you are going to upload. 
    */  
}

curl --location 'https://api.eu1.prepr.io/assets' \
--header 'Authorization: Bearer ae1f665960cc3d14522c1377482b86b41172' \
--form 'label="Video"' \
--form 'upload_phase="start"' \
--form 'file_size="8308859"'

When the upload is started successfully an auto-generated Id of the new asset will be returned in the response of this request. This Id can then be used in the request to upload the chunks and finish the request.

Step 3: Upload chunks

Now that the upload session has started and you have chunks ready to upload, make a transfer request to upload each chunk in the order that they are split.

To upload the first video chunk, send a POST request to the https://api.eu1.prepr.io/assets/{id}/multipart endpoint and set the parameters like in the example below. Replace {id} with the Id returned in the response of the previous request.

{
    "upload_phase": "transfer",
    "original_name": "intro.mp4",
    "file_chunk": "/Users/mike/videos/xaa"
}

curl --location 'https://api.eu1.prepr.io/assets/31f04a7a-5761-4a7f-8fc9-797813164c7e/multipart' \
--header 'Authorization: Bearer ae1f665960cc3d14522c1377482b86b41172' \
--form 'label="Video"' \
--form 'upload_phase="transfer"' \
--form 'file_chunk=@"/Users/mike/videos/xaa"' \
--form 'orginal_name="Complete tutorial"'

Step 4: Complete the upload

Once you upload all chunks, make a finish request to complete the upload, post the video, and queue it for asynchronous video-encoding. Send a POST request to the https://api.eu1.prepr.io/assets/{id}/multipart endpoint and set the parameters like in the example below. Replace {id} with the Id returned in the response of the start session request.

{
    "upload_phase": "finish"
}

curl --location 'https://api.eu1.prepr.io/assets/31f04a7a-5761-4a7f-8fc9-797813164c7e/multipart' \
--header 'Authorization: Bearer ae1f665960cc3d14522c1377482b86b41172' \
--form 'upload_phase="finish"'

Update

To update an existing asset, add the REST API scopes assets and assets_publish to the access token. Send a PUT request to the https://api.eu1.prepr.io/assets/{id} endpoint. The asset.changed event will be fired when the asset is changed.

Destroy

To destroy an existing asset, add the REST API scopes assets and assets_delete to the access token. Send a DELETE request to the https://api.eu1.prepr.io/assets/{id} endpoint. The asset.deleted event will be fired when the asset is deleted.