Skip to content

IoT File Service


The IoT File Service provides the user with file management for files related to assets. The service provides an interface to manage data, search files and download them to specified agents. Files can also be uploaded to a temporary storage and managed there.


For accessing this service you need to have the respective roles listed in IoT File Service roles and scopes.

A user can only interact with files within their environment and subtenants.

For accessing the Secure Data Sharing (SDS) protected APIs you need to have appropriate Policy Definitions in place. Please refer here for the list of supported APIs and Required Actions.


The service implements CRUD (create, read, update and delete) functionality and searching for files.

Each file is linked to an asset. An asset can have multiple files attached. The asset ID is required for each request.

Each file has a set of standard properties as metadata:

  • File ID
  • File name
  • File path
  • File type (e.g., image)
  • File size
  • Description
  • Timestamps (created, updated)

The content of these files is not parsed by Insights Hub and it requires custom applications or analytical tools to interpret and visualize the data.

The maximum request payload that can be stored or retrieved depends on the client's network speed. The current timeout is one minute, and any file that takes longer than one minute to read or write results in an error 502 "Bad Gateway". If a file is too large to upload in one minute, use the multi part upload feature.

Supported Use Cases

Typical use cases that are supported within File Service are as follows:

  • Storing static data related to Assets (configuration files, images, specifications, etc.)
  • Supports low frequency operations on the data (once in a day, weekly or even monthly)
  • Temporary storage of data to explore real time data storage in Time Series


Avoid the use of File Service for high frequency and continuous read or write, analytical workflows and storing high volume real-time data (Time Series data).


The service does not provide explicit versioning. If different versions of a file need to be stored, put a version identifier in the file name to make it unique.

File Deletion

Files are always deleted physically. There is no logical delete. Files of an asset are automatically deleted if the asset is deleted physically.

Files can be deleted from the storage in the following ways:

Delete MechanismDescription
Single File DeleteDelete a file for the specified asset (entity) and path (actual file + metadata). This is a synchronous call.
Bulk DeleteDelete files in bulk (actual files + metadata). This is an asynchronous activity in which files are deleted from storage within a day.
There is an API available for bulk deletion using Time To (Live) rule. Users are required to create a Time To Live (TTL) rule to initiate bulk file deletion. The TTL rule specifies the duration after which files are automatically deleted by the system. This rule operates on a daily basis, identifying and removing files that meet the criteria outlined in the rule.
Asset DeleteIf the underlying asset is deleted, the files related to that asset are also deleted from the storage. File deletion is triggered on asset delete notification. This is also an asynchronous activity.

Files can be queried using filtering and sorting operations. For more information refer to the Filtering documentation.


The IoT File Service exposes its API for realizing the following tasks:

  • Create a new file
  • Update (overwrite) an existing file
  • Read a file
  • Delete a file
  • Search for files by metadata
  • Count and order files by metadata
  • Multi part upload and download
  • Bulk delete of files for an asset


  • For security reasons, a strict timeout is enforced. Currently, this leads to the situation that the size of a file which can be uploaded/ downloaded depends on the network bandwidth at client side.
  • When uploading files to the File Service, a file name cannot contain blank spaces. Blank spaces in the file name will prevent the file form being stored.
  • After deleting an asset, associated files might still be accessible for up to 30 minutes as this data is deleted asynchronously.
  • After deleting a file, it will take some time (up to 60 - 120 seconds) to create the file with the same name again depending on the data stored in storage.
  • After creating or deleting the file, it will take some time (up to 3 seconds) to get the file in "search file" API.
  • In File Service, a maximum of 100 characters are allowed for a file name.
  • Using special characters like '*' or '?' can delay the search and might result in slow search performance.

All requests pass through Industrial IoT Gateway and must adhere to the Industrial IoT Gateway Restrictions.

Usage Quota and Limits

IoT File Service APIs are restricted with following limitations:

API EndpointQuota ParameterXXS (S4F)XS (Offering ID5302)S (Offering ID5303)M (Offering ID5304)L (Offering ID5305)XL (Offering ID5306)
PUT (Short Window)core_iotfile_v3_files--_put_30s6810121416
PUT (Long Window)core_iotfile_v3_files--_put_600s10100140180220280
LIST (Short Window)core_iotfile_v3_files--_get_30s61012151820
LIST (Long Window)core_iotfile_v3_files--_get_600s30210240270300350
GET (Short Window)core_iotfile_v3_files-~_get_30s61214182225
GET (Long Window)core_iotfile_v3_files-~_get_600s30200250300400500
DELETE (Short Window)core_iotfile_v3_files--_delete_30s112345
DELETE (Long Window)core_iotfile_v3_files--_delete_600s31012152025
POST Bulk Delete (Short Window)core_iotfile_v3_filesdeletejobs_post_6h012345
POST Bulk Delete (Long Window)core_iotfile_v3_filesdeletejobs_post_24h023468
Get Bulk Delete Jobs (Short Window)core_iotfile_v3_files-deletejobs-~_get_30s012345
Get Bulk Delete Jobs (Long Window)core_iotfile_v3_files-deletejobs-~_get_600s089101215
Get Bulk Delete Job Detail (Short Window)core_iotfile_v3_filesdeletejobs_get_30s012345
Get Bulk Delete Job Detail (Long Window)core_iotfile_v3_filesdeletejobs_get_600s089101215


Rate Limits can cause discontinuity in the use case flow. Ensure to check the rate limits before implementing File Service APIs. Also, check the alternate storage mechanisms within Insights Hub for advanced use cases.

Example Scenario

The application developer of a brewery wants to store files associated to assets in order to provide additional meta information (e.g., images, technical descriptions, manuals, etc.).

The developer uses the IoT File Service to upload files to an asset.


Connect and Collaborate with Industrial Professionals and Join the Community!

Click to load comments