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.

These operations stay available. Asset-centric identifiers on these operations are deprecated. Identify the resource with an instance ID (space and externalId) instead.See Deprecated and retired features for dates, and Data modeling status for CDF projects for how DATA_MODELING_ONLY and HYBRID projects behave while you upgrade.

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. Create the instance in the space where you want to store the file. For the workflow, see Files in data modeling. To create the node and upload content in the Python SDK, see Create a file node and upload content.

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. To assign the file to a data set, include dataSetId when you create the file. See Create data sets. In the Python SDK, pass data_set_id to Upload a file or directory.

Uploading files

CDF supports two upload methods:

Single-part upload: For files up to 5000 MB (5,000,000,000 bytes)
Multi-part upload: For files up to 1000 GiB

Upload limits

An upload URL expires after one week. CDF deletes the file record if the content is not uploaded, or the multipart upload is not completed, within that week. A single-part upload URL accepts at most 5000 MB. Use multipart upload for a larger file. If the upload URL contains /v1/files/gcs_proxy/, you can use a Google Cloud Storage resumable upload. Multipart upload uses the same API on every CDF cloud. Set the required parts query parameter to a value from 1 to 250. Each part must be larger than 5 MiB and smaller than 4000 MiB, except the last part, which can be smaller than 5 MiB. You can retry a failed part upload. Limit parallel part uploads, for example to 3 at a time. POST /files/initmultipartupload creates the file and returns the uploadId and the upload URLs. POST /files/multiuploadlink returns upload URLs for a file that already exists. Send each part with PUT and no Authorization, Content-Type, or Content-Encoding header. Content-Length is optional. Then call POST /files/completemultipartupload with either id or externalId, plus uploadId. The uploaded flag becomes true after CDF assembles the parts. Confirm that with a retrieve call. Data modeling uploads can use filesAcl:WRITE, or dataModelsAcl:READ on the cdf_cdm space together with dataModelInstancesAcl:WRITE.

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 expires after one week. See Upload limits.

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.

Content encoding

If the bytes you upload are compressed, set Content-Encoding on the single-part PUT, or set contentEncoding on the multipart init or multi-upload request. Compress the full file before you split it into parts. The download response repeats that Content-Encoding value, and your client decompresses the body. Do not use the Content-Encoding header on POST /files/initmultipartupload to describe the file. That header applies only to the JSON request body.

Downloading files

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

Download links

A download URL expires after 30 seconds. Set extendedExpiration to keep it for 1 hour. Send GET to the URL to read the file. You can request a byte range with Range: bytes=start-end. The response includes Content-Range for the returned range and the full size, and Content-Length for the size of that range.

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 expires after 30 seconds, or after 1 hour when you set extendedExpiration. See Download links.

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. JPEG and PNG images are supported. Other image formats might return an icon, but that support can change. A request for an unsupported file returns HTTP 400. Pass either id or externalId, not both.

​File content vs file metadata

​Creating files

​Data modeling projects

​Asset-centric projects

​Uploading files

​Upload limits

​Single-part upload workflow

​Multi-part upload workflow

​Content encoding

​Downloading files

​Download links

​File icons

File content vs file metadata

Creating files

Data modeling projects

Asset-centric projects

Uploading files

Upload limits

Single-part upload workflow

Multi-part upload workflow

Content encoding

Downloading files

Download links

File icons