Upload asset to DAM

How to upload asset using Management API

Creating a new asset is a multi-step process. The asset will not be available in the DAM until all operations are completed.

  1. Create a new empty asset
  2. Upload the file to AWS S3
  3. Add metadata to the asset
  4. Complete the asset

 

Create a new empty asset

URL

POST https://mapi.bluestonepim.com/media/upload

Request body

{
  "fileName": "new-asset.jpg",
  "contentType": "image/jpeg"
}

File name for the asset will be displayed in PIM UI as "Original filename". Content type will determine what type it gets in the DAM. 

Response body

{
    "id": "0d9a2052-0975-4568-8f6e-5c9ebe08f85f",
  "actionUrl": "https://webon-test-media-bank.s3-eu-central-1.amazonaws.com/",
    "parameters": [
        {
            "key": "x-amz-date",
            "value": "20220502T000000Z"
        },
        {
            "key": "success_action_status",
            "value": "201"
        },
        {
            "key": "x-amz-signature",
          "value": "7fe2c610de59d04e029ab79016a64dff11e82758e4d1ba6d81732a468ab4a2"
        },
        {
            "key": "content-type",
            "value": "image/jpeg"
        },
        {
            "key": "x-amz-security-token",
          "value": "IQoJb3JpZ2luX2VjEHUaDGV1bnRyYWwtMSJGMEQCIB1XvfvIbaaoaprFe7UkBtZ0EA89WCkGWxBpLszAIQAiBJc37vaI+uL25HF5ff9EvhcidNgsIp25efbSZkZSXyVyr3Awg+EAMaDDY4OTk0NzY3MTg2MSIMtxVmAdOnyWTJnIdQKtQDUhgDQdtcQL5H2tOsCk2rXdQ1j3T5Dlm2C6b16sP4GMTl9aqvmn3jvMZ7WburOm8eE2h1WFvm8QEh8D1C+zQPsgCsdvx5FZXUQIsIQgViQueEysD3x97m5Bh/cOefynjEeLkqNeSJ9Au/Ao5yboWnsHsVyKiZdVqjkjRYIUSmGJmWLKw60tW2W3a+5ZaHEhBDlvkEeuMbcbuRK9ygIhM0s0ETOa+YuZAiIkpuZ5ERe5rqMy29CXjXHZRyslIbuaWPtKmRCI9gWItjQX6oJgNVmCIMQ/lWHxbOz5LAIAdIahRaVS+mJv6UPdqOS9jBwtALAhffb3rBYlOO3i4dvQ8OEkTqWOpWuNRMJgbTI9L0Utk6QS69JZionaXRqqJ/jzItXmuDsxJoPAjOOP20KeUtEOYv0N9RDv1B0HtVL0/dg2BpuuEua6cFEYzckCk6SUENzZc0hQa/2RqufdVWerrQ5waqKjHKRVSvgVdCJP925uy5gBhmeynRTzIBPD9ZegBI05QokhyDeS4h29bLfHCEKGRLwKSs+sbYEymsvNzvbiOE80HURx+IOpCWaulNVJ30wSjlqOA/ONuEX2dN+ojcSY6KGusjhQD2OGOVe94elw27GGynMLrPvZMGOqYBQ1oRVAkJ4VtdDeaSUPemKlOnuDHvLvES+4wutEd5KvBm65FRxuD+UM8fsRcFyxHd59CS3Nnq7qADrxtr5KYaSuPNlvje42uUEZrVvABA+APNeH+shWAiaRikgQWAo/nc2Y2hGkkM2GseSWHn9I7wQLqiy0M42T+oefx+fAThRoKQUpijU7ntP9xfmK43ZdIBGOUGY4P4eFWWroLXjsB35QvmtZ9Hew=="
        },
        {
            "key": "key",
          "value": "4c99b917-30a5-4dff-9916-6caf62/0d9a2052-0975-4568-8f6e-5c9ebe08f85f/O6JfCk719V1XV5anmQe0OXhL6/DylFQioaaQk1UCZwn0Iwecrg7.jpg"
        },
        {
            "key": "x-amz-algorithm",
            "value": "AWS4-HMAC-SHA256"
        },
        {
            "key": "policy",
          "value": "eyJleHBpcmF0aW9uIjoiMjAyMi0wNSwODozODowMC4wMDBaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0Ijoid2Vib24tdGVzdC1tZWRpYS1iYW5rIn0seyJrZXkiOiI0Yzk5YjkxNy0zMGE1LTRkZmYtOTkxNi02Y2ExNzI4YWZmNjIvMGQ5YTIwNTItMDk3NS00NTY4LThmNmUtNWM5ZWJlMDhmODVmL082SmZDazcxOVYxWFY1YW5tUWUwT1hoTDYvRHlsRlFpb2FhUWsxVUNad24wSXdlY3JnNy5qcGcifSx7ImNvbnRlbnQtdHlwZSI6ImltYWdlL2pwZWcifSx7IngtYW16LWFsZ29yaXRobSI6IkFXUzQtSE1BQy1TSEEyNTYifSx7IngtYW16LWNyZWRlbnRpYWwiOiJBU0lBMkJKQVY3VTJYV1UyV0UyUy8yMDIyMDUwMi9ldS1jZW50cmFsLTEvczMvYXdzNF9yZXF1ZXN0In0seyJ4LWFtei1zZWN1cml0eS10b2tlbiI6IklRb0piM0pwWjJsdVgyVmpFSFVhREdWMUxXTmxiblJ5WVd3dE1TSkdNRVFDSUIxWHZmcFh2SWJhYW9hcHJGZTdVa0J0WjBFQTg5V0NrR1d4QnBMc3pBSVFBaUJKYzM3dmFJK3VMMjVIRjVmZjlFdmhjaWROZ3NJcDI1ZWZiU1prWlNYeVZ5cjNBd2crRUFNYUREWTRPVGswTnpZM01UZzJNU0lNdHhWbUFkT255V1RKbklkUUt0UURVaGdEUWR0Y1FMNUgydE9zQ2syclhkUTFqM1Q1RGxtMkM2YjE2c1A0R01UbDlhcXZtbjNqdk1aN1didXJPbThlRTJoMVdGdm04UUVoOEQxQyt6UVBzZ0NzZHZ4NUZaWFVRSXNJUWdWaVF1ZUV5c0QzeDk3bTVCaC9jT2VmeW5qRWVMa3FOZVNKOUF1L0FvNXlib1duc0hzVnlLaVpkVnFqa2pSWUlVU21HSm1XTEt3NjB0VzJXM2ErNVphSEVoQkRsdmtFZXVNYmNidVJLOXlnSWhNMHMwRVRPYStZdVpBaUlrcHVaNUVSZTVycU15MjlDWGpYSFpSeXNsSWJ1YVdQdEttUkNJOWdXSXRqUVg2b0pnTlZtQ0lNUS9sV0h4Yk96NUxBSUFkSWFoUmFWUyttSnY2VVBkcU9TOWpCd3RBTEFoZmZiM3JCWWxPTzNpNGR2UThPRWtUcVdPcFd1TlJNSmdiVEk5TDBVdGs2UVM2OUpaaW9uYVhScXFKL2p6SXRYbXVEc3hKb1BBak9PUDIwS2VVdEVPWXYwTjlSRHYxQjBIdFZMMC9kZzJCcHV1RXVhNmNGRVl6Y2tDazZTVUVOelpjMGhRYS8yUnF1ZmRWV2VyclE1d2FxS2pIS1JWU3ZnVmRDSlA5MjV1eTVnQmhtZXluUlR6SUJQRDlaZWdCSTA1UW9raHlEZVM0aDI5YkxmSENFS0dSTHdLU3Mrc2JZRXltc3ZOenZiaU9FODBIVVJ4K0lPcENXYXVsTlZKMzB3U2pscU9BL09OdUVYMmROK29qY1NZNktHdXNqaFFEMk9HT1ZlOTRlbHcyN0dHeW5NTHJQdlpNR09xWUJRMW9SVkFrSjRWdGREZWFTVVBlbUtsT251REh2THZFUys0d3V0RWQ1S3ZCbTY1RlJ4dUQrVU04ZnNSY0Z5eEhkNTlDUzNObnE3cUFEcnh0cjVLWWFTdVBObHZqZTQydVVFWnJWdkFCQStBUE5lSCtzaFdBaWFSaWtnUVdBby9uYzJZMmhHa2tNMkdzZVNXSG45STd3UUxxaXkwTTQyVCtvZWZ4K2ZBVGhSb0tRVXBpalU3bnRQOXhmbUs0M1pkSUJHT1VHWTRQNGVGV1dyb0xYanNCMzVRdm10WjlIZXc9PSJ9LHsieC1hbXotZGF0ZSI6IjIwMjIwNTAyVDAwMDAwMFoifSxbImVxIiwiJHN1Y2Nlc3NfYWN0aW9uX3N0YXR1cyIsIjIwMSJdLFsiY29udGVudC1sZW5ndGgtcmFuZ2UiLDAsMTA3Mzc0MTgyNDBdXX0="
        },
        {
            "key": "x-amz-credential",
            "value": "ASIA2BJAV7U2XWU2WE2S/20220502/eu-central-1/s3/aws4_request"
        }
    ]
}

