Assets

Assets in Kontent.ai consist of a reference to a binary file and metadata describing the file. Each binary file can be referenced only by a single asset.Binary files that are not used by any assets will not be visible in the Kontent.ai UI.

Adding assets is a 2-step process

Upload a binary file to get a file reference to the file.
Use the file reference to create a new asset referencing the uploaded file.

Asset object

A single asset object.

descriptions[]

array · unique items

The asset's descriptions for each active language.

Show child attributes

elements[]

array · unique items

An array of asset taxonomy elements as defined in the asset type.

The asset type can be managed only in the UI.

This feature isn’t available for some legacy plan subscriptions. Contact us to find out your options.

Show child attributes

external_id

string

The asset's external ID. The external ID can be specified when adding or upserting assets. Use this parameter as a unique identifier for your assets. If not specified, the external_id property is not present.

file_name

string · read-only

The file's name.

Determined by the file referenced in the file_reference property.

file_reference

required · object

Points to a specific binary file that was uploaded to an environment.

Show child attributes

folder

object

A reference to the folder containing the asset. You can specify a folder by its internal ID, codename, or external ID. Not present if the asset is not in a folder.To return an asset to the top level outside any folders, use "id" : "00000000-0000-0000-0000-000000000000".

Show child attributes

collection

object

A reference to the collection that the asset is assigned to. You can specify a collection by its internal ID, codename, or external ID.

For projects created after the asset collections product release, the asset’s collection is set to the default collection unless specified when creating the asset. The collection property can be modified but cannot be set to null.

Show child attributes

id

string · read-only · uuid

The asset's internal ID.

codename

string

The asset's codename. Unless specified when adding or upserting assets, initially generated from the asset's title. If title is empty, the file_name is used.

image_height

number · nullable · read-only · int32

The image's height in pixels. Is null if the file is not an image.

Determined by the file referenced in the file_reference property.

image_width

number · nullable · read-only · int32

The image's width in pixels. Is null if the file is not an image.

Determined by the file referenced in the file_reference property.

last_modified

string · read-only · date-time

ISO-8601

formatted date and time of the last change to the asset.

size

number · read-only · int32

The file's size in bytes.

Determined by the file referenced in the file_reference property.

title

string · nullable · max. 200 chars

The asset's display name. The title can be specified when adding or upserting assets. Use title to better identify and filter your assets in the UI. If not specified, the title property is null.

type

string · read-only

The file's MIME type.

Determined by the file referenced in the file_reference property.

url

string · read-only

The asset's URL.

JSON

{
  "descriptions": [
    {
      "language": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "description": "The asset's alt text for the default language."
    }
  ],
  "elements": [
    {
      "element": {
        "id": "c7c3b834-2222-5677-89c4-b46f04489109"
      },
      "value": [
        {
          "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
        },
        {
          "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
        }
      ]
    }
  ],
  "external_id": "custom-asset-identifier",
  "file_name": "file_name.png",
  "file_reference": {
    "id": "806ec84e-7c71-4856-9519-ee3dd3558583",
    "type": "internal"
  },
  "folder": {
    "id": "8fe4ff47-0ca8-449d-bc63-c280efee44ea"
  },
  "collection": {
    "reference": {
      "codename": "first_collection"
    }
  },
  "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
  "codename": "my_asset",
  "image_height": 548,
  "image_width": 1280,
  "last_modified": "2019-09-12T08:29:36.1645977Z",
  "size": 148636,
  "title": "Makes the asset easier to find when you need it",
  "type": "image/png",
  "url": "https://assets-us-01.kc-usercontent.com/8d20758c-d74c-4f59-ae04-ee928c0816b7/806ec84e-7c71-4856-9519-ee3dd3558583/file_name.png"
}

Upload a binary file

Add a new file. The file won't be visible in the UI until you add an asset referencing the uploaded file.

Adding assets is a 2-step process

Upload a binary file to get a file reference to the file.
Use the file reference to create a new asset referencing the uploaded file.

Maximum size limit for binary files is 100 MB.

POST

https://manage.kontent.ai/v2/projects/{environment_id}/files/{file_name}

Request

Path parameters

environment_id

required · string

Identifies your environment.

file_name

required · string · 1-500 chars

Specifies the name of the uploaded binary file.If the file name contains reserved characters

, they must be URL-encoded

