Import assets

Jan Cerman

13 minutes

Download PDF

0% complete

Learn how to import a single asset to Kontent.ai and use the asset in a content item.

How importing assets work

Importing assets using the Management API is a 3-step process.

Upload a file to Kontent.ai.
Create a new asset using a reference to the uploaded file.
Link to the asset from a content item's language variant.

The result has the following structure:

1. Upload files

To upload a file via API, send a POST request to the <YOUR_ENVIRONMENT_ID>/files/<YOUR_FILE_NAME> endpoint with your project's environment ID and your file name filled in. For example, 975bf280-fd91-488c-994c-2f04416e5ee3/files/my%20file%232.png.

Set the Content-type header to the MIME type matching your file. For example, for a jpg image set the header to image/jpeg.
Set the Content-length header to a number matching the size of the file in bytes. For example, if the image is 12 kB, set the header to 12288.

Don't forget to set your Management API key in the request's authorization header (or the ManagementClient definition when using an SDK). You can only upload files from local storage. The Management API doesn't support uploading files from a URL.

This returns a file_reference object.

JSON

{
    "id": "8660e19c-7bbd-48a3-bb51-721934c7756c",
    "type": "internal"
}

You'll use the file_reference object to create the actual asset in the next step.

2. Create assets

To create an asset using the uploaded file, it's best to perform an upsert operation. This way, you can send the request repeatedly to update your asset. This means sending a PUT request to the <YOUR_ENVIRONMENT_ID>/assets/external-id/<ASSET_EXTERNAL_ID> endpoint with your project's environment ID and an external ID of your choice for the asset filled in.

In the body of the request, specify these properties:

file_reference – use the file reference you obtained in the previous step to link the asset with your file.
(Optional) title – specify a title for the asset (displayed in the administration interface).
descriptions – specify an asset description for each language.
- language – can be specified by its codename or internal id.
- description – string with a description of the asset.

See our API reference for more details on upserting assets by external id. The response will include an asset object:

JSON

{
  "id": "8d0baeb7-1165-5f13-b72e-b23fc39fc549",
  "file_name": "brno-cafe-1080px.jpg",
  "title": "Brno Cafe",
  "size": 481939,
  "image_width": 1920,
  "image_height": 1440,
  "type": "image/jpeg",
  "file_reference": {
    "id": "8660e19c-7bbd-48a3-bb51-721934c7756c",
    "type": "internal"
  },
  "descriptions": [
    {
      "language": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "description": "Cafe in Brno"
    },
    {
      "language": {
        "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
      },
      "description": "Café en Brno"
    }
  ],
  "external_id": "brno-cafe-image",
  "last_modified": "2021-04-10T09:44:39.0111761Z"
}

To verify the creation of the asset, you can view it in Kontent.ai:

3. Use assets in content items

The content of an item is stored in a specific language variant. Within the language variant, you can use the imported asset in asset and rich text elements. The asset might need to meet the limitations set for the item's content type.

Use assets in Asset elements

Sign in with your Kontent.ai credentials or sign up for free to unlock the full lesson, track your progress, and access exclusive expert insights and tips!