const fileContent = 'file data here'; // can also be of type ArrayBuffer, Buffer, Blob, File or any
// automatic upload:
const file = await client.files.upload({name: 'examplefile.jpg', mimeType: 'image/jpeg'}, fileContent);
// manual with uploadUrl:
const file2 = await client.files.upload({name: 'examplefile.jpg', mimeType: 'image/jpeg'});
// then upload using the file.uploadUrl{
"name": "<string>",
"id": 4503599627370496,
"uploaded": true,
"createdTime": 1730204346000,
"lastUpdatedTime": 1730204346000,
"uploadUrl": "<string>",
"externalId": "my.known.id",
"directory": "<string>",
"source": "<string>",
"mimeType": "image/jpeg",
"metadata": {},
"assetIds": [
4503599627370496
],
"dataSetId": 4503599627370496,
"sourceCreatedTime": 1730204346000,
"sourceModifiedTime": 1730204346000,
"securityCategories": [
4503599627370496
],
"labels": [
{
"externalId": "my.known.id"
}
],
"geoLocation": {
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
123
]
},
"properties": {}
},
"uploadedTime": 1730204346000,
"instanceId": {
"space": "<string>",
"externalId": "<string>"
}
}Required capabilities:
filesAcl:WRITE
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 single part uploadUrl from initFileUpload supports uploading files up to 5000 MB (5,000,000,000 bytes) in size. For larger files than that, please use the multipart upload API.
The initMultiPartUpload and completeMultiPartUpload endpoints provides an alternative way to upload files, both small and large, up to 1000 GiB 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 subject to the new throttling policy, which enforces limits on both request rate and concurrency. For more details, please refer to the Files resource documentation.
const fileContent = 'file data here'; // can also be of type ArrayBuffer, Buffer, Blob, File or any
// automatic upload:
const file = await client.files.upload({name: 'examplefile.jpg', mimeType: 'image/jpeg'}, fileContent);
// manual with uploadUrl:
const file2 = await client.files.upload({name: 'examplefile.jpg', mimeType: 'image/jpeg'});
// then upload using the file.uploadUrl{
"name": "<string>",
"id": 4503599627370496,
"uploaded": true,
"createdTime": 1730204346000,
"lastUpdatedTime": 1730204346000,
"uploadUrl": "<string>",
"externalId": "my.known.id",
"directory": "<string>",
"source": "<string>",
"mimeType": "image/jpeg",
"metadata": {},
"assetIds": [
4503599627370496
],
"dataSetId": 4503599627370496,
"sourceCreatedTime": 1730204346000,
"sourceModifiedTime": 1730204346000,
"securityCategories": [
4503599627370496
],
"labels": [
{
"externalId": "my.known.id"
}
],
"geoLocation": {
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
123
]
},
"properties": {}
},
"uploadedTime": 1730204346000,
"instanceId": {
"space": "<string>",
"externalId": "<string>"
}
}Authorizations
Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.
Headers
The 'Origin' header parameter is required if there is a Cross Origin issue.
Query Parameters
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.
Body
Fields to be set for the file.
Name of the file.
256The external ID provided by the client. Must be unique for the resource type.
255"my.known.id"
Directory containing the file. Must be an absolute, unix-style path.
512The source of the file.
128File type. E.g. text/plain, application/pdf, ..
256"image/jpeg"
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.
Show child attributes
Show child attributes
1 - 1000 elementsA server-generated ID for the object.
1 <= x <= 9007199254740991The dataSet Id for the item.
1 <= x <= 9007199254740991The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
x >= 01730204346000
The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
x >= 01730204346000
The security category IDs required to access this file.
100A server-generated ID for the object.
1 <= x <= 9007199254740991A list of the labels associated with this resource item.
10Show child attributes
Show child attributes
Geographic metadata.
Show child attributes
Show child attributes
Response
The response for a successful files operation
Name of the file.
256A server-generated ID for the object.
1 <= x <= 9007199254740991Whether or not the actual file is uploaded. This field is returned only by the API, it has no effect in a post body.
true
The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
x >= 01730204346000
The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
x >= 01730204346000
The URL where the file contents should be uploaded.
The external ID provided by the client. Must be unique for the resource type.
255"my.known.id"
Directory containing the file. Must be an absolute, unix-style path.
512The source of the file.
128File type. E.g. text/plain, application/pdf, ..
256"image/jpeg"
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.
Show child attributes
Show child attributes
1 - 1000 elementsA server-generated ID for the object.
1 <= x <= 9007199254740991The dataSet Id for the item.
1 <= x <= 9007199254740991The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
x >= 01730204346000
The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
x >= 01730204346000
The security category IDs required to access this file.
100A server-generated ID for the object.
1 <= x <= 9007199254740991A list of the labels associated with this resource item.
10Show child attributes
Show child attributes
Geographic metadata.
Show child attributes
Show child attributes
The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
x >= 01730204346000
Show child attributes
Show child attributes
Was this page helpful?