. For example, the file name my file#2.png would be URL-encoded to my%20file%232.png. For image files, include a file extension such as .png to ensure the files can be optimized using the Image transformation API.

Header parameters

Content-type

required · string

Specifies the MIME type

of the binary data.Make sure the Content-type value matches the file extension specified in file_name.

Content-length

required · number · int32

Specifies the size of the binary file in bytes.

Body schema

Application/octet-stream

The binary data of the file.

string · max. 104857600 chars · binary

Request samples

TypeScript
C#
cURL

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Note that this approach works when using Node.js. See a worked example using the browser
import { ManagementClient } from '@kontent-ai/management-sdk';
import { readFileSync } from 'fs';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const data = readFileSync('which-brewing-fits-you-1080px.jpg');

const response = await client
  .uploadBinaryFile()
  .withData({
    binaryData: data,
    contentLength: data.byteLength,
    contentType: 'image/jpeg',
    filename: 'which-brewing-fits-you-1080px.jpg',
  })
  .toPromise();

Response

Status (200)

A file reference to the uploaded binary file.

id

required · string · uuid

The binary file's internal ID.

type

required · string

The type of the file reference.

Example responses

200
400

{
  "id": "806ec84e-7c71-4856-9519-ee3dd3558583",
  "type": "internal"
}

Add an asset

Use a file reference to link an existing binary file to a new asset. You can also create assets by upserting (PUT /assets/external-id/<external_id>).Each binary file can be referenced only by a single asset.

When used in an asset, file names go through a sanitization step where the following characters: / \ : * ? " < > | % # & { } $ ! ' ` ~ ^ + = [ ] ; @ are replaced with underscores _. The only exceptions are comma , and brackets (), which are preserved. For example, the file name my file#2.png then displays as my file_2.png in the Kontent.ai UI.

POST

https://manage.kontent.ai/v2/projects/{environment_id}/assets

Request

Path parameters

environment_id

required · string

Identifies your environment.

Body schema

Application/json

The asset to create.

descriptions[]

array · unique items

The asset's descriptions for each active language.

Show child attributes

elements[]

array · unique items

An array of asset taxonomy elements as defined in the asset type.

The asset type can be managed only in the UI.

This feature isn’t available for some legacy plan subscriptions. Contact us to find out your options.

Show child attributes

external_id

string

file_reference

required · object

Points to a specific binary file that was uploaded to an environment.

Show child attributes

folder

object

Show child attributes

collection

object

A reference to the collection that the asset is assigned to. You can specify a collection by its internal ID, codename, or external ID.

Show child attributes

codename

string

The asset's codename. Unless specified when adding or upserting assets, initially generated from the asset's title. If title is empty, the file_name is used.

title

string · nullable · max. 200 chars

Request samples

Payload
TypeScript
C#
cURL

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .addAsset()
  .withData((builder) => {
    return {
      // To create a file reference, check the 'Upload a binary file' endpoint
      file_reference: {
        id: 'fcbb12e6-66a3-4672-85d9-d502d16b8d9c',
        type: 'internal',
      },
      title: 'Coffee Brewing Techniques',
      external_id: 'which-brewing-fits-you',
      descriptions: [
        {
          language: {
            codename: 'en-US',
          },
          description: 'Coffee Brewing Techniques',
        },
        {
          language: {
            codename: 'es-ES',
          },
          description: 'Técnicas para hacer café',
        },
      ],
      elements: [
        builder.taxonomyElement({
          element: {
            codename: 'taxonomy-categories',
          },
          value: [
            {
              codename: 'coffee',
            },
            {
              codename: 'brewing',
            },
          ],
        }),
      ],
    };
  })
  .toPromise();

Response

Status (201)

The created asset.

descriptions[]

array · unique items

The asset's descriptions for each active language.

Show child attributes

elements[]

array · unique items

An array of asset taxonomy elements as defined in the asset type.

The asset type can be managed only in the UI.

This feature isn’t available for some legacy plan subscriptions. Contact us to find out your options.

Show child attributes

external_id

string

file_name

string · read-only

The file's name.

Determined by the file referenced in the file_reference property.

file_reference

required · object

Points to a specific binary file that was uploaded to an environment.

Show child attributes

folder

object

Show child attributes

collection

object