The id is the Bluestone PIM asset id to use in subsequent calls. The rest of the response content should be used to upload the file in the next step.

Try it in readme.io

 

Upload the file to AWS S3

The file upload is done directly to S3 using a presigned URL.

URL

Use the actionUrl (https://webon-test-media-bank.s3-eu-central-1.amazonaws.com/) from the previous response to do a POST request to AWS S3.

Request headers

The Content-Type header of the request should be multipart/form-data.

Request body

The rest of the parameters from the previous response should be added as form data.

Add a file parameter containing the upload file.

The order of parameters can be significant. Start with the key and end with the file.

Here is an example screenshot from a Postman request. 

Response body

<?xml version="1.0" encoding="UTF-8"?>
<PostResponse>
  <Location>https://webon-test-media-bank.s3-eu-central-1.amazonaws.com/4c99b917-30a5-4dff-9916-6caaff62%2F0d9a2052-0975-4568-8f6e-5c9ebe08f85f%2FO6JfCk719V1XV5anmQe0OXhL6%2FDylFQioaaQk1UCZwn0Iwecrg7.jpg</Location>
    <Bucket>webon-test-media-bank</Bucket>
  <Key>4c99b917-30a5-4dff-9916-6caf62/0d9a2052-0975-4568-8f6e-5c9ebe08f85f/O6JfCk719V1XV5anmQe0OXhL6/DylFQioaaQk1UCZwn0Iwecrg7.jpg</Key>
    <ETag>"7e4d7e6908ffad1ab1395b7ca8b4681f"</ETag>
</PostResponse>

If successful, the response status will be 201 - Created. 

Add metadata to the asset

URL

PUT https://mapi.bluestonepim.com/media/upload/{id}

Use asset id from the first response in the path.

Request body

{
  "name": "Sample asset name",
  "number": "asset-123",
  "description": "More sample text about the asset",
  "labels": [
    "6c159583-a699-4f79-87bc-1852a132694c",
    "11afedc6-abc3-4f26-904a-6768e98d538c"
  ],
  "folderId": null,
  "internal": false
}
  • name: Custom asset name
  • number: Custom unique identifier that can be used to match an asset across different systems. Will typically be set to the id of the system where the asset originated or where the asset is to be exported. Will be auto-generated if null.
  • description: Custom asset description.
  • labels: List of label id's. 
  • folderId: Folders can be used to manage access to media for restricted users. 
  • internal: By default, assets are not publicly accessible. When an asset is connected to a published product, the asset is also published. If the internal flag is set to "true", the asset will never be published regardless. 

Response body

{
    "id": "0d9a2052-0975-4568-8f6e-5c9ebe08f85f",
    "mediaInfo": {
        "mediaType": "IMAGE",
      "fileKey": "4c99b917-30a5-4dff-9916-6caf62/0d9a2052-0975-4568-8f6e-5c9ebe08f85f/O6JfCk719V1XV5anmQe0OXhL6/DylFQioaaQk1UCZwn0Iwecrg7.jpg",
        "versionId": "O6JfCk719V1XV5anmQe0OXhL6",
        "container": "webon-test-media-bank"
    },
    "name": "Sample asset name",
    "description": "More sample text about the asset",
    "labels": [
        "6c159583-a699-4f79-87bc-1852a132694c",
        "11afedc6-abc3-4f26-904a-6768e98d538c"
    ],
    "internal": false
}

Returns 200 - OK if successful. 

Try it in readme.io

Complete the asset

Call this endpoint to let the DAM know that the asset is finished and ready for use. At this point, it will be made available to the users in PIM. 

URL

POST https://mapi.test.bluestonepim.com/media/upload/{id}/done

Use asset id from the first response in the path.

Request body

No request body.

Response

Returns 204 - Created if successful. 

Try it in readme.io