Upload file

Create metadata information and get an uploadUrl for a file.

To upload the file, send an HTTP PUT request to the uploadUrl from the response, with the relevant 'Content-Type' and 'Content-Length' headers.

If the uploadUrl contains the string '/v1/files/gcs_proxy/', you can make a Google Cloud Storage (GCS) resumable upload request as documented in https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload.

The uploadUrl expires after one week. Any file info entry that does not have the actual file uploaded within one week will be automatically deleted.

Note: The uploadUrl from initFileUpload supports files smaller than 5 GiB.

The initMultiPartUpload and completeMultiPartUpload endpoints provides an alternative way to upload files, both small and large, up to 1 TiB in size. These endpoints exposes a uniform multipart upload API for all cloud vendor environments for CDF. Optionally parallel part uploads can be used, for faster uploads.

Request throttling

This endpoint is a subject of the new throttling schema (limited request rate and concurrency). Please check Files resource description for more information.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
query Parameters
overwrite
boolean
Default: false

If 'overwrite' is set to true, and the POST body content specifies a 'externalId' field, fields for the file found for externalId can be overwritten. The default setting is false.

If metadata is included in the request body, all of the original metadata will be overwritten. The actual file will be overwritten after a successful upload with the uploadUrl from the response. If there is no successful upload, the current file contents will be kept.

File-Asset mappings only change if explicitly stated in the assetIds field of the POST json body. Do not set assetIds in request body if you want to keep the current file-asset mappings.

header Parameters
Origin
string

The 'Origin' header parameter is required if there is a Cross Origin issue.

Request Body schema: application/json
required

Fields to be set for the file.

externalId
string (CogniteExternalId) <= 255 characters

The external ID provided by the client. Must be unique for the resource type.

name
required
string (FileName) <= 256 characters

Name of the file.

directory
string (FileDirectory) <= 512 characters

Directory containing the file. Must be an absolute, unix-style path.

source
string (FileSource) <= 128 characters

The source of the file.

mimeType
string (MimeType) <= 256 characters

File type. E.g. text/plain, application/pdf, ..

object (FilesMetadataField)

Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 128 bytes, value 10240 bytes, up to 256 key-value pairs, of total size at most 10240.

assetIds
Array of integers <int64> (CogniteInternalId) [ 1 .. 1000 ] items
dataSetId
integer <int64> (DataSetId) [ 1 .. 9007199254740991 ]

The dataSet Id for the item.

sourceCreatedTime
integer <int64> >= 0

The timestamp for when the file was originally created in the source system, specified in milliseconds since the epoch.

sourceModifiedTime
integer <int64> >= 0

The timestamp for when the file was last modified in the source system, specified in milliseconds since the epoch.

securityCategories
Array of integers <int64> (CogniteInternalId) [ 0 .. 100 ] items

The security category IDs required to access this file.

Array of objects (LabelList) [ 0 .. 10 ] items unique

A list of the labels associated with this resource item.

object (GeoLocation)

Geographic metadata.

Responses
201

The response for a successful files operation

400

The response for a failed request.

post/files
Request samples
application/json
{
  • "externalId": "my.known.id",
  • "name": "string",
  • "directory": "string",
  • "source": "string",
  • "mimeType": "image/jpeg",
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "assetIds": [
    • 1
    ],
  • "dataSetId": 1,
  • "sourceCreatedTime": 1730204346000,
  • "sourceModifiedTime": 1730204346000,
  • "securityCategories": [
    • 1
    ],
  • "labels": [
    • {
      }
    ],
  • "geoLocation": {
    • "type": "Feature",
    • "geometry": {
      },
    • "properties": { }
    }
}
Response samples
application/json
{
  • "items": [
    • {
      }
    ]
}
➔ Next to Upload multipart file