A reference to the collection that the asset is assigned to. You can specify a collection by its internal ID, codename, or external ID.

Show child attributes

id

string · read-only · uuid

The asset's internal ID.

codename

string

The asset's codename. Unless specified when adding or upserting assets, initially generated from the asset's title. If title is empty, the file_name is used.

image_height

number · nullable · read-only · int32

The image's height in pixels. Is null if the file is not an image.

Determined by the file referenced in the file_reference property.

image_width

number · nullable · read-only · int32

The image's width in pixels. Is null if the file is not an image.

Determined by the file referenced in the file_reference property.

last_modified

string · read-only · date-time

ISO-8601

formatted date and time of the last change to the asset.

size

number · read-only · int32

The file's size in bytes.

Determined by the file referenced in the file_reference property.

title

string · nullable · max. 200 chars

type

string · read-only

The file's MIME type.

Determined by the file referenced in the file_reference property.

url

string · read-only

The asset's URL.

Example responses

201
400

{
  "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
  "file_name": "file_name.jpeg",
  "title": "Description of what the file contains",
  "size": 148636,
  "type": "image/jpeg",
  "url": "https://assets-us-01.kc-usercontent.com/8d20758c-d74c-4f59-ae04-ee928c0816b7/adf26cd2-1acb-403f-9d1e-6d04e46c39f1/file_name.png",
  "image_width": 1280,
  "image_height": 548,
  "file_reference": {
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "type": "internal"
  },
  "folder": {
    "id": "8fe4ff47-0ca8-449d-bc63-c280efee44ea"
  },
  "descriptions": [
    {
      "language": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "description": "The asset's alt text in the default language describing what the file or image shows."
    }
  ],
  "elements": [
    {
      "element": {
        "id": "c7c3b834-2222-5677-89c4-b46f04489109"
      },
      "value": [
        {
          "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
        },
        {
          "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
        }
      ]
    }
  ],
  "external_id": "custom-asset-identifier",
  "last_modified": "2017-09-12T08:29:36.1645977Z"
}

Retrieve an asset

Retrieve information about a single asset.

GET

https://manage.kontent.ai/v2/projects/{environment_id}/assets/{asset_identifier}

Request

Path parameters

environment_id

required · string

Identifies your environment.

asset_identifier

