File content - Cognite Docs

Works with both data modeling and asset-centric projects.

Your project type	How to identify files
Data modeling	Use `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:
- Data modeling: Use the Instances API to create and manage file nodes
- Asset-centric: Use the File metadata API to manage file metadata

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

Get an upload URL

Request an upload URL from CDF, identifying the file using instanceId (DM) or externalId/id (asset-centric).

Data modeling (instanceId)
Asset-centric (externalId)
Asset-centric (id)

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

{
  "items": [
    {
      "instanceId": {
        "space": "my_space",
        "externalId": "my-document.pdf"
      }
    }
  ]
}

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

{
  "items": [
    {
      "externalId": "my-document.pdf"
    }
  ]
}

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

{
  "items": [
    {
      "id": 123456789
    }
  ]
}

The response includes a temporary uploadUrl:

{
  "items": [
    {
      "uploadUrl": "https://upload.cognitedata.com/...",
      "instanceId": {
        "space": "my_space",
        "externalId": "my-document.pdf"
      }
    }
  ]
}

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.

Initialize multi-part upload

Data modeling (instanceId)
Asset-centric (externalId)

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

{
  "items": [
    {
      "instanceId": {
        "space": "my_space",
        "externalId": "large-file.zip"
      },
      "parts": 10
    }
  ]
}

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

{
  "items": [
    {
      "externalId": "large-file.zip",
      "parts": 10
    }
  ]
}

The response includes an uploadId that you’ll use for subsequent steps.

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.

Upload each part

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

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.

Get a download URL

Data modeling (instanceId)
Asset-centric (externalId)
Asset-centric (id)

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

{
  "items": [
    {
      "instanceId": {
        "space": "my_space",
        "externalId": "my-document.pdf"
      }
    }
  ]
}

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

{
  "items": [
    {
      "externalId": "my-document.pdf"
    }
  ]
}

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

{
  "items": [
    {
      "id": 123456789
    }
  ]
}

The response includes a temporary downloadUrl:

{
  "items": [
    {
      "downloadUrl": "https://download.cognitedata.com/...",
      "instanceId": {
        "space": "my_space",
        "externalId": "my-document.pdf"
      }
    }
  ]
}

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:

Data modeling (instanceId)
Asset-centric (id)

GET /api/v1/projects/my-project/files/icon?instanceId={"space":"my_space","externalId":"my-image.png"}

GET /api/v1/projects/my-project/files/icon?id=123456789

The endpoint returns a scaled-down version of the file suitable for use as a thumbnail or icon.

​File content vs file metadata

​Creating files

​Data modeling projects

​Asset-centric projects

​Uploading files

​Single-part upload workflow

​Multi-part upload workflow

​Downloading files

​File icons

File content vs file metadata

Creating files

Data modeling projects

Asset-centric projects

Uploading files

Single-part upload workflow

Multi-part upload workflow

Downloading files

File icons