Import assets
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.
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
.
URL-encode reserved charactersIf the name of your file contains reserved characters, you need to URL encode the file name first. For instance, use
my%20file%232.png
instead of my file#2.png
. The file will then show as my file#2.png
in the Kontent.ai UI.- Set the
Content-type
header to the MIME type matching your file. For example, for a jpg image set the header toimage/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 to12288
.
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.
// Using ES6 syntax
// This approach works when using Node.js.
import { ManagementClient } from '@kontent-ai/management-sdk';
import { readFileSync } from 'fs'
const client = new ManagementClient({
environmentId: '<YOUR_ENVIRONMENT_ID>',
apiKey: '<YOUR_API_KEY>'
});
const data = readFileSync('./<YOUR_PATH>/brno-cafe-1080px.jpg');
const response = await client.uploadBinaryFile()
.withData({
binaryData: data,
contentLength: data.byteLength,
contentType: 'image/jpeg',
filename: 'brno-cafe-1080px.jpg'
})
.toPromise();
file_reference
object.
{
"id": "8660e19c-7bbd-48a3-bb51-721934c7756c",
"type": "internal"
}
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.
Best practice: Referencing by external IDMake 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.
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 itscodename
or internalid
.description
– string with a description of the asset.
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';
const client = new ManagementClient({
environmentId: '<YOUR_ENVIRONMENT_ID>',
apiKey: '<YOUR_API_KEY>'
});
// Uses the file reference object obtained in step 1
const response = await client.upsertAsset()
.byAssetExternalId('brno-cafe-image')
.withData(
{
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'
}
]
}
)
.toPromise();
{
"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"
}
3. Use assets in content items
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!