required · string

Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c), codename (e.g., codename/my_asset, or external ID (e.g., external-id/my-own-asset-identifier-42).

Request samples

TypeScript
C#
cURL

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .viewAsset()
  .byAssetId('0270ea18-4842-4d09-9570-17b41bb37e2d')
  // .byAssetExternalId('which-brewing-fits-you')
  .toPromise();

Response

Status (200)

A single asset object with metadata about the asset and the referenced binary file.

descriptions[]

array · unique items

The asset's descriptions for each active language.

Show child attributes

elements[]

array · unique items

An array of asset taxonomy elements as defined in the asset type.

The asset type can be managed only in the UI.

This feature isn’t available for some legacy plan subscriptions. Contact us to find out your options.

Show child attributes

external_id

string

file_name

string · read-only

The file's name.

Determined by the file referenced in the file_reference property.

file_reference

required · object

Points to a specific binary file that was uploaded to an environment.

Show child attributes

folder

object

Show child attributes

collection

object

A reference to the collection that the asset is assigned to. You can specify a collection by its internal ID, codename, or external ID.

Show child attributes

id

string · read-only · uuid

The asset's internal ID.

codename

string

The asset's codename. Unless specified when adding or upserting assets, initially generated from the asset's title. If title is empty, the file_name is used.

image_height

number · nullable · read-only · int32

The image's height in pixels. Is null if the file is not an image.

Determined by the file referenced in the file_reference property.

image_width

number · nullable · read-only · int32

The image's width in pixels. Is null if the file is not an image.

Determined by the file referenced in the file_reference property.

last_modified

string · read-only · date-time

ISO-8601

formatted date and time of the last change to the asset.

size

number · read-only · int32

The file's size in bytes.

Determined by the file referenced in the file_reference property.

title

string · nullable · max. 200 chars

type

string · read-only

The file's MIME type.

Determined by the file referenced in the file_reference property.

url

string · read-only

The asset's URL.

Example responses

200
404

{
  "descriptions": [
    {
      "language": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "description": "The asset's alt text for the default language."
    }
  ],
  "elements": [
    {
      "element": {
        "id": "c7c3b834-2222-5677-89c4-b46f04489109"
      },
      "value": [
        {
          "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
        },
        {
          "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
        }
      ]
    }
  ],
  "external_id": "custom-asset-identifier",
  "file_name": "file_name.png",
  "file_reference": {
    "id": "806ec84e-7c71-4856-9519-ee3dd3558583",
    "type": "internal"
  },
  "folder": {
    "id": "8fe4ff47-0ca8-449d-bc63-c280efee44ea"
  },
  "collection": {
    "reference": {
      "codename": "first_collection"
    }
  },
  "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
  "codename": "my_asset",
  "image_height": 548,
  "image_width": 1280,
  "last_modified": "2019-09-12T08:29:36.1645977Z",
  "size": 148636,
  "title": "Makes the asset easier to find when you need it",
  "type": "image/png",
  "url": "https://assets-us-01.kc-usercontent.com/8d20758c-d74c-4f59-ae04-ee928c0816b7/806ec84e-7c71-4856-9519-ee3dd3558583/file_name.png"
}

List assets

Retrieve a dynamically paginated list of assets.

GET

https://manage.kontent.ai/v2/projects/{environment_id}/assets

Request

Path parameters

environment_id

required · string

Identifies your environment.

Header parameters

x-continuation

string

Determines the page of results to retrieve.To get the next page of results, check the pagination object in the API response and set the x-continuation header parameter to the value of the continuation_token property.

Request samples

TypeScript
C#
cURL

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

// Gets the first page of results
const response = await client.listAssets().toPromise();

// Gets all pages of results
// const response = await client.listAssets()
//   .toAllPromise();

Response

Status (200)

A dynamically paginated list of assets.

assets[]

required · array

List of assets.

Show child attributes

pagination

required · object

Information about the next page of results.

Show child attributes

Example responses

200
400

{
  "assets": {
    "descriptions": [
      {
        "language": {
          "id": "00000000-0000-0000-0000-000000000000"
        },
        "description": "The asset's alt text for the default language."
      }
    ],
    "elements": [
      {
        "element": {
          "id": "c7c3b834-2222-5677-89c4-b46f04489109"
        },
        "value": [
          {
            "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
          },
          {
            "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
          }
        ]
      }
    ],
    "external_id": "custom-asset-identifier",
    "file_name": "file_name.png",
    "file_reference": {
      "id": "806ec84e-7c71-4856-9519-ee3dd3558583",
      "type": "internal"
    },
    "folder": {
      "id": "8fe4ff47-0ca8-449d-bc63-c280efee44ea"
    },
    "collection": {
      "reference": {
        "codename": "first_collection"
      }
    },
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "codename": "my_asset",
    "image_height": 548,
    "image_width": 1280,
    "last_modified": "2019-09-12T08:29:36.1645977Z",
    "size": 148636,
    "title": "Makes the asset easier to find when you need it",
    "type": "image/png",
    "url": "https://assets-us-01.kc-usercontent.com/8d20758c-d74c-4f59-ae04-ee928c0816b7/806ec84e-7c71-4856-9519-ee3dd3558583/file_name.png"
  },
  "pagination": {
    "continuation_token": "W3sidG9rZW4iOiIrUklEOn...",
    "next_page": "https://manage.kontent.ai/v2/your/chosen/list/endpoint"
  }
}

Upsert an asset

Update an existing asset, or add a new asset specified by external ID.

PUT

https://manage.kontent.ai/v2/projects/{environment_id}/assets/{asset_identifier}

Request

Path parameters

environment_id

required · string

Identifies your environment.

asset_identifier

required · string

Identifies an asset by its internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c) or external ID (e.g., external-id/custom-identifier-of-your-asset).

When adding a new asset, use an external ID as the asset's identifier.
When updating an existing asset, identify the asset either by its internal ID or external ID.

New vs existing assetsIf the specified external ID is not used by an existing asset, the API will create a new asset. For existing assets, the API updates only the specified asset's descriptions and title.

Body schema

Application/json

The asset to update or create.

descriptions[]

array

Asset descriptions for each active language.

Show child attributes

elements[]

array · unique items

Asset taxonomy elements as defined in the asset type.

This feature isn’t available for some legacy plan subscriptions. Contact us to find out your options.

Show child attributes

