> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# File content

> Upload and download file content in Cognite Data Fusion (CDF).

<Info>
  **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](/cdf/dm/dm_guides/dm_integrate_files) for the full DM workflow.
</Info>

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](/api-reference/concepts/20230101/instances) to create and manage file nodes
  * **Asset-centric**: Use the [File metadata API](/api-reference/concepts/20230101/files) 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](/api-reference/concepts/20230101/instances). The file node must reference a view that includes the `CogniteFile` type from the core data model.

See [Files in data modeling](/cdf/dm/dm_guides/dm_integrate_files) for detailed instructions.

### Asset-centric projects

Create file metadata using the [File metadata API](/api-reference/concepts/20230101/files). 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

<Steps>
  <Step title="Get an upload URL">
    Request an upload URL from CDF, identifying the file using `instanceId` (DM) or `externalId`/`id` (asset-centric).

    <Tabs>
      <Tab title="Data modeling (instanceId)">
        ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        POST /api/v1/projects/my-project/files/uploadlink
        Content-Type: application/json

        {
          "items": [
            {
              "instanceId": {
                "space": "my_space",
                "externalId": "my-document.pdf"
              }
            }
          ]
        }
        ```
      </Tab>

      <Tab title="Asset-centric (externalId)">
        ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        POST /api/v1/projects/my-project/files/uploadlink
        Content-Type: application/json

        {
          "items": [
            {
              "externalId": "my-document.pdf"
            }
          ]
        }
        ```
      </Tab>

      <Tab title="Asset-centric (id)">
        ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        POST /api/v1/projects/my-project/files/uploadlink
        Content-Type: application/json

        {
          "items": [
            {
              "id": 123456789
            }
          ]
        }
        ```
      </Tab>
    </Tabs>

    The response includes a temporary `uploadUrl`:

    ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
      "items": [
        {
          "uploadUrl": "https://upload.cognitedata.com/...",
          "instanceId": {
            "space": "my_space",
            "externalId": "my-document.pdf"
          }
        }
      ]
    }
    ```
  </Step>

  <Step title="Upload the file content">
    Use the `uploadUrl` to upload your file with a `PUT` request. The upload URL is valid for 30 minutes.

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    PUT https://upload.cognitedata.com/...
    Content-Type: application/pdf

    [Binary file content]
    ```

    <Check>
      After successful upload, the file content is available for download.
    </Check>
  </Step>
</Steps>

### Multi-part upload workflow

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

<Steps>
  <Step title="Initialize multi-part upload">
    <Tabs>
      <Tab title="Data modeling (instanceId)">
        ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        POST /api/v1/projects/my-project/files/initmultipartupload
        Content-Type: application/json

        {
          "items": [
            {
              "instanceId": {
                "space": "my_space",
                "externalId": "large-file.zip"
              },
              "parts": 10
            }
          ]
        }
        ```
      </Tab>

      <Tab title="Asset-centric (externalId)">
        ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        POST /api/v1/projects/my-project/files/initmultipartupload
        Content-Type: application/json

        {
          "items": [
            {
              "externalId": "large-file.zip",
              "parts": 10
            }
          ]
        }
        ```
      </Tab>
    </Tabs>

    The response includes an `uploadId` that you'll use for subsequent steps.
  </Step>

  <Step title="Get upload URLs for each part">
    ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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.
  </Step>

  <Step title="Upload each part">
    Upload each part of your file to its corresponding URL using `PUT` requests.
  </Step>

  <Step title="Complete the multi-part upload">
    After uploading all parts, complete the upload:

    ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    POST /api/v1/projects/my-project/files/completemultipartupload
    Content-Type: application/json

    {
      "items": [
        {
          "uploadId": "upload-id-from-init-step"
        }
      ]
    }
    ```

    <Check>
      CDF assembles the parts into a single file.
    </Check>
  </Step>
</Steps>

## Downloading files

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

<Steps>
  <Step title="Get a download URL">
    <Tabs>
      <Tab title="Data modeling (instanceId)">
        ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        POST /api/v1/projects/my-project/files/downloadlink
        Content-Type: application/json

        {
          "items": [
            {
              "instanceId": {
                "space": "my_space",
                "externalId": "my-document.pdf"
              }
            }
          ]
        }
        ```
      </Tab>

      <Tab title="Asset-centric (externalId)">
        ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        POST /api/v1/projects/my-project/files/downloadlink
        Content-Type: application/json

        {
          "items": [
            {
              "externalId": "my-document.pdf"
            }
          ]
        }
        ```
      </Tab>

      <Tab title="Asset-centric (id)">
        ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        POST /api/v1/projects/my-project/files/downloadlink
        Content-Type: application/json

        {
          "items": [
            {
              "id": 123456789
            }
          ]
        }
        ```
      </Tab>
    </Tabs>

    The response includes a temporary `downloadUrl`:

    ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
      "items": [
        {
          "downloadUrl": "https://download.cognitedata.com/...",
          "instanceId": {
            "space": "my_space",
            "externalId": "my-document.pdf"
          }
        }
      ]
    }
    ```
  </Step>

  <Step title="Download the file content">
    Use the `downloadUrl` to retrieve the file with a `GET` request. The download URL is valid for 30 minutes.

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    GET https://download.cognitedata.com/...
    ```

    <Check>
      The response contains the file content with the appropriate Content-Type header.
    </Check>
  </Step>
</Steps>

## File icons

You can retrieve an icon or thumbnail for a file using the file icon endpoint. This works with both identification methods:

<Tabs>
  <Tab title="Data modeling (instanceId)">
    ```
    GET /api/v1/projects/my-project/files/icon?instanceId={"space":"my_space","externalId":"my-image.png"}
    ```
  </Tab>

  <Tab title="Asset-centric (id)">
    ```
    GET /api/v1/projects/my-project/files/icon?id=123456789
    ```
  </Tab>
</Tabs>

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