Importing assets

In this tutorial, you will import a single asset to Kentico Cloud and use it in a content item. For the basics of using the Content Management API, first see Importing to Kentico Cloud.

Premium feature 

The Content Management API requires a Professional plan or higher. See Pricing for more details.

Table of contents

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

    1. Upload a file to Kentico Cloud.
    2. Create a new asset using a reference to the file.
    3. 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 Cloud, send a POST request to {~https://manage.kenticocloud.com/projects/<YOUR_PROJECT_ID>/files/<YOUR_FILE_NAME>~}.

    • Use your Content Management API Key in the authorization header of the request.
    • Make sure to use the correct {~Content-type~} header value with MIME type matching your file.
    • Include the {~Content-length~} header and specify the length of the file in bytes.
    • C#
    using KenticoCloud.ContentManagement; ContentManagementOptions options = new ContentManagementOptions { ApiKey = "Bearer <YOUR_API_KEY>", ProjectId = "14372844-0a5d-434a-8423-605b8a631623" }; ContentManagementClient client = new ContentManagementClient(options); string filePath = Path.Combine(AppContext.BaseDirectory, @"<YOUR_PATH>\brno-cafe-1080px.jpg"); string contentType = "image/jpg"; // Binary file reference to be used when adding a new asset FileReference fileResult = await client.UploadFileAsync(new FileContentSource(filePath, contentType));
    using KenticoCloud.ContentManagement; ContentManagementOptions options = new ContentManagementOptions { ApiKey = "Bearer <YOUR_API_KEY>", ProjectId = "14372844-0a5d-434a-8423-605b8a631623" }; ContentManagementClient client = new ContentManagementClient(options); string filePath = Path.Combine(AppContext.BaseDirectory, @"<YOUR_PATH>\brno-cafe-1080px.jpg"); string contentType = "image/jpg"; // Binary file reference to be used when adding a new asset FileReference fileResult = await client.UploadFileAsync(new FileContentSource(filePath, contentType));
    • cURL
    curl --request POST \ --url https://manage.kenticocloud.com/v1/projects/14372844-0a5d-434a-8423-605b8a631623/files/brno-cafe-1080px.jpg \ --data-binary "@brno-cafe-1080px.jpg" \ --header "Authorization: Bearer <YOUR_API_KEY>" \ --header "Content-type: image/jpeg" \ --header "Content-length: 125770"
    curl --request POST \ --url https://manage.kenticocloud.com/v1/projects/14372844-0a5d-434a-8423-605b8a631623/files/brno-cafe-1080px.jpg \ --data-binary "@brno-cafe-1080px.jpg" \ --header "Authorization: Bearer <YOUR_API_KEY>" \ --header "Content-type: image/jpeg" \ --header "Content-length: 125770"

    See our API reference for more details on Uploading binary files.

    The response will include an ID that serves as a reference (or a pointer) to your file. You will use it to create the actual asset.

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

    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 {~https://manage.kenticocloud.com/projects/<YOUR_PROJECT_ID>/assets/external-id/<ASSET_EXTERNAL_ID>~}.

    Best practice: Referencing by external ID

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

    See Referencing by external ID for more details.

    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.
    • {~title~} – you can specify a title for the asset (displayed in Kentico Cloud UI).
    • {~descriptions~} – you can specify an asset description for each language in your project.
      • {~language~} – can be specified by its {~codename~} or internal {~id~}.
      • {~description~} – string with a description of the asset.
    • C#
    AssetDescription englishDescription = new AssetDescription { Description = "Cafe in Brno", Language = LanguageIdentifier.ByCodename("en-US") }; AssetDescription spanishDescription = new AssetDescription { Description = "Café en Brno", Language = LanguageIdentifier.ByCodename("es-ES") }; IEnumerable<AssetDescription> descriptions = new [] { englishDescription, spanishDescription }; string title = "Brno Cafe"; // Defines the asset to upsert AssetUpsertModel asset = new AssetUpsertModel { // Note: For the definiiton of fileResult, see "Uploading binary files" FileReference = fileResult, Descriptions = descriptions, Title = title }; string assetExternalId = "Ext-Asset-Xyz"; // Upserts an asset by external ID AssetModel response = await client.UpsertAssetByExternalIdAsync(externalId, asset);
    AssetDescription englishDescription = new AssetDescription { Description = "Cafe in Brno", Language = LanguageIdentifier.ByCodename("en-US") }; AssetDescription spanishDescription = new AssetDescription { Description = "Café en Brno", Language = LanguageIdentifier.ByCodename("es-ES") }; IEnumerable<AssetDescription> descriptions = new [] { englishDescription, spanishDescription }; string title = "Brno Cafe"; // Defines the asset to upsert AssetUpsertModel asset = new AssetUpsertModel { // Note: For the definiiton of fileResult, see "Uploading binary files" FileReference = fileResult, Descriptions = descriptions, Title = title }; string assetExternalId = "Ext-Asset-Xyz"; // Upserts an asset by external ID AssetModel response = await client.UpsertAssetByExternalIdAsync(externalId, asset);
    • cURL
    curl --request PUT \ --url https://manage.kenticocloud.com/v1/projects/14372844-0a5d-434a-8423-605b8a631623/assets/external-id/Ext-Asset-Xyz \ --header "Authorization: Bearer <YOUR_API_KEY>" \ --header "Content-type: application/json" \ --data " { "file_reference": { "id": "8660e19c-7bbd-48a3-bb51-721934c7756c", "type": "internal" }, "title": "Brno Cafe", "descriptions": [ { "language": { "codename": "en-US" }, "description": "Cafe in Brno" }, { "language": { "codename": "es-ES" }, "description": "Café en Brno" } ] }"
    curl --request PUT \ --url https://manage.kenticocloud.com/v1/projects/14372844-0a5d-434a-8423-605b8a631623/assets/external-id/Ext-Asset-Xyz \ --header "Authorization: Bearer <YOUR_API_KEY>" \ --header "Content-type: application/json" \ --data " { "file_reference": { "id": "8660e19c-7bbd-48a3-bb51-721934c7756c", "type": "internal" }, "title": "Brno Cafe", "descriptions": [ { "language": { "codename": "en-US" }, "description": "Cafe in Brno" }, { "language": { "codename": "es-ES" }, "description": "Café en Brno" } ] }"

    See our API reference for more details on Upserting assets by external id.

    The response will include a complete asset object:

    • JSON
    { "id": "8d0baeb7-1165-5f13-b72e-b23fc39fc549", "file_name": "brno-cafe-1080px.jpg", "title": "Brno Cafe", "size": 481939, "image_width": 800, "image_height": 533, "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": "Ext-Asset-Xyz", "last_modified": "2017-12-29T09:44:39.0111761Z" }
    { "id": "8d0baeb7-1165-5f13-b72e-b23fc39fc549", "file_name": "brno-cafe-1080px.jpg", "title": "Brno Cafe", "size": 481939, "image_width": 800, "image_height": 533, "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": "Ext-Asset-Xyz", "last_modified": "2017-12-29T09:44:39.0111761Z" }

    To verify the creation of the asset, you can view it inside Kentico Cloud:

    From the app menu, open Content & Assets -> Assets to view and edit your files.

    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 limitations set by 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-59713~}) and the language of the variant (for example, {~/variants/codename/en-US~}).

    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.

    • C#
    // Upsert a language variant which references the asset using external ID CafeModel stronglyTypedElements = new CafeModel { Picture = AssetIdentifier.ByExternalId("Ext-Asset-Xyz"), }; ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ByExternalId("ext-cafe-brno-59713"); LanguageIdentifier languageIdentifier = LanguageIdentifier.ByCodename("en-US"); ContentItemVariantIdentifier identifier = new ContentItemVariantIdentifier(itemIdentifier, languageIdentifier); ContentItemVariantModel<CafeModel> variantResponse = await client.UpsertContentItemVariantAsync<CafeModel>(identifier, stronglyTypedElements);
    // Upsert a language variant which references the asset using external ID CafeModel stronglyTypedElements = new CafeModel { Picture = AssetIdentifier.ByExternalId("Ext-Asset-Xyz"), }; ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ByExternalId("ext-cafe-brno-59713"); LanguageIdentifier languageIdentifier = LanguageIdentifier.ByCodename("en-US"); ContentItemVariantIdentifier identifier = new ContentItemVariantIdentifier(itemIdentifier, languageIdentifier); ContentItemVariantModel<CafeModel> variantResponse = await client.UpsertContentItemVariantAsync<CafeModel>(identifier, stronglyTypedElements);
    • cURL
    curl --request PUT \ --url https://manage.kenticocloud.com/v1/projects/14372844-0a5d-434a-8423-605b8a631623/items/external-id/ext-cafe-brno-59713/variants/codename/en-US \ --header "authorization: Bearer <YOUR_API_KEY>" \ --header "content-type: application/json" \ --data " { "elements":{ "photo":[ { "external_id":"Ext-Asset-Xyz" } ] } }"
    curl --request PUT \ --url https://manage.kenticocloud.com/v1/projects/14372844-0a5d-434a-8423-605b8a631623/items/external-id/ext-cafe-brno-59713/variants/codename/en-US \ --header "authorization: Bearer <YOUR_API_KEY>" \ --header "content-type: application/json" \ --data " { "elements":{ "photo":[ { "external_id":"Ext-Asset-Xyz" } ] } }"

    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 Cloud:

    From the app menu, choose Content & Assets -> Brno to view the updated content item.

    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 content type Article (which contains a Rich text element) with external ID {~ext-new-cafes-485~}.

    To add your asset, you can use the same API endpoint as above, only update the {~body_copy~} Rich text element of the {~ext-new-cafes-485~} content item. Use the {~<figure>~} HTML element to add an image using its external ID.

    • C#
    // Upsert a language variant which references the asset using external ID ArticleModel stronglyTypedElements = new ArticleModel { BodyCopy = @"<p>...</p> <figure data-asset-external-id=\"Ext-Asset-Xyz\"></figure>" }; ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ByCodename("new_cafes_joining_our_network_"); LanguageIdentifier languageIdentifier = LanguageIdentifier.ByCodename("en-US"); ContentItemVariantIdentifier identifier = new ContentItemVariantIdentifier(itemIdentifier, languageIdentifier); ContentItemVariantModel<ArticleModel> variantResponse = await client.UpsertContentItemVariantAsync<ArticleModel>(identifier, stronglyTypedElements);
    // Upsert a language variant which references the asset using external ID ArticleModel stronglyTypedElements = new ArticleModel { BodyCopy = @"<p>...</p> <figure data-asset-external-id=\"Ext-Asset-Xyz\"></figure>" }; ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ByCodename("new_cafes_joining_our_network_"); LanguageIdentifier languageIdentifier = LanguageIdentifier.ByCodename("en-US"); ContentItemVariantIdentifier identifier = new ContentItemVariantIdentifier(itemIdentifier, languageIdentifier); ContentItemVariantModel<ArticleModel> variantResponse = await client.UpsertContentItemVariantAsync<ArticleModel>(identifier, stronglyTypedElements);
    • cURL
    curl --request PUT \ --url manage.kenticocloud.com/v1/projects/14372844-0a5d-434a-8423-605b8a631623/items/external-id/ext-new-cafes-485/variants/codename/en-US \ --header "authorization: Bearer <YOUR_API_KEY>" \ --header "content-type: application/json" \ --data " { "elements":{ "body_copy":"<p>...</p> <figure data-asset-external-id=\"Ext-Asset-Xyz\"></figure>" } }"
    curl --request PUT \ --url manage.kenticocloud.com/v1/projects/14372844-0a5d-434a-8423-605b8a631623/items/external-id/ext-new-cafes-485/variants/codename/en-US \ --header "authorization: Bearer <YOUR_API_KEY>" \ --header "content-type: application/json" \ --data " { "elements":{ "body_copy":"<p>...</p> <figure data-asset-external-id=\"Ext-Asset-Xyz\"></figure>" } }"

    See the Rich text model in our API Reference for more examples of links inside Rich text elements.

    What's next?

    In this tutorial, you uploaded a file to Kentico Cloud, created an asset from it, and used the asset in a content item.