folder

object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

collection

object

An object containing a reference to the collection containing the asset. You can specify a collection by its internal ID, codename, or external ID. If you need to remove the asset from a collection, use a null reference {"reference": null}.

Show child attributes

title

string · 1-200 chars

The title of the new asset. Use this parameter to better identify and filter your assets in the UI.

file_reference

required · object

Points to a specific binary file that was uploaded to an environment.

Show child attributes

codename

string

The asset's codename. Unless specified, initially generated from the asset's title. If title is empty, the file_name is used.

Request samples

TypeScript
C#
cURL

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

// Updates an existing asset
const response = await client
  .updateAsset()
  .byAssetExternalId('which-brewing-fits-you')
  // .byAssetId('fcbb12e6-66a3-4672-85d9-d502d16b8d9c')
  .withData((builder) => {
    return {
      title: 'Coffee Brewing Techniques',
      assetId: 'fcbb12e6-66a3-4672-85d9-d502d16b8d9c',
      descriptions: [
        {
          language: {
            codename: 'en-US',
          },
          description: 'Coffee Brewing Techniques',
        },
        {
          language: {
            codename: 'es-ES',
          },
          description: 'Técnicas para hacer café',
        },
      ],
      elements: [
        builder.taxonomyElement({
          element: {
            codename: 'taxonomy-categories',
          },
          value: [
            {
              codename: 'coffee',
            },
            {
              codename: 'brewing',
            },
          ],
        }),
      ],
    };
  })
  .toPromise();

// Creates a new asset or updates an existing one
const response = await client
  .upsertAsset()
  .byAssetExternalId('which-brewing-fits-you')
  // .byAssetId('fcbb12e6-66a3-4672-85d9-d502d16b8d9c')
  .withData((builder) => {
    return {
      // 'file_reference' is only required when creating a new asset
      // To create a file reference, see the 'Upload a binary file' endpoint
      file_reference: {
        id: 'fcbb12e6-66a3-4672-85d9-d502d16b8d9c',
        type: 'internal',
      },
      title: 'Coffee Brewing Techniques',
      external_id: 'which-brewing-fits-you',
      descriptions: [
        {
          language: {
            codename: 'en-US',
          },
          description: 'Coffee Brewing Techniques',
        },
        {
          language: {
            codename: 'es-ES',
          },
          description: 'Técnicas para hacer café',
        },
      ],
      elements: [
        builder.taxonomyElement({
          element: {
            codename: 'taxonomy-categories',
          },
          value: [
            {
              codename: 'coffee',
            },
            {
              codename: 'brewing',
            },
          ],
        }),
      ],
    };
  })
  .toPromise();

Response

Status (200)

Status (201)

The specified asset was updated.

descriptions[]

array · unique items

The asset's descriptions for each active language.

Show child attributes

elements[]

array · unique items

An array of asset taxonomy elements as defined in the asset type.

The asset type can be managed only in the UI.

This feature isn’t available for some legacy plan subscriptions. Contact us to find out your options.

Show child attributes

external_id

string

file_name

string · read-only

The file's name.

Determined by the file referenced in the file_reference property.

file_reference

required · object

Points to a specific binary file that was uploaded to an environment.

Show child attributes

folder

object

Show child attributes

collection

object

A reference to the collection that the asset is assigned to. You can specify a collection by its internal ID, codename, or external ID.

Show child attributes

id

string · read-only · uuid

The asset's internal ID.

codename

string

The asset's codename. Unless specified when adding or upserting assets, initially generated from the asset's title. If title is empty, the file_name is used.

image_height

number · nullable · read-only · int32

The image's height in pixels. Is null if the file is not an image.

Determined by the file referenced in the file_reference property.

image_width

number · nullable · read-only · int32

The image's width in pixels. Is null if the file is not an image.

Determined by the file referenced in the file_reference property.

last_modified

string · read-only · date-time

ISO-8601

formatted date and time of the last change to the asset.

size

number · read-only · int32

The file's size in bytes.

Determined by the file referenced in the file_reference property.

title

string · nullable · max. 200 chars

type

string · read-only

The file's MIME type.

Determined by the file referenced in the file_reference property.

url

string · read-only

The asset's URL.

Example responses

200
201
400

