Two versions of the Management API

The Management API currently has two versions. For this reason, the cURL and JavaScript examples here use v2. For v1, you can only manage content items, their language variants, and assets. Until the .Net SDK is updated to v2, the examples here for .Net use v1.

Table of contents

Importing assets using the Management API is a 3-step process in which you:

Upload a file to Kentico Kontent.

Create a new asset using a reference to the file.

Link to the asset from a language variant of a content item.

The result has the following structure:

1. Uploading files

To upload a file to Kentico Kontent via API, send a POST request to the <YOUR_PROJECT_ID>/files/<YOUR_FILE_NAME> endpoint with your project ID and your file name filled in. For example, 975bf280-fd91-488c-994c-2f04416e5ee3/files/my_file.png.

Use your Management API Key in the authorization header of the request (in place of <YOUR_API_KEY> in the examples).

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

2. Creating 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_PROJECT_ID>/assets/external-id/<ASSET_EXTERNAL_ID> endpoint with your project ID and an external ID of your choice for the asset filled in.

Best practice: Referencing by external ID

Make it easier to reference your asset from content items by specifying an external ID. External IDs can point to non-existent (not yet imported) content. This way, you can import your assets and content items in any order and not worry about dependencies.

3. Using assets in content items

The content of an item is always 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.

Using assets in Asset elements

To use the imported asset in an asset element, you need to upsert a language variant by sending a PUT request to an endpoint specifying the content item (for example, /items/external-id/ext-cafe-brno) and the language of the variant (for example, /variants/codename/en-US). (This is the same item you worked with in Importing to Kentico Kontent.)

The request body must contain a single elements object. In it, you specify the content elements you want to update – in this case, only the photo asset element. The asset element takes an array of Reference objects, each containing either the internal ID or external ID of the asset.

The language variant of the item was updated and the Photo element now contains the imported asset. You can verify this by opening the item inside Kentico Kontent:

Using assets in rich text elements

You can also use assets as inline images in rich text elements.

For this example, we created a new item of the Article content type (which contains a Rich text element) with the external ID new-cafes.

To add your asset, you need to upsert a language variant by sending a PUT request to the /items/external-id/new-cafes/variants/codename/en-US endpoint, specifying the content item and the language of the variant.

The request body must contain a single elements object. In it, you specify the content elements you want to update – in this case, only the body_copy rich text element. Use the <figure> HTML element to add an image using its external ID.