Assets

The Get all assets request returns comprehensive information on all assets available in a stack.

To configure the permissions for your application via OAuth, please include the cm.assets.management:read scope.
Additionally, if you wish to fetch the metadata attached to each asset, then you need to pass include_metadata as a query parameter. Set this parameter to true to include the asset metadata along with all assets in the response body.

You will find the asset metadata under the _metadata key in the response. It will be associated with a specific extension UID as follows:

    "_metadata":{
    "extensions":{
       "{extension_uid}":[
            {
                "image_copyrights": "Contentstack Branding",
                "scope”: “local”
            }
        ]
    }
}

You can add queries to extend the functionality of this API call. Under the URL Parameters section, insert a parameter named query and provide a query in JSON format as the value.

To learn more about the queries, refer to the Queries section of the Content Delivery API doc.

Tip To include the publish details in the response, make use of the include_publish_details parameter and set its value to ‘true’. This query will return the publish details of the entry in every environment along with the version number that is published in each of the environment. When you publish an asset, the associated metadata of that asset will also get published.

The Get an asset request returns comprehensive information about a specific version of an asset of a stack.

To configure the permissions for your application via OAuth, please include the cm.assets.management:read scope.
Additionally, if you wish to fetch the metadata attached to each asset, then you need to pass include_metadata as a query parameter. Set this parameter to true to include the asset metadata along with all assets in the response body.

You will find the asset metadata under the _metadata key in the response. It will be associated with a specific extension UID as follows:

 "_metadata":{
    "extensions":{
       "{extension_uid}":[
            {
                "image_copyrights": "Contentstack Branding",
                "scope”: “local”
            }
        ]
    }
}

Tip To include the publish details in the response, make use of the include_publish_details parameter and set its value to ‘true’. This query will return the publish details of the entry in every environment along with the version number that is published in each of the environment. When you publish an asset, the associated metadata of that asset will also get published. However, when publishing assets in bulk, the associated metadata of the assets will not get published.

The Get assets of a specific folder retrieves all assets of a specific asset folder; however, it doesn't retrieve the details of subfolders within it.
To configure the permissions for your application via OAuth, please include the cm.assets.management:read scope.

The Get assets and folders of a parent folder retrieves details of both assets and asset subfolders within a specific parent asset folder.
To configure the permissions for your application via OAuth, please include the cm.assets.management:read scope.

The Upload asset request uploads an asset file to your stack.
To configure the permissions for your application via OAuth, please include the cm.assets.management:write scope.

To upload assets from your local system to Contentstack and manage their details, you need to use the following "form-data" parameters:

You can try the call manually in any REST API client, such as Postman. Here's a screenshot for reference:

Click to enlarge

For easier access, here's the cURL for this API Request:

curl -X POST \
  https://api.contentstack.io/v3/assets?include_dimension=true \
  -H 'api_key: {api_key_of_your_stack}' \
  -H 'authtoken: {your_authtoken}' \
  -H 'cache-control: no-cache' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'asset[upload]=@{Filepath e.g., /C:/Users/abc/Desktop/Sample.png}' \
  -F 'asset[parent_uid]={If you need to add this file under an existing asset folder, pass the UID of the parent folder.}' \
  -F 'asset[title]={If needed, enter a title for your uploaded asset.}' \
  -F 'asset[description]={If needed, enter a description for your uploaded asset.}'
  -F 'asset[tags]={If needed, assign a specific tag to your uploaded asset.}'

In the above cURL command, pass the necessary values within the curly brackets. The asset[parent_uid],asset[title],asset[description],asset[tags], and include_dimension=true parameters are optional. You can skip them if not required.

The Replace asset call will replace an existing asset with another file on the stack.
To configure the permissions for your application via OAuth, please include the cm.assets.management:write scope.

Tip You can try the call manually in any REST API client, such as Postman.
Under 'Body', pass a body parameter named asset[upload] and select the input type as 'File'. This will enable you to select the file that you wish to import.
You can assign a parent folder to your asset by using the asset[parent_uid] parameter, where you can pass the UID of the parent folder.
Additionally, you can pass optional parameters such as asset[title] and asset[description] which let you enter a title and a description for the uploaded asset, respectively.