{
  "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
  "folder": {
    "id": "4033071a-5bc1-48da-8342-d129bb967d1d"
  },
  "file_name": "which-brewing-fits-you-1080px.jpg",
  "title": "Coffee Brewing Techniques",
  "size": 125770,
  "type": "image/jpeg",
  "url": "https://assets-us-01.kc-usercontent.com/975bf280-fd91-488c-994c-2f04416e5ee3/fcbb12e6-66a3-4672-85d9-d502d16b8d9c/which-brewing-fits-you-1080px.jpg",
  "image_width": 1000,
  "image_height": 666,
  "file_reference": {
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "type": "internal"
  },
  "descriptions": [
    {
      "language": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "description": "Coffee Brewing Techniques"
    },
    {
      "language": {
        "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
      },
      "description": "Técnicas para hacer café"
    }
  ],
  "elements": [
    {
      "element": {
        "id": "c7c3b834-2222-5677-89c4-b46f04489109"
      },
      "value": [
        {
          "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
        },
        {
          "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
        }
      ]
    }
  ],
  "last_modified": "2017-09-12T08:29:36.1645977Z"
}

Delete an asset

Delete an unused asset from an environment.

DELETE

https://manage.kontent.ai/v2/projects/{environment_id}/assets/{asset_identifier}

Request

Path parameters

environment_id

required · string

Identifies your environment.

asset_identifier

