Upload multipart file

curl --request POST \
  --url https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<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"
    }
  ]
}
'

import requests

url = "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload"

payload = {
    "name": "<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" }]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<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'}]
  })
};

fetch('https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"externalId\": \"my.known.id\",\n  \"directory\": \"<string>\",\n  \"source\": \"<string>\",\n  \"mimeType\": \"image/jpeg\",\n  \"metadata\": {},\n  \"assetIds\": [\n    4503599627370496\n  ],\n  \"dataSetId\": 4503599627370496,\n  \"sourceCreatedTime\": 1730204346000,\n  \"sourceModifiedTime\": 1730204346000,\n  \"securityCategories\": [\n    4503599627370496\n  ],\n  \"labels\": [\n    {\n      \"externalId\": \"my.known.id\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"externalId\": \"my.known.id\",\n  \"directory\": \"<string>\",\n  \"source\": \"<string>\",\n  \"mimeType\": \"image/jpeg\",\n  \"metadata\": {},\n  \"assetIds\": [\n    4503599627370496\n  ],\n  \"dataSetId\": 4503599627370496,\n  \"sourceCreatedTime\": 1730204346000,\n  \"sourceModifiedTime\": 1730204346000,\n  \"securityCategories\": [\n    4503599627370496\n  ],\n  \"labels\": [\n    {\n      \"externalId\": \"my.known.id\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"externalId\": \"my.known.id\",\n  \"directory\": \"<string>\",\n  \"source\": \"<string>\",\n  \"mimeType\": \"image/jpeg\",\n  \"metadata\": {},\n  \"assetIds\": [\n    4503599627370496\n  ],\n  \"dataSetId\": 4503599627370496,\n  \"sourceCreatedTime\": 1730204346000,\n  \"sourceModifiedTime\": 1730204346000,\n  \"securityCategories\": [\n    4503599627370496\n  ],\n  \"labels\": [\n    {\n      \"externalId\": \"my.known.id\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "name": "<string>",
      "id": 4503599627370496,
      "uploaded": true,
      "createdTime": 1730204346000,
      "lastUpdatedTime": 1730204346000,
      "uploadId": "<string>",
      "uploadUrls": [
        "uploadURL_for_part_1",
        "uploadURL_for_part_2",
        "uploadURL_for_part_3"
      ],
      "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>"
      }
    }
  ]
}

{
  "error": {
    "code": 401,
    "message": "Could not authenticate.",
    "missing": [
      {}
    ],
    "duplicated": [
      {}
    ]
  }
}

Upload multipart file

Required capabilities: filesAcl:WRITE

Multipart file upload enables upload of files larger than 5000 MB, using a uniform API on all cloud environments for CDF.

Each file part must be larger than 5 MiB, and smaller than 4000 MiB. The file part for the last uploadURL can be smaller than 5 MiB. Maximum 250 upload URLs can be requested. The supported maximum size for each file uploaded with the multi-part upload API is therefore 1000 GiB (1.073 TB / 0.976 TiB). The client should calculate the ideal number of parts depending on predetermined or estimated file size, between 1 and the maximum. Specify the number of parts in the parts URL query parameter. The parts parameter is required.

The request creates metadata information for a new file, and returns in addition to the file id, also a uploadId, and a list of uploadUrls for uploading the file contents. To upload a file, send an HTTP PUT request to each of the uploadUrls, with the corresponding part of the file in the request body. You may use a ‘Content-Length’ header in the PUT request for each part, but this is not required. A failed part PUT upload can be retried.

If ‘contentEncoding’ is specified in the files/initmultipartupload request body, the full file contents must be compressed with that encoding before uploading the parts as byte ranges of the full content. When the file is later downloaded through a download link, the response will include a ‘Content-Encoding’ header set to this value, and the client is responsible for decompressing the content accordingly.

The client must ensure that the parts of the source file are stored in the correct order, using the order of the uploadUrls as specified in the response. This to avoid ending up with a corrupt final file.

The parts can optionally be uploaded in parallel, preferably on a subset of parts at a time, for example maximum 3 concurrent PUT operations.

Once all file parts have been uploaded, the client should call the ‘files/completemultipartupload’ endpoint, with the required file ID (as id or externalId) and uploadId fields in the request body. This will assemble the parts into one file. The file’s uploaded flag will then eventually be set to true.

A standard sequence of calls to upload a large file with multipart upload would be for example as follows:

POST files/initmultipartupload?parts=8, to start a multipart upload session with 8 parts. Optionally specify the contentEncoding request body property if the file content is compressed with a compression encoding. Use standard CDF project request headers such as Authorization and Content-Type for this POST request. Also optionally add a Content-Encoding request header to this POST request, but note that it would be for the compressed JSON POST request body content, not for the full file content. Expect a 201 CREATED response code, and a response body with information to be used in the PUT <uploadURL> and POST files/completemultipartupload requests.
PUT <uploadUrl>, for each of the uploadUrls in the response from the files/initmultipartupload request. Expect a 200 OK or 201 CREATED response for each PUT request. NOTE: You can set the Content-Length request header for this PUT request. Do not add Authorization, Content-Type or Content-Encoding headers in the PUT <uploadURL> requests for the multipart upload based requests.
POST files/completemultipartupload, with request body { "id":123456789, "uploadId":"ABCD4321EFGH" }. This will assemble the file. Use standard CDF project POST request headers such as Authorization, Content-Type for this request. Expect a 200 OK response.

Consider verifying that the file is eventually marked as uploaded with a call to the getFileByInternalId endpoint.

NOTE: The uploadUrls expires after one week. A file that does not have the file content parts uploaded and completed within one week will be automatically deleted.

Request throttling

Please note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency. For more details, please refer to the Files resource documentation.

POST

files

initmultipartupload

Upload multipart file

curl --request POST \
  --url https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<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"
    }
  ]
}
'

import requests

url = "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload"

payload = {
    "name": "<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" }]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<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'}]
  })
};

fetch('https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"externalId\": \"my.known.id\",\n  \"directory\": \"<string>\",\n  \"source\": \"<string>\",\n  \"mimeType\": \"image/jpeg\",\n  \"metadata\": {},\n  \"assetIds\": [\n    4503599627370496\n  ],\n  \"dataSetId\": 4503599627370496,\n  \"sourceCreatedTime\": 1730204346000,\n  \"sourceModifiedTime\": 1730204346000,\n  \"securityCategories\": [\n    4503599627370496\n  ],\n  \"labels\": [\n    {\n      \"externalId\": \"my.known.id\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"externalId\": \"my.known.id\",\n  \"directory\": \"<string>\",\n  \"source\": \"<string>\",\n  \"mimeType\": \"image/jpeg\",\n  \"metadata\": {},\n  \"assetIds\": [\n    4503599627370496\n  ],\n  \"dataSetId\": 4503599627370496,\n  \"sourceCreatedTime\": 1730204346000,\n  \"sourceModifiedTime\": 1730204346000,\n  \"securityCategories\": [\n    4503599627370496\n  ],\n  \"labels\": [\n    {\n      \"externalId\": \"my.known.id\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"externalId\": \"my.known.id\",\n  \"directory\": \"<string>\",\n  \"source\": \"<string>\",\n  \"mimeType\": \"image/jpeg\",\n  \"metadata\": {},\n  \"assetIds\": [\n    4503599627370496\n  ],\n  \"dataSetId\": 4503599627370496,\n  \"sourceCreatedTime\": 1730204346000,\n  \"sourceModifiedTime\": 1730204346000,\n  \"securityCategories\": [\n    4503599627370496\n  ],\n  \"labels\": [\n    {\n      \"externalId\": \"my.known.id\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "name": "<string>",
      "id": 4503599627370496,
      "uploaded": true,
      "createdTime": 1730204346000,
      "lastUpdatedTime": 1730204346000,
      "uploadId": "<string>",
      "uploadUrls": [
        "uploadURL_for_part_1",
        "uploadURL_for_part_2",
        "uploadURL_for_part_3"
      ],
      "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>"
      }
    }
  ]
}

{
  "error": {
    "code": 401,
    "message": "Could not authenticate.",
    "missing": [
      {}
    ],
    "duplicated": [
      {}
    ]
  }
}

Authorizations

Authorization

string

header

required

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.

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. 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.

parts

integer<int32>

required

The 'parts' parameter specifies how many uploadURLs should be returned, for uploading the file contents in parts. See main endpoint description for more details.

Required range: 1 <= x <= 250

Body

application/json

Fields to be set for the file.

name

string

required

Name of the file.

Maximum string length: 256

externalId

string

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

Maximum string length: 255

Example:

"my.known.id"

Response

The response for a successful request to initiate upload of multiple parts for a file.

items

object[]

Show child attributes

Last modified on July 31, 2026

Download files

Get multipart file upload link

⌘I