The Generate Permanent Asset URL request allows you to generate a permanent URL for an asset. This URL remains constant irrespective of any subsequent updates to the asset.
To configure the permissions for your application via OAuth, please include the cm.assets.management:write scope.

WarningYou can generate the permanent asset URL and update the asset details only once. Once done, you can no longer make changes to the permanent URL.

In the request body, you need to pass the permanent URL in the following format:

{
    "asset": {
        "permanent_url": "https://images.contentstack.io/v3...{stack_api_key}/{asset_uid}/{unique_identifier}"

    }
}

In the above URL, you can pass any unique identifier (slug) that suits your requirement.

Another way to generate a permanent URL for an asset is to pass the URL as a form-data parameter, i.e., asset[permanent_url]. In that case, the Content-Type in the Headers section must be changed from application/json to multipart/form-data. You can provide the permanent URL of your choice (along with a slug) as a value for this parameter, for example:

https://{base_URL}/v3/assets/{stack_api_key}/{asset_uid}/{slug}

The Download an asset with permanent URL request displays an asset in the response. The asset returned in the response can be saved to your local storage system. Make sure to specify the unique identifier (slug) in the request URL.

To configure the permissions for your application via OAuth, please include the cm.assets:download scope.

This request will return the most recent version of the asset, however, to download the latest published version of the asset, pass the environment query parameter with the environment name.

NoteBefore executing this API request, ensure to create a permanent URL for the asset you want to download.

The Delete asset call will delete an existing asset from the stack.
To configure the permissions for your application via OAuth, please include the cm.assets.management:write scope.

The Get information on RTE assetscall returns comprehensive information on all assets uploaded through the Rich Text Editor field.
To configure the permissions for your application via OAuth, please include the cm.assets.rt:read scope.

The Set Version Name for Asset request allows you to assign a name to a specific version of an asset.

In the request body, you need to specify the version name to be assigned to the asset version.

To configure the permissions for your application via OAuth, please include the cm.asset:writescope.

The Get Details of All Versions of an Asset request returns comprehensive information of all the versions of a specific asset within your stack.

The Delete Version Name of Asset request allows you to delete the name assigned to a specific version of an asset. This request resets the name of the asset version to the version number.

To configure the permissions for your application via OAuth, please include the cm.asset:write scope.

The Get asset references request retrieves a list of entries and content types that reference the specified asset.

When using OAuth, ensure your application includes the cm.asset:read scope to access this endpoint.

To include publish-related metadata for the referenced asset, set the include_publish_details query parameter to true. This metadata includes:

• _version_name: Name assigned to the latest version (if available)
• _version: Latest version number of the specified asset
• publish_details: An array of objects containing:
  • environment: UID of the environment where the asset is published
  • locale: Locale of the published asset
  • time: Timestamp of when the asset was published
  • user: UID of the user who performed the publishing action
  • version: Version number that was published
  • version_name: Metadata about the published version, including title, updated_by, and updated_at

The Get either only images or videos request retrieves assets that are either image or video files, based on query request.
To configure the permissions for your application via OAuth, please include the cm.assets.management:read scope.

You can add queries to extend the functionality of this API call. Under the URL Parameters section, insert a parameter named query and provide a query in JSON format as the value.

To learn more about the queries, refer to the Queries section of the Content Delivery API doc.

The Update asset revision call upgrades a specified version of an asset as the latest version of that asset.

To configure the permissions for your application via OAuth, please include the cm.assets.management:write scope.

Under 'Body', you need to specify the asset version number that you want to make the latest in raw JSON format, and also provide a "Title" and a "Description" for the asset. Another way to provide a "Title" and a "Description" for the asset is to pass them as optional form-data parameters, i.e., asset[title] and asset[description].

Here's an example of the raw body:

{
    "asset": {
        "title": "Title",
        "description": "Description"
    },
    "version": 3
}

The Update asset request allows you to update the title and description of an asset.
To configure the permissions for your application via OAuth, please include the cm.assets.management:write scope.

NoteHere are some points to keep in mind:
1. You can also use this request to Generate a permanent URL for your asset, which remains constant irrespective of any further updates to the asset.
2. This call updates only the meta data of an asset. To replace an asset, try the Replace asset request under Asset Collection.

Under 'Body', you need to pass the updated details of "Title" and "Description" is in the form of 'raw' body as follows:

{
   "asset":{
      "title":"new title",
       "description":"updated description"
     }
}

Another way to provide a "Title" and a "Description" for the asset is to pass them as optional form-data parameters, i.e., asset[title] and asset[description]. You can assign a parent folder to your asset by using the asset[parent_uid] parameter, where you need to pass the UID of the parent folder.

The Publish an asset call is used to publish a specific version of an asset on the desired environment either immediately or at a later date/time.
To configure the permissions for your application via OAuth, please include the cm.asset:publish scope.

NoteWhen you publish an asset, the associated metadata of that asset will also get published. However, when publishing assets in bulk, the associated metadata of the assets will not get published.

In case of Scheduled Publishing, add the scheduled_at key and provide the date/time in the ISO format as its value. Example: "scheduled_at":"2016-10-07T12:34:36.000Z"

In the 'Body' section, enter the asset details, such as locales and environments, where the assets need to be published. These details should be in JSON format.

The Unpublish an asset call is used to unpublish a specific version of an asset from a desired environment.
To configure the permissions for your application via OAuth, please include the cm.asset:unpublish scope.

In case of Scheduled Unpublishing, add the scheduled_at key and provide the date/time in the ISO format as its value. Example: "scheduled_at":"2016-10-07T12:34:36.000Z"

In the 'Body' section, enter the asset details, such as locales and environments, from where the assets need to be unpublished. These details should be in JSON format.

The Get a single folder call gets the comprehensive details of a specific asset folder by means of folder UID.
To configure the permissions for your application via OAuth, please include the cm.assets.management:read scope.

When executing the API call to search for a subfolder, you need to provide the parent folder UID.

The Get a single folder by name call retrieves a specific asset folder based on the name provided.
To configure the permissions for your application via OAuth, please include the cm.assets.management:read scope.

The Get subfolders of a parent folder request retrieves the details of only the subfolders of a specific asset folder. This request does not retrieve asset files.
To configure the permissions for your application via OAuth, please include the cm.assets.management:read scope.

The Create a folder call is used to create an asset folder and/or add a parent folder to it (if required). To configure the permissions for your application via OAuth, please include the cm.assets.management:write scope.

In the ‘Body’ section, you need to provide a name for the new folder.

If you want to place this folder within another folder, provide the UID of the parent folder in the Request body as follows:

{
    "asset": {
        "name": "asset_folder_name",
        "parent_uid": "asset_parent_folder_uid"
    }
}

Note Here are some points that needs to be considered when executing this API request:

• A maximum of 300 folders can be created.
• The maximum level of folder nesting is 5.
• When nesting folder, you cannot nest a folder within the same folder or within its child folders.

The Update or move folder request can be used either to update the details of a folder or set the parent folder if you want to move a folder under another folder.
To configure the permissions for your application via OAuth, please include the cm.assets.management:write scope.

When executing the API request, provide the UID of the folder that you want to move/update.

In the ‘Body’ section, you need to provide a new name for your folder, and if you want to move your folder within another folder, then you need provide the UID of the parent folder.

NoteHere are some points that needs to be considered when executing this API request:

• A maximum of 300 folders can be created.
• The maximum level of folder nesting is 5.
• When nesting folder, you cannot nest a folder within the same folder or within its child folders.

The Delete a folder call is used to delete an asset folder along with all the assets within that folder.

When executing the API call, provide the parent folder UID.
To configure the permissions for your application via OAuth, please include the cm.assets.management:write scope.