required · string

Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c), codename (e.g., codename/my_asset, or external ID (e.g., external-id/my-own-asset-identifier-42).

Request samples

TypeScript
C#
cURL

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .deleteAsset()
  .byAssetId('1b458663-d23a-441c-8cc2-c2825fe53b48')
  // .byAssetExternalId('which-brewing-fits-you')
  .toPromise();

Response

Status (204)

The specified asset was deleted.

Empty response

Example responses

404

{
  "request_id": "00000000-0000-0000-6f12-0080000000c7",
  "error_code": 105,
  "message": "The requested asset 'fcbb12e6-66a3-4672-85d9-d502d16b8d9c' was not found."
}

Asset object

A single asset object.

descriptions[]

array · unique items

The asset's descriptions for each active language.

Show child attributes

elements[]

array · unique items

An array of asset taxonomy elements as defined in the asset type.

The asset type can be managed only in the UI.

This feature isn’t available for some legacy plan subscriptions. Contact us to find out your options.

Show child attributes

external_id

string

file_name

string · read-only

The file's name.

Determined by the file referenced in the file_reference property.

file_reference

required · object

Points to a specific binary file that was uploaded to an environment.

Show child attributes

folder

object

Show child attributes

collection

object

A reference to the collection that the asset is assigned to. You can specify a collection by its internal ID, codename, or external ID.

Show child attributes

id

string · read-only · uuid

The asset's internal ID.

codename

string

The asset's codename. Unless specified when adding or upserting assets, initially generated from the asset's title. If title is empty, the file_name is used.

image_height

number · nullable · read-only · int32

The image's height in pixels. Is null if the file is not an image.

Determined by the file referenced in the file_reference property.

image_width

number · nullable · read-only · int32

The image's width in pixels. Is null if the file is not an image.

Determined by the file referenced in the file_reference property.

last_modified

string · read-only · date-time

ISO-8601

formatted date and time of the last change to the asset.

size

number · read-only · int32

The file's size in bytes.

Determined by the file referenced in the file_reference property.

title

string · nullable · max. 200 chars

type

string · read-only

The file's MIME type.

Determined by the file referenced in the file_reference property.

url

string · read-only

The asset's URL.

JSON

{
  "descriptions": [
    {
      "language": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "description": "The asset's alt text for the default language."
    }
  ],
  "elements": [
    {
      "element": {
        "id": "c7c3b834-2222-5677-89c4-b46f04489109"
      },
      "value": [
        {
          "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
        },
        {
          "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
        }
      ]
    }
  ],
  "external_id": "custom-asset-identifier",
  "file_name": "file_name.png",
  "file_reference": {
    "id": "806ec84e-7c71-4856-9519-ee3dd3558583",
    "type": "internal"
  },
  "folder": {
    "id": "8fe4ff47-0ca8-449d-bc63-c280efee44ea"
  },
  "collection": {
    "reference": {
      "codename": "first_collection"
    }
  },
  "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
  "codename": "my_asset",
  "image_height": 548,
  "image_width": 1280,
  "last_modified": "2019-09-12T08:29:36.1645977Z",
  "size": 148636,
  "title": "Makes the asset easier to find when you need it",
  "type": "image/png",
  "url": "https://assets-us-01.kc-usercontent.com/8d20758c-d74c-4f59-ae04-ee928c0816b7/806ec84e-7c71-4856-9519-ee3dd3558583/file_name.png"
}

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript // Note that this approach works when using Node.js. See a worked example using the browser import { ManagementClient } from '@kontent-ai/management-sdk'; import { readFileSync } from 'fs'; const client = new ManagementClient({ environmentId: 'KONTENT_AI_ENVIRONMENT_ID', apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY', }); const data = readFileSync('which-brewing-fits-you-1080px.jpg'); const response = await client .uploadBinaryFile() .withData({ binaryData: data, contentLength: data.byteLength, contentType: 'image/jpeg', filename: 'which-brewing-fits-you-1080px.jpg', }) .toPromise();

{ "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c", "file_name": "file_name.jpeg", "title": "Description of what the file contains", "size": 148636, "type": "image/jpeg", "url": "https://assets-us-01.kc-usercontent.com/8d20758c-d74c-4f59-ae04-ee928c0816b7/adf26cd2-1acb-403f-9d1e-6d04e46c39f1/file_name.png", "image_width": 1280, "image_height": 548, "file_reference": { "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c", "type": "internal" }, "folder": { "id": "8fe4ff47-0ca8-449d-bc63-c280efee44ea" }, "descriptions": [ { "language": { "id": "00000000-0000-0000-0000-000000000000" }, "description": "The asset's alt text in the default language describing what the file or image shows." } ], "elements": [ { "element": { "id": "c7c3b834-2222-5677-89c4-b46f04489109" }, "value": [ { "id": "53a5eecb-f295-59b4-a07d-19655b6ad860" }, { "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53" } ] } ], "external_id": "custom-asset-identifier", "last_modified": "2017-09-12T08:29:36.1645977Z" }

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { ManagementClient } from '@kontent-ai/management-sdk'; const client = new ManagementClient({ environmentId: 'KONTENT_AI_ENVIRONMENT_ID', apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY', }); const response = await client .viewAsset() .byAssetId('0270ea18-4842-4d09-9570-17b41bb37e2d') // .byAssetExternalId('which-brewing-fits-you') .toPromise();

{ "descriptions": [ { "language": { "id": "00000000-0000-0000-0000-000000000000" }, "description": "The asset's alt text for the default language." } ], "elements": [ { "element": { "id": "c7c3b834-2222-5677-89c4-b46f04489109" }, "value": [ { "id": "53a5eecb-f295-59b4-a07d-19655b6ad860" }, { "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53" } ] } ], "external_id": "custom-asset-identifier", "file_name": "file_name.png", "file_reference": { "id": "806ec84e-7c71-4856-9519-ee3dd3558583", "type": "internal" }, "folder": { "id": "8fe4ff47-0ca8-449d-bc63-c280efee44ea" }, "collection": { "reference": { "codename": "first_collection" } }, "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c", "codename": "my_asset", "image_height": 548, "image_width": 1280, "last_modified": "2019-09-12T08:29:36.1645977Z", "size": 148636, "title": "Makes the asset easier to find when you need it", "type": "image/png", "url": "https://assets-us-01.kc-usercontent.com/8d20758c-d74c-4f59-ae04-ee928c0816b7/806ec84e-7c71-4856-9519-ee3dd3558583/file_name.png" }

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { ManagementClient } from '@kontent-ai/management-sdk'; const client = new ManagementClient({ environmentId: 'KONTENT_AI_ENVIRONMENT_ID', apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY', }); // Gets the first page of results const response = await client.listAssets().toPromise(); // Gets all pages of results // const response = await client.listAssets() // .toAllPromise();

{ "assets": { "descriptions": [ { "language": { "id": "00000000-0000-0000-0000-000000000000" }, "description": "The asset's alt text for the default language." } ], "elements": [ { "element": { "id": "c7c3b834-2222-5677-89c4-b46f04489109" }, "value": [ { "id": "53a5eecb-f295-59b4-a07d-19655b6ad860" }, { "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53" } ] } ], "external_id": "custom-asset-identifier", "file_name": "file_name.png", "file_reference": { "id": "806ec84e-7c71-4856-9519-ee3dd3558583", "type": "internal" }, "folder": { "id": "8fe4ff47-0ca8-449d-bc63-c280efee44ea" }, "collection": { "reference": { "codename": "first_collection" } }, "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c", "codename": "my_asset", "image_height": 548, "image_width": 1280, "last_modified": "2019-09-12T08:29:36.1645977Z", "size": 148636, "title": "Makes the asset easier to find when you need it", "type": "image/png", "url": "https://assets-us-01.kc-usercontent.com/8d20758c-d74c-4f59-ae04-ee928c0816b7/806ec84e-7c71-4856-9519-ee3dd3558583/file_name.png" }, "pagination": { "continuation_token": "W3sidG9rZW4iOiIrUklEOn...", "next_page": "https://manage.kontent.ai/v2/your/chosen/list/endpoint" } }

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { ManagementClient } from '@kontent-ai/management-sdk'; const client = new ManagementClient({ environmentId: 'KONTENT_AI_ENVIRONMENT_ID', apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY', }); // Updates an existing asset const response = await client .updateAsset() .byAssetExternalId('which-brewing-fits-you') // .byAssetId('fcbb12e6-66a3-4672-85d9-d502d16b8d9c') .withData((builder) => { return { title: 'Coffee Brewing Techniques', assetId: 'fcbb12e6-66a3-4672-85d9-d502d16b8d9c', descriptions: [ { language: { codename: 'en-US', }, description: 'Coffee Brewing Techniques', }, { language: { codename: 'es-ES', }, description: 'Técnicas para hacer café', }, ], elements: [ builder.taxonomyElement({ element: { codename: 'taxonomy-categories', }, value: [ { codename: 'coffee', }, { codename: 'brewing', }, ], }), ], }; }) .toPromise(); // Creates a new asset or updates an existing one const response = await client .upsertAsset() .byAssetExternalId('which-brewing-fits-you') // .byAssetId('fcbb12e6-66a3-4672-85d9-d502d16b8d9c') .withData((builder) => { return { // 'file_reference' is only required when creating a new asset // To create a file reference, see the 'Upload a binary file' endpoint file_reference: { id: 'fcbb12e6-66a3-4672-85d9-d502d16b8d9c', type: 'internal', }, title: 'Coffee Brewing Techniques', external_id: 'which-brewing-fits-you', descriptions: [ { language: { codename: 'en-US', }, description: 'Coffee Brewing Techniques', }, { language: { codename: 'es-ES', }, description: 'Técnicas para hacer café', }, ], elements: [ builder.taxonomyElement({ element: { codename: 'taxonomy-categories', }, value: [ { codename: 'coffee', }, { codename: 'brewing', }, ], }), ], }; }) .toPromise();

{ "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c", "folder": { "id": "4033071a-5bc1-48da-8342-d129bb967d1d" }, "file_name": "which-brewing-fits-you-1080px.jpg", "title": "Coffee Brewing Techniques", "size": 125770, "type": "image/jpeg", "url": "https://assets-us-01.kc-usercontent.com/975bf280-fd91-488c-994c-2f04416e5ee3/fcbb12e6-66a3-4672-85d9-d502d16b8d9c/which-brewing-fits-you-1080px.jpg", "image_width": 1000, "image_height": 666, "file_reference": { "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c", "type": "internal" }, "descriptions": [ { "language": { "id": "00000000-0000-0000-0000-000000000000" }, "description": "Coffee Brewing Techniques" }, { "language": { "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8" }, "description": "Técnicas para hacer café" } ], "elements": [ { "element": { "id": "c7c3b834-2222-5677-89c4-b46f04489109" }, "value": [ { "id": "53a5eecb-f295-59b4-a07d-19655b6ad860" }, { "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53" } ] } ], "last_modified": "2017-09-12T08:29:36.1645977Z" }

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { ManagementClient } from '@kontent-ai/management-sdk'; const client = new ManagementClient({ environmentId: 'KONTENT_AI_ENVIRONMENT_ID', apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY', }); const response = await client .deleteAsset() .byAssetId('1b458663-d23a-441c-8cc2-c2825fe53b48') // .byAssetExternalId('which-brewing-fits-you') .toPromise();