openapi: 3.1.0
info:
title: Cognite 3D Asset Mapping Files API
description: "# Introduction\nThis is the reference documentation for the Cognite API with\nan overview of all the available methods.\n\n# Postman\nSelect the **Download** button to download our OpenAPI specification to get started.\n\nTo import your data into Postman, select **Import**, and the Import modal opens.\nYou can import items by dragging or dropping files or folders. You can choose how to import your API and manage the import settings in **View Import Settings**.\n\nIn the Import Settings, set the **Folder organization** to **Tags**, select\n**Enable optional parameters** to turn off the settings, and select **Always inherit authentication** to turn on the settings. Select **Import**.\n\nSet the Authorization to **Oauth2.0**. By default, the settings are for Open Industrial Data. Navigate to [Cognite Hub](https://hub.cognite.com/open-industrial-data-211) to understand how to get the credentials for use in Postman.\n\nFor more information, see [Getting Started with Postman](https://developer.cognite.com/dev/guides/postman/).\n\n# Pagination\nMost resource types can be paginated, indicated by the field `nextCursor` in the response.\nBy passing the value of `nextCursor` as the cursor you will get the next page of `limit` results.\nNote that all parameters except `cursor` has to stay the same.\n\n# Parallel retrieval\nAs general guidance, Parallel Retrieval is a technique that should be used when due to query complexity, retrieval of data in a single request is significantly slower than it would otherwise be for a simple request. Parallel retrieval does not act as a speed multiplier on optimally running queries. By parallelizing such requests, data retrieval performance can be tuned to meet the client application needs. \n\nCDF supports parallel retrieval through the `partition` parameter, which has the format `m/n` where `n` is the amount of partitions you would like to split the entire data set into.\nIf you want to download the entire data set by splitting it into 10 partitions, do the following in parallel with `m` running from 1 to 10:\n - Make a request to `/events` with `partition=m/10`.\n - Paginate through the response by following the cursor as explained above. Note that the `partition` parameter needs to be passed to all subqueries.\n\nProcessing of parallel retrieval requests is subject to concurrency quota availability. The request returns the `429` response upon exceeding concurrency limits. See the Request throttling chapter below.\n\nTo prevent unexpected problems and to maximize read throughput, you should at most use 10 partitions. \nSome CDF resources will automatically enforce a maximum of 10 partitions.\nFor more specific and detailed information, please read the ```partition``` attribute documentation for the CDF resource you're using. \n\n# Requests throttling\nCognite Data Fusion (CDF) returns the HTTP `429` (too many requests) response status code when project capacity exceeds the limit.\n\nThe throttling can happen:\n - If a user or a project sends too many (more than allocated) concurrent requests.\n - If a user or a project sends a too high (more than allocated) rate of requests in a given amount of time.\n\nCognite recommends using a retry strategy based on truncated exponential backoff to handle sessions with HTTP response codes 429.\n\nCognite recommends using a reasonable number (up to 10) of `Parallel retrieval` partitions.\n\nFollowing these strategies lets you slow down the request frequency to maximize productivity without having to re-submit/retry failing requests.\n\nSee more [here](https://docs.cognite.com/dev/concepts/resource_throttling).\n\n# API versions\n## Version headers\nThis API uses calendar versioning, and version names follow the `YYYYMMDD` format.\nYou can find the versions currently available by using the version selector at the top of this page.\n\nTo use a specific API version, you can pass the `cdf-version: $version` header along with your requests to the API.\n\n## Beta versions\nThe beta versions provide a preview of what the stable version will look like in the future.\nBeta versions contain functionality that is reasonably mature, and highly likely to become a part of the stable API.\n\nBeta versions are indicated by a `-beta` suffix after the version name. For example, the beta version header for the\n2023-01-01 version is then `cdf-version: 20230101-beta`.\n\n## Alpha versions\nAlpha versions contain functionality that is new and experimental, and not guaranteed to ever become a part of the stable API.\nThis functionality presents no guarantee of service, so its use is subject to caution.\n\nAlpha versions are indicated by an `-alpha` suffix after the version name. For example, the alpha version header for\nthe 2023-01-01 version is then `cdf-version: 20230101-alpha`."
version: v1
contact:
name: Cognite Support
url: https://support.cognite.com
email: support@cognite.com
servers:
- url: https://{cluster}.cognitedata.com/api/v1/projects/{project}
description: The URL for the CDF cluster to connect to
variables:
cluster:
enum:
- api
- az-tyo-gp-001
- az-eastus-1
- az-power-no-northeurope
- westeurope-1
- asia-northeast1-1
- gc-dsm-gp-001
default: api
description: The CDF cluster to connect to
project:
default: publicdata
description: The CDF project name.
security:
- oidc-token:
- https://{cluster}.cognitedata.com/.default
- oauth2-client-credentials:
- https://{cluster}.cognitedata.com/.default
- oauth2-open-industrial-data:
- https://api.cognitedata.com/.default
- oauth2-auth-code:
- https://{cluster}.cognitedata.com/.default
tags:
- name: Files
description: "A file stores a sequence of bytes connected to one or more assets. For\nexample, a file can contain a piping and instrumentation diagram (P&IDs)\nshowing how multiple assets are connected.\n\nEach file is identified by the 'id' field, which is generated internally\nfor each new file. Each file's 'id' field is unique within a project.\n\nThe 'externalId' field is optional, but can also be used to identify a file.\nThe 'externalId' (if used) must be unique within a project.\n\nFiles are created in two steps; First the metadata is stored in a file\nobject, and then the file contents are uploaded. This means that files can\nexist in a non-uploaded state. The upload state is reflected in the 'uploaded'\nfield in responses.\n\nAsset references obtained from a file - through asset ids - may be\ninvalid, simply by the non-transactional nature of HTTP.\nThey are maintained in an eventual consistent manner.\n\n## Rate and concurrency limits\n\nBoth the rate of requests (denoted as request per second, or â\x80\x98**rps**â\x80\x99) and the number of concurrent (parallel) requests are governed by limits,\nfor all CDF API endpoints. If a request exceeds one of the limits,\nit will be throttled with a `429: Too Many Requests` response. More on limit types\nand how to avoid being throttled is described\n[here](https://docs.cognite.com/dev/concepts/resource_throttling).\n\nLimits are defined at both the overall API service level, and on the API endpoints belonging to the service.\nSome types of requests consume more resources (compute, storage IO) than others, and where a service handles\nmultiple concurrent requests with varying resource consumption.\nFor example, â\x80\x98CRUDâ\x80\x99 type requests (**C**reate, **R**etrieve, **R**equest ByIDs, **U**pdate and **D**elete and similar) are far less resource\nintensive than â\x80\x98Analyticalâ\x80\x99 type requests (List, Search and Filter) and in addition, the most resource\nintensive Analytical endpoint of all, Aggregates, receives its own request budget within the overall Analytical request budget.\nThe version 1.0 limits for the overall API service and its constituent endpoints are illustrated in the diagram below.\nThese limits are subject to change, pending review of changing consumption patterns and resource availability over time:\n\n<img src=\"https://apps-cdn.cogniteapp.com/@cognite/docs-portal-images/1.0.0/images/api-docs/FilesLimitsFeb2023.png\" alt=\" \" width=\"80%\"/>\n\n### Translating RPS into data speed\nA single request may retrieve up to 1000 items. In the context of Files, 1 item = 1 file record\nTherefore, the maximum theoretical data speed at the top API service level is 160,000 items per second for all consumers,\nand 120,000 for a single identity or client in a project.\n\n### Use of Partitions / Parallel Retrieval\nAs a general guidance, Parallel Retrieval is a technique that should be used where due to query complexity, retrieval of data in a\nsingle request session turns out to be slow. By parallelizing such requests, data retrieval performance can be tuned to meet the\nclient application needs. Parallel retrieval may also be used where retrieval of large sets of data is required, up to the\ncapacity limits defined for a given API service. For example (using the Files API request budget):\n\n* A single request may retrieve up to 1000 items\n* Up to 23 requests per second may be issued for an analytical query (per identity), such as when using /list or /filter API endpoints\n* This provides a theoretical maximum of 23,000 items read per second per identity\n* The query complexity may result in it taking longer than 1s to read or write 1000 items in a single request\n* Therefore, it is appropriate to specify the query to retrieve a lower number of items per request, and retrieve more items in parallel, up to the theoretical maximum performance of 23,000 items per second.\n\n**Important Note:**\nParallel retrieval should be only used in situations where, due to query complexity,\na single request flow provides data retrieval speeds that are significantly less than the theoretical maximum.\nParallel retrieval does not act as a speed multiplier on optimally running queries. Regardless of the number\nof concurrent requests issued, the overall requests per second limit still applies.\nSo for example, a single request returning data at approximately 18,000 items per second will only\nbenefit from adding a second parallel request, the capacity of which goes somewhat wasted\nas only an additional 5,000 items per second will return before the request rate budget limit is reached."
paths:
/files:
post:
tags:
- Files
summary: Upload file
description: '
> **Required capabilities:** `filesAcl:WRITE`
Create metadata information and get an uploadUrl for a file.
To upload the file, send an HTTP PUT request to the uploadUrl from the response, with the relevant ''Content-Type'' and ''Content-Length'' headers.
If the uploadUrl contains the string ''/v1/files/gcs_proxy/'', you can make a Google Cloud Storage (GCS) resumable upload request
as documented in https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload.
The uploadUrl expires after one week.
Any file info entry that does not have the actual file uploaded within one week will be automatically deleted.
Note: The single part uploadUrl from initFileUpload supports uploading files up to 5000 MB (5,000,000,000 bytes) in size. For larger files than that, please use the multipart upload API.
The initMultiPartUpload and completeMultiPartUpload endpoints provides an alternative way to upload files, both small and large, up to 1000 GiB in size.
These endpoints exposes a uniform multipart upload API for all cloud vendor environments for CDF. Optionally parallel part uploads can be used, for faster uploads.
### Request throttling
This endpoint is subject to the new throttling policy, which enforces limits on both request rate and concurrency.
For more details, please refer to the [Files resource documentation](../../).'
operationId: initFileUpload
parameters:
- in: header
name: Origin
description: The 'Origin' header parameter is required if there is a Cross Origin issue.
schema:
type: string
- in: query
name: overwrite
schema:
type: boolean
default: false
description: '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 with the uploadUrl from the response.
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.'
requestBody:
description: Fields to be set for the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalFilesMetadata'
required: true
responses:
'201':
$ref: '#/components/responses/UploadFileMetadataResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- filesAcl:WRITE
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: 'const fileContent = ''file data here''; // can also be of type ArrayBuffer, Buffer, Blob, File or any
// automatic upload:
const file = await client.files.upload({name: ''examplefile.jpg'', mimeType: ''image/jpeg''}, fileContent);
// manual with uploadUrl:
const file2 = await client.files.upload({name: ''examplefile.jpg'', mimeType: ''image/jpeg''});
// then upload using the file.uploadUrl'
- lang: Python
label: Python SDK
source: 'res = client.files.upload("/path/to/file", name="my_file")
res = client.files.upload("/path/to/file")
res = client.files.upload("/path/to/my/directory")
from cognite.client.data_classes import Label
res = client.files.upload("/path/to/file", name="my_file", labels=[Label(external_id="WELL LOG")])
from cognite.client.data_classes import GeoLocation, Geometry
geometry = Geometry(type="LineString", coordinates=[[30, 10], [10, 30], [40, 40]])
res = client.files.upload("/path/to/file", geo_location=GeoLocation(type="Feature", geometry=geometry))
'
- lang: Java
label: Java SDK
source: "Path fileAOriginal = Paths.get(\"./src/test/resources/csv-data.txt\"); \nList<FileContainer> fileContainerInput = new ArrayList<>(); \nFileMetadata fileMetadata = FileMetadata.newBuilder() \n .setExternalId(\"10\") \n .setName(\"test_file_.test\") \n .setSource(\"sdk-data-generator\") \n .putMetadata(\"type\", \"sdk-data-generator\") \n .build(); \n\n FileContainer fileContainer = FileContainer.newBuilder() \n .setFileMetadata(fileMetadata) \n .setFileBinary(FileBinary.newBuilder() \n .setBinaryUri(fileAOriginal.toUri().toString())) \n .build(); \n fileContainerInput.add(fileContainer); \n\n List<FileMetadata> uploadFileResult = \n client.files().upload(fileContainerInput); \n\n"
get:
tags:
- Files
summary: List files
description: '
> **Required capabilities:** `filesAcl:READ`
The GET /files operation can be used to return information for all files in a project.
Optionally you can add one or more of the following query parameters.
The filter query parameters will filter the results to only include files that match all filter parameters.
### Request throttling
This endpoint is intended for data analytics and exploration purposes. It is not designed to support high-throughput data retrieval.
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](../../).'
operationId: listFiles
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Name'
- in: query
name: mimeType
schema:
$ref: '#/components/schemas/MimeType'
- in: query
name: source
schema:
$ref: '#/components/schemas/FileSource'
- in: query
name: assetIds
schema:
$ref: '#/components/schemas/AssetIds'
- in: query
name: assetExternalIds
description: Asset external IDs of related equipment that this file relates to. Takes 1..100 unique items.
example: '["externalId1", "externalId2", "externalId3"]'
schema:
$ref: '#/components/schemas/JsonArrayString'
- in: query
name: dataSetIds
schema:
$ref: '#/components/schemas/DataSetIdEithers'
- in: query
name: rootAssetIds
description: Only include files that have a related asset in a tree rooted at any of these root assetIds.
example: '[363848954441724, 793045462540095, 1261042166839739]'
schema:
$ref: '#/components/schemas/JsonArrayInt64'
- in: query
name: assetSubtreeIds
description: Only include files that have a related asset in a subtree rooted at any of these assetIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.
example: '[363848954441724, 793045462540095, 1261042166839739]'
schema:
$ref: '#/components/schemas/JsonArrayInt64'
- in: query
name: assetSubtreeExternalIds
description: Only include files that have a related asset in a subtree rooted at any of these assetExternalIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.
example: '["externalId1", "externalId2", "externalId3"]'
schema:
$ref: '#/components/schemas/JsonArrayString'
- in: query
name: minCreatedTime
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: maxCreatedTime
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: minLastUpdatedTime
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: maxLastUpdatedTime
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: minUploadedTime
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: maxUploadedTime
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: minSourceCreatedTime
description: Include files that have sourceCreatedTime set and with minimum this value.
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: maxSourceCreatedTime
description: Include files that have sourceCreatedTime set and with maximum this value.
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: minSourceModifiedTime
description: Include files that have sourceModifiedTime set and with minimum this value.
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: maxSourceModifiedTime
description: Include files that have sourceModifiedTime set and with maximum this value.
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: externalIdPrefix
schema:
$ref: '#/components/schemas/CogniteExternalIdPrefix'
style: form
explode: false
- in: query
name: uploaded
description: Whether or not the actual file is uploaded. This field is returned only by the API, it has no effect in a post body.
schema:
type: boolean
example: true
- $ref: '#/components/parameters/partitionLimited10'
responses:
'200':
$ref: '#/components/responses/FileMetadataWithCursorResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- filesAcl:READ
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: 'const files = await client.files.list({filter: {mimeType: ''image/png''}});'
- lang: Python
label: Python SDK
source: "file_list = client.files.list(limit=5, external_id_prefix=\"prefix\")\n\nfor file_metadata in client.files:\n file_metadata # do something with the file metadata\n\nfor file_list in client.files(chunk_size=2500):\n file_list # do something with the files\n\nfrom cognite.client.data_classes import LabelFilter\nmy_label_filter = LabelFilter(contains_all=[\"WELL LOG\", \"VERIFIED\"])\nfile_list = client.files.list(labels=my_label_filter)\n\nfrom cognite.client.data_classes import GeoLocationFilter, GeometryFilter\nmy_geo_location_filter = GeoLocationFilter(relation=\"intersects\", shape=GeometryFilter(type=\"Point\", coordinates=[35,10]))\nfile_list = client.files.list(geo_location=my_geo_location_filter)\n"
/files/initmultipartupload:
post:
tags:
- Files
summary: Upload multipart file
description: '
> **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.
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:
1. POST files/initmultipartupload?parts=8, to start a multipart upload session with 8 parts. Expect a 201 CREATED response code, and a response body with information to be used in the part uploads and completemultipartupload requests.
2. PUT `uploadUrl`, for each of the `uploadUrls` in the response from files/initmultipartupload. Expect a 200 OK or 201 CREATED response for each PUT request.
3. POST files/completemultipartupload, with request body ''{ "id":123456789, "uploadId":"ABCD4321EFGH" }''. This will assemble the file. 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](../../).'
operationId: initMultiPartUpload
parameters:
- in: query
name: overwrite
schema:
type: boolean
default: false
description: '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 with the uploadUrls from the response.
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.'
- in: query
name: parts
required: true
schema:
type: integer
format: int32
minimum: 1
maximum: 250
description: The 'parts' parameter specifies how many uploadURLs should be returned, for uploading the file contents in parts. See main endpoint description for more details.
requestBody:
description: Fields to be set for the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalFilesMetadata'
required: true
responses:
'201':
$ref: '#/components/responses/MultiPartUploadFileMetadataResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- filesAcl:WRITE
/files/uploadlink:
post:
tags:
- Files
summary: Get upload file link
description: '
> **Required capabilities:** `filesAcl:WRITE`
>
> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:WRITE`
Get an uploadUrl for a file.
To upload the file, send an HTTP PUT request to the uploadUrl from the response, with the relevant ''Content-Type'' and ''Content-Length'' headers.
If the uploadUrl contains the string ''/v1/files/gcs_proxy/'', you can make a Google Cloud Storage (GCS) resumable upload request
as documented in https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload.
The uploadUrl expires after one week.
Any file info entry that does not have the actual file uploaded within one week will be automatically deleted.
Note: The single part uploadUrl from getUploadLink only supports uploading files up to 5000 MB (5,000,000,000 bytes) in size.
The getMultiPartUploadLink and completeMultiPartUpload endpoints provides an alternative way to upload files, both small and large, up to 1000 GiB in size.
These endpoints exposes a uniform multipart upload API for all cloud vendor environments for CDF. Optionally parallel part uploads can be used, for faster uploads.
### 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](../../).'
operationId: getUploadLink
parameters:
- in: header
name: Origin
description: The 'Origin' header parameter is required if there is a Cross Origin issue.
schema:
type: string
requestBody:
description: Fields to be set for the file.
content:
application/json:
schema:
$ref: '#/components/schemas/FileDataUploadIds'
required: true
responses:
'201':
$ref: '#/components/responses/UploadFileMetadataResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- filesAcl:WRITE
x-cdm-capability:
- dataModelInstancesAcl:WRITE
/files/multiuploadlink:
post:
tags:
- Files
summary: Get multipart file upload link
description: '
> **Required capabilities:** `filesAcl:WRITE`
>
> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl: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 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.
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:
1. POST files/initmultipartupload?parts=8, to start a multipart upload session with 8 parts. Expect a 201 CREATED response code, and a response body with information to be used in the part uploads and completemultipartupload requests.
2. PUT `uploadUrl`, for each of the `uploadUrls` in the response from files/initmultipartupload. Expect a 200 OK or 201 CREATED response for each PUT request.
3. POST files/completemultipartupload, with request body ''{ "id":123456789, "uploadId":"ABCD4321EFGH" }''. This will assemble the file. 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](../../).'
operationId: getMultiPartUploadLink
parameters:
- in: query
name: parts
required: true
schema:
type: integer
format: int32
minimum: 1
maximum:
# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cognite/refs/heads/main/openapi/cognite-files-api-openapi.yml