Skip to main content
Works with both data modeling and asset-centric projects.
Your project typeHow to identify files
Data modelingUse instanceId — an object with space and externalId
Asset-centric (legacy)Use externalId (string) or id (integer)
See Files in data modeling for the full DM workflow.
The file content APIs let you upload and download files and documents in CDF. These operations work with both data modeling and asset-centric projects.

​
File content vs file metadata

It’s important to understand the distinction between file content (the actual file data) and file metadata (information about the file):
  • File content operations (covered on this page): Upload and download the actual file data using uploadlink, downloadlink, and multipart upload endpoints. These work with both DM and asset-centric projects.
  • File metadata operations: Create, update, search, and manage file metadata. The approach differs by project type:

​
Creating files

Before uploading file content, you must first create the file object:

​
Data modeling projects

Create file nodes as instances in your data model using the Instances API. The file node must reference a view that includes the CogniteFile type from the core data model. See Files in data modeling for detailed instructions.

​
Asset-centric projects

Create file metadata using the File metadata API. This returns a file id or externalId that you can use for upload operations.

​
Uploading files

CDF supports two upload methods:
  • Single-part upload: For files up to 5 GB
  • Multi-part upload: For files larger than 5 GB, uploaded in chunks

​
Single-part upload workflow

1

Get an upload URL

Request an upload URL from CDF, identifying the file using instanceId (DM) or externalId/id (asset-centric).
POST /api/v1/projects/my-project/files/uploadlink
Content-Type: application/json

{
  "items": [
    {
      "instanceId": {
        "space": "my_space",
        "externalId": "my-document.pdf"
      }
    }
  ]
}
The response includes a temporary uploadUrl:
{
  "items": [
    {
      "uploadUrl": "https://upload.cognitedata.com/...",
      "instanceId": {
        "space": "my_space",
        "externalId": "my-document.pdf"
      }
    }
  ]
}
2

Upload the file content

Use the uploadUrl to upload your file with a PUT request. The upload URL is valid for 30 minutes.
PUT https://upload.cognitedata.com/...
Content-Type: application/pdf

[Binary file content]
After successful upload, the file content is available for download.

​
Multi-part upload workflow

For files larger than 5 GB, use multi-part upload to upload the file in chunks.
1

Initialize multi-part upload

POST /api/v1/projects/my-project/files/initmultipartupload
Content-Type: application/json

{
  "items": [
    {
      "instanceId": {
        "space": "my_space",
        "externalId": "large-file.zip"
      },
      "parts": 10
    }
  ]
}
The response includes an uploadId that you’ll use for subsequent steps.
2

Get upload URLs for each part

POST /api/v1/projects/my-project/files/multiuploadlink
Content-Type: application/json

{
  "items": [
    {
      "uploadId": "upload-id-from-previous-step"
    }
  ]
}
This returns temporary upload URLs for each part.
3

Upload each part

Upload each part of your file to its corresponding URL using PUT requests.
4

Complete the multi-part upload

After uploading all parts, complete the upload:
POST /api/v1/projects/my-project/files/completemultipartupload
Content-Type: application/json

{
  "items": [
    {
      "uploadId": "upload-id-from-init-step"
    }
  ]
}
CDF assembles the parts into a single file.

​
Downloading files

To download a file, request a temporary download URL and then retrieve the file content.
1

Get a download URL

POST /api/v1/projects/my-project/files/downloadlink
Content-Type: application/json

{
  "items": [
    {
      "instanceId": {
        "space": "my_space",
        "externalId": "my-document.pdf"
      }
    }
  ]
}
The response includes a temporary downloadUrl:
{
  "items": [
    {
      "downloadUrl": "https://download.cognitedata.com/...",
      "instanceId": {
        "space": "my_space",
        "externalId": "my-document.pdf"
      }
    }
  ]
}
2

Download the file content

Use the downloadUrl to retrieve the file with a GET request. The download URL is valid for 30 minutes.
GET https://download.cognitedata.com/...
The response contains the file content with the appropriate Content-Type header.

​
File icons

You can retrieve an icon or thumbnail for a file using the file icon endpoint. This works with both identification methods: 
GET /api/v1/projects/my-project/files/icon?instanceId={"space":"my_space","externalId":"my-image.png"}
The endpoint returns a scaled-down version of the file suitable for use as a thumbnail or icon.
Last modified on April 23, 2026