Importing assets

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

Premium feature 

The Content Management API requires a Professional plan or higher.

Note: The CM API currently has two versions. While CM API v2 is in BETA, it is not expected that its behavior will substantially change just that more features will be added (all changes will be noted in the API changelog). 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 CM API is a 3-step process in which you:

    1. Upload a file to Kentico Kontent.
    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 Kontent, send a POST request to the <YOUR_PROJECT_ID>/files/<YOUR_FILE_NAME> endpoint with your project ID and your file name filled in.

    • Use your CM API Key in the authorization header of the request (in place of <YOUR_API_KEY> in the examples).
    • Make sure to use the correct Content-type header value with the MIME type matching your file.
    • Include the Content-length header and specify the length of the file in bytes.
    • JavaScript
    // Using ES6 syntax // Note that this approach works when using Node.js. See a worked example using the browser: https://github.com/Enngage/kentico-cloud-content-management-js-demo import { ManagementClient } from "@kentico/kontent-management"; import { readFileSync } from "fs" const client = new ManagementClient({ projectId: "<YOUR_PROJECT_ID>", apiKey: "<YOUR_API_KEY>" }); const data = readFileSync("brno-cafe-1080px.jpg"); client.uploadBinaryFile() .withData({ binaryData: data, contentLength: data.byteLength, contentType: "image/jpg", filename: "brno-cafe-1080px.jpg" }) .toObservable() .subscribe((response) => { console.log(response); }, (error) => { console.log(error); });
    // Using ES6 syntax // Note that this approach works when using Node.js. See a worked example using the browser: https://github.com/Enngage/kentico-cloud-content-management-js-demo import { ManagementClient } from "@kentico/kontent-management"; import { readFileSync } from "fs" const client = new ManagementClient({ projectId: "<YOUR_PROJECT_ID>", apiKey: "<YOUR_API_KEY>" }); const data = readFileSync("brno-cafe-1080px.jpg"); client.uploadBinaryFile() .withData({ binaryData: data, contentLength: data.byteLength, contentType: "image/jpg", filename: "brno-cafe-1080px.jpg" }) .toObservable() .subscribe((response) => { console.log(response); }, (error) => { console.log(error); });
    • C#
    // Using CM API v1 using KenticoCloud.ContentManagement; ContentManagementOptions options = new ContentManagementOptions { ApiKey = "Bearer <YOUR_API_KEY>", ProjectId = "<YOUR_PROJECT_ID>" }; 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 CM API v1 using KenticoCloud.ContentManagement; ContentManagementOptions options = new ContentManagementOptions { ApiKey = "Bearer <YOUR_API_KEY>", ProjectId = "<YOUR_PROJECT_ID>" }; 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.kontent.ai/v2/projects/<YOUR_PROJECT_ID>/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.kontent.ai/v2/projects/<YOUR_PROJECT_ID>/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 the <YOUR_PROJECT_ID>/assets/external-id/<ASSET_EXTERNAL_ID> endpoint with your project ID and an external ID for your 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.

    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.
    • (Optional) title – specify a title for the asset (displayed in the Kentico Kontent UI).
    • descriptions – 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.
    • JavaScript
    // Using ES6 syntax import { ManagementClient } from "@kentico/kontent-management"; const client = new ManagementClient({ projectId: "<YOUR_PROJECT_ID>", apiKey: "<YOUR_API_KEY>" }); client.upsertAsset() .withData( { fileReference: { id: "8660e19c-7bbd-48a3-bb51-721934c7756c", type: "internal" }, title: "Brno Cafe", assetExternalId: "brno-cafe-image", descriptions: [ { language: { codename: "en-US" }, description: "Cafe in Brno" }, { language: { codename: "es-ES" }, description: "Café en Brno" } ] } ) .toObservable() .subscribe((response) => { console.log(response); }, (error) => { console.log(error); });
    // Using ES6 syntax import { ManagementClient } from "@kentico/kontent-management"; const client = new ManagementClient({ projectId: "<YOUR_PROJECT_ID>", apiKey: "<YOUR_API_KEY>" }); client.upsertAsset() .withData( { fileReference: { id: "8660e19c-7bbd-48a3-bb51-721934c7756c", type: "internal" }, title: "Brno Cafe", assetExternalId: "brno-cafe-image", descriptions: [ { language: { codename: "en-US" }, description: "Cafe in Brno" }, { language: { codename: "es-ES" }, description: "Café en Brno" } ] } ) .toObservable() .subscribe((response) => { console.log(response); }, (error) => { console.log(error); });
    • C#
    // Using CM API v1 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 = "brno-cafe-image"; // Upserts an asset by external ID AssetModel response = await client.UpsertAssetByExternalIdAsync(externalId, asset);
    // Using CM API v1 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 = "brno-cafe-image"; // Upserts an asset by external ID AssetModel response = await client.UpsertAssetByExternalIdAsync(externalId, asset);
    • cURL
    curl --request PUT \ --url https://manage.kontent.ai/v2/projects/<YOUR_PROJECT_ID>/assets/external-id/brno-cafe-image \ --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.kontent.ai/v2/projects/<YOUR_PROJECT_ID>/assets/external-id/brno-cafe-image \ --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": "brno-cafe-image", "last_modified": "2019-10-10T09: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": "brno-cafe-image", "last_modified": "2019-10-10T09:44:39.0111761Z" }

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

    From the app menu, choose 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 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.

    • JavaScript
    // Using ES6 syntax import { ManagementClient } from "@kentico/kontent-management"; const client = new ManagementClient({ projectId: "<YOUR_PROJECT_ID>", apiKey: "<YOUR_API_KEY>" }); client.upsertLanguageVariant() .byItemExternalId("ext-cafe-brno") .byLanguageCodename("en-US") .withElements([ { element: { codename: "photo" }, value: [ { external_id: "brno-cafe-image" } ] } ]) .toObservable() .subscribe((response) => { console.log(response); }, (error) => { console.log(error); });
    // Using ES6 syntax import { ManagementClient } from "@kentico/kontent-management"; const client = new ManagementClient({ projectId: "<YOUR_PROJECT_ID>", apiKey: "<YOUR_API_KEY>" }); client.upsertLanguageVariant() .byItemExternalId("ext-cafe-brno") .byLanguageCodename("en-US") .withElements([ { element: { codename: "photo" }, value: [ { external_id: "brno-cafe-image" } ] } ]) .toObservable() .subscribe((response) => { console.log(response); }, (error) => { console.log(error); });
    • C#
    // Using CM API v1 // Upsert a language variant which references the asset using external ID CafeModel stronglyTypedElements = new CafeModel { Picture = AssetIdentifier.ByExternalId("brno-cafe-image"), }; ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ByExternalId("ext-cafe-brno"); LanguageIdentifier languageIdentifier = LanguageIdentifier.ByCodename("en-US"); ContentItemVariantIdentifier identifier = new ContentItemVariantIdentifier(itemIdentifier, languageIdentifier); ContentItemVariantModel<CafeModel> variantResponse = await client.UpsertContentItemVariantAsync<CafeModel>(identifier, stronglyTypedElements);
    // Using CM API v1 // Upsert a language variant which references the asset using external ID CafeModel stronglyTypedElements = new CafeModel { Picture = AssetIdentifier.ByExternalId("brno-cafe-image"), }; ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ByExternalId("ext-cafe-brno"); 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.kontent.ai/v2/projects/<YOUR_PROJECT_ID>/items/external-id/ext-cafe-brno/variants/codename/en-US \ --header "authorization: Bearer <YOUR_API_KEY>" \ --header "content-type: application/json" \ --data " { "elements":{ "photo":[ { "external_id":"brno-cafe-image" } ] } }"
    curl --request PUT \ --url https://manage.kontent.ai/v2/projects/<YOUR_PROJECT_ID>/items/external-id/ext-cafe-brno/variants/codename/en-US \ --header "authorization: Bearer <YOUR_API_KEY>" \ --header "content-type: application/json" \ --data " { "elements":{ "photo":[ { "external_id":"brno-cafe-image" } ] } }"

    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:

    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 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.

    • JavaScript
    // Using ES6 syntax import { ManagementClient } from "@kentico/kontent-management"; const client = new ManagementClient({ projectId: "<YOUR_PROJECT_ID>", apiKey: "<YOUR_API_KEY>" }); client.upsertLanguageVariant() .byItemExternalId("new-cafes") .byLanguageCodename("en-US") .withElements([ { element: { codename: "body_copy" }, value: "<p>...</p> <figure data-asset-external-id=\"brno-cafe-image\"></figure>" } ]) .toObservable() .subscribe((response) => { console.log(response); }, (error) => { console.log(error); });
    // Using ES6 syntax import { ManagementClient } from "@kentico/kontent-management"; const client = new ManagementClient({ projectId: "<YOUR_PROJECT_ID>", apiKey: "<YOUR_API_KEY>" }); client.upsertLanguageVariant() .byItemExternalId("new-cafes") .byLanguageCodename("en-US") .withElements([ { element: { codename: "body_copy" }, value: "<p>...</p> <figure data-asset-external-id=\"brno-cafe-image\"></figure>" } ]) .toObservable() .subscribe((response) => { console.log(response); }, (error) => { console.log(error); });
    • C#
    // Using CM API v1 ArticleModel stronglyTypedElements = new ArticleModel { BodyCopy = @"<p>...</p> <figure data-asset-external-id=\"brno-cafe-image\"></figure>" }; ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ByExternalId("new-cafes"); LanguageIdentifier languageIdentifier = LanguageIdentifier.ByCodename("en-US"); ContentItemVariantIdentifier identifier = new ContentItemVariantIdentifier(itemIdentifier, languageIdentifier); ContentItemVariantModel<ArticleModel> variantResponse = await client.UpsertContentItemVariantAsync<ArticleModel>(identifier, stronglyTypedElements);
    // Using CM API v1 ArticleModel stronglyTypedElements = new ArticleModel { BodyCopy = @"<p>...</p> <figure data-asset-external-id=\"brno-cafe-image\"></figure>" }; ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ByExternalId("new-cafes"); 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.kontent.ai/v2/projects/<YOUR_PROJECT_ID>/items/external-id/new-cafes/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=\"brno-cafe-image\"></figure>" } }"
    curl --request PUT \ --url manage.kontent.ai/v2/projects/<YOUR_PROJECT_ID>/items/external-id/new-cafes/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=\"brno-cafe-image\"></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 Kontent, created an asset from it, and used the asset in a content item.

    • For more information on working with assets using the CM API, see our API Reference.
    • Have a look at our Content Management SDKs for .Net and JavaScript.