{ "opencollection": "1.0.0", "info": { "name": "Cognite 3D Asset Mapping Files API", "version": "v1" }, "request": { "auth": { "type": "bearer", "token": "{{bearerToken}}" } }, "items": [ { "info": { "name": "Files", "type": "folder" }, "items": [ { "info": { "name": "List files", "type": "http" }, "http": { "method": "GET", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files", "params": [ { "name": "limit", "value": "", "type": "query", "description": "Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit." }, { "name": "cursor", "value": "", "type": "query", "description": "Cursor for paging through results. In general, if a response contains a `nextCursor`\nproperty, it means that there may be more results, and you should pass that value as the\n`cursor` parameter in the next request.\n\nNote that the cursor may or may not be encrypted, but either way, it is not intended to be\ndecoded. Its internal structure is not a part of the public API, and may change without\nnotice. You should treat it as an opaque string and not attempt to craft your own cursors.\n" }, { "name": "name", "value": "", "type": "query" }, { "name": "mimeType", "value": "", "type": "query" }, { "name": "source", "value": "", "type": "query" }, { "name": "assetIds", "value": "", "type": "query" }, { "name": "assetExternalIds", "value": "[\"externalId1\", \"externalId2\", \"externalId3\"]", "type": "query", "description": "Asset external IDs of related equipment that this file relates to. Takes 1..100 unique items." }, { "name": "dataSetIds", "value": "", "type": "query" }, { "name": "rootAssetIds", "value": "[363848954441724, 793045462540095, 1261042166839739]", "type": "query", "description": "Only include files that have a related asset in a tree rooted at any of these root assetIds." }, { "name": "assetSubtreeIds", "value": "[363848954441724, 793045462540095, 1261042166839739]", "type": "query", "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." }, { "name": "assetSubtreeExternalIds", "value": "[\"externalId1\", \"externalId2\", \"externalId3\"]", "type": "query", "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." }, { "name": "minCreatedTime", "value": "", "type": "query" }, { "name": "maxCreatedTime", "value": "", "type": "query" }, { "name": "minLastUpdatedTime", "value": "", "type": "query" }, { "name": "maxLastUpdatedTime", "value": "", "type": "query" }, { "name": "minUploadedTime", "value": "", "type": "query" }, { "name": "maxUploadedTime", "value": "", "type": "query" }, { "name": "minSourceCreatedTime", "value": "", "type": "query", "description": "Include files that have sourceCreatedTime set and with minimum this value." }, { "name": "maxSourceCreatedTime", "value": "", "type": "query", "description": "Include files that have sourceCreatedTime set and with maximum this value." }, { "name": "minSourceModifiedTime", "value": "", "type": "query", "description": "Include files that have sourceModifiedTime set and with minimum this value." }, { "name": "maxSourceModifiedTime", "value": "", "type": "query", "description": "Include files that have sourceModifiedTime set and with maximum this value." }, { "name": "externalIdPrefix", "value": "", "type": "query" }, { "name": "uploaded", "value": "true", "type": "query", "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." }, { "name": "partition", "value": "", "type": "query", "description": "Splits the data set into `N` partitions.\nThe attribute is specified as a \"M/N\" string, where `M` is a natural number in the interval of `[1, N]`.\nYou need to follow the cursors within each partition in order to receive all the data.\n\nThe maximum number of allowed partitions (`N`) is 10.\n\nCognite rejects requests if you specify more than 10 partitions.\nWhen Cognite enforces this behavior, the requests result in a 400 Bad Request status.\n" } ] }, "docs": "\n\n> **Required capabilities:** `filesAcl:READ`\n\nThe GET /files operation can be used to return information for all files in a project.\n\nOptionally you can add one or more of the following query parameters.\nThe filter query parameters will filter the results to only include files that match all filter parameters.\n\n### Request throttling\nThis endpoint is intended for data analytics and exploration purposes. It is not designed to support high-throughput data retrieval.\nPlease note that this endpoin" }, { "info": { "name": "Upload file", "type": "http" }, "http": { "method": "POST", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files", "headers": [ { "name": "Origin", "value": "" } ], "params": [ { "name": "overwrite", "value": "", "type": "query", "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.\n\nIf metadata is included in the request body, all of the original metadata will be overwritten.\nThe actual file will be overwritten after a successful upload with the uploadUrl from the response.\nIf there is no successful upload, the current file contents will be kept.\n\nFile-Asset mappings only change if explicitly stated in the assetIds field of the POST json body.\nDo not set assetIds in request body if you want to keep the current file-asset mappings." } ], "body": { "type": "json", "data": "{}" } }, "docs": "\n\n> **Required capabilities:** `filesAcl:WRITE`\n\nCreate metadata information and get an uploadUrl for a file.\n\nTo upload the file, send an HTTP PUT request to the uploadUrl from the response, with the relevant 'Content-Type' and 'Content-Length' headers.\n\nIf the uploadUrl contains the string '/v1/files/gcs_proxy/', you can make a Google Cloud Storage (GCS) resumable upload request\nas documented in https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload.\n\nThe uploadUrl expires " }, { "info": { "name": "Upload multipart file", "type": "http" }, "http": { "method": "POST", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/initmultipartupload", "params": [ { "name": "overwrite", "value": "", "type": "query", "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.\n\nIf metadata is included in the request body, all of the original metadata will be overwritten.\nThe actual file will be overwritten after a successful upload with the uploadUrls from the response.\nIf there is no successful upload, the current file contents will be kept.\n\nFile-Asset mappings only change if explicitly stated in the assetIds field of the POST json body.\nDo not set assetIds in request body if you want to keep the current file-asset mappings." }, { "name": "parts", "value": "", "type": "query", "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." } ], "body": { "type": "json", "data": "{}" } }, "docs": "\n\n> **Required capabilities:** `filesAcl:WRITE`\n\nMultipart file upload enables upload of files larger than 5000 MB, using a uniform API on all cloud environments for CDF.\n\nEach 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.\nThe supported maximum size for each file uploaded with the multi-part upload API is therefore 1000 GiB (1.073 TB / 0.976 TiB).\nThe client should calculat" }, { "info": { "name": "Get upload file link", "type": "http" }, "http": { "method": "POST", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/uploadlink", "headers": [ { "name": "Origin", "value": "" } ], "body": { "type": "json", "data": "{}" } }, "docs": "\n\n> **Required capabilities:** `filesAcl:WRITE`\n>\n> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:WRITE`\n\nGet an uploadUrl for a file.\n\nTo upload the file, send an HTTP PUT request to the uploadUrl from the response, with the relevant 'Content-Type' and 'Content-Length' headers.\n\nIf the uploadUrl contains the string '/v1/files/gcs_proxy/', you can make a Google Cloud Storage (GCS) resumable upload request\nas documented in https://cloud.google.com/storage/docs/json" }, { "info": { "name": "Get multipart file upload link", "type": "http" }, "http": { "method": "POST", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/multiuploadlink", "params": [ { "name": "parts", "value": "", "type": "query", "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." } ], "body": { "type": "json", "data": "{}" } }, "docs": "\n\n> **Required capabilities:** `filesAcl:WRITE`\n>\n> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:WRITE`\n\nMultipart file upload enables upload of files larger than 5000 MB, using a uniform API on all cloud environments for CDF.\n\nEach 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.\nThe supported maximum size for each file uploaded with the multi" }, { "info": { "name": "Retrieve a file by its ID", "type": "http" }, "http": { "method": "GET", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/:id", "params": [ { "name": "id", "value": "", "type": "path" } ] }, "docs": "\n\n> **Required capabilities:** `filesAcl:READ`\n>\n> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:READ`\n\nReturns file info for the file ID\n\n### Request throttling\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../)." }, { "info": { "name": "Filter files", "type": "http" }, "http": { "method": "POST", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/list", "body": { "type": "json", "data": "{}" } }, "docs": "\n\n> **Required capabilities:** `filesAcl:READ`\n\nRetrieves a list of all files in a project. Criteria can be supplied to\nselect a subset of files. This operation supports pagination with cursors.\n\n### Request throttling\nThis endpoint is intended for data analytics and exploration purposes. It is not designed to support high-throughput data retrieval.\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details," }, { "info": { "name": "Retrieve files", "type": "http" }, "http": { "method": "POST", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/byids", "body": { "type": "json", "data": "{}" } }, "docs": "\n\n> **Required capabilities:** `filesAcl:READ`\n>\n> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:READ`\n\nRetrieves metadata information about multiple specific files in the same project.\nResults are returned in the same order as in the request. This operation does not return the file contents.\n\n### Request throttling\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, p" }, { "info": { "name": "Search files", "type": "http" }, "http": { "method": "POST", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/search", "body": { "type": "json", "data": "{}" } }, "docs": "\n\n> **Required capabilities:** `filesAcl:READ`\n\nSearch for files based on relevance.\nYou can also supply a strict match filter as in Filter files, and search in the results from the filter.\nReturns first 1000 results based on relevance. This operation does not support pagination.\n\n### Request throttling\nThis endpoint is intended for data analytics and exploration purposes. It is not designed to support high-throughput data retrieval.\nPlease note that this endpoint is subject to the new throttlin" }, { "info": { "name": "Delete files", "type": "http" }, "http": { "method": "POST", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/delete", "body": { "type": "json", "data": "{}" } }, "docs": "\n\n> **Required capabilities:** `filesAcl:WRITE`\n\nDeletes the files with the given ids.\n\nA maximum of 1000 files can be deleted per request.\n\n### Request throttling\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resource documentation](../../)." }, { "info": { "name": "Download files", "type": "http" }, "http": { "method": "POST", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/downloadlink", "params": [ { "name": "extendedExpiration", "value": "", "type": "query" } ], "body": { "type": "json", "data": "{}" } }, "docs": "\n\n> **Required capabilities:** `filesAcl:READ`\n>\n> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:READ`\n\nRetrieves a list of download URLs for the specified list of file IDs.\nAfter getting the download links, the client has to issue a GET request to the returned URLs,\nwhich will respond with the contents of the file. The links will by default expire after 30 seconds.\nIf providing the query parameter extendedExpiration the links will expire after 1 hour.\n\n### Reques" }, { "info": { "name": "Get icon", "type": "http" }, "http": { "method": "GET", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/icon", "params": [ { "name": "id", "value": "", "type": "query" }, { "name": "externalId", "value": "", "type": "query" }, { "name": "space", "value": "", "type": "query" }, { "name": "instanceExternalId", "value": "", "type": "query" } ] }, "docs": "\n\n> **Required capabilities:** `filesAcl:READ`\n>\n> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:READ`\n\nThe GET /files/icon operation can be used to get an image representation of a file.\n\nEither id or externalId must be provided as a query parameter (but not both).\nSupported file formats:\n- Normal jpeg and png files are currently fully supported.\n- Other image file formats might work, but continued support for these are not guaranteed.\n- Currently only supporting" }, { "info": { "name": "Update files", "type": "http" }, "http": { "method": "POST", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/update", "body": { "type": "json", "data": "{}" } }, "docs": "\n\n> **Required capabilities:** `filesAcl:WRITE`\n\nUpdates the information for the files specified in the request body.\n\nIf you want to update the file content, uploaded using the uploadUrl, please\nuse the initFileUpload request with the query parameter 'overwrite=true'.\nAlternatively, delete and recreate the file.\n\nFor primitive fields (String, Long, Int), use 'set': 'value' to update\nvalue; use 'setNull': true to set that field to null.\n\nFor the Json Array field (e.g. assetIds and securityCatego" }, { "info": { "name": "Aggregate files", "type": "http" }, "http": { "method": "POST", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/aggregate", "body": { "type": "json", "data": "{}" } }, "docs": "\n\n> **Required capabilities:** `filesAcl:READ`\n\nCalculate aggregates for files, based on optional filter specification.\nReturns the following aggregates: `count`\n\n### Request throttling\nThis endpoint is intended for data analytics and exploration purposes. It is not designed to support high-throughput data retrieval.\nPlease note that this endpoint is subject to the new throttling policy, which imposes limits on both request rate and concurrency.\nFor more details, please refer to the [Files resou" }, { "info": { "name": "Complete multipart upload", "type": "http" }, "http": { "method": "POST", "url": "https://{cluster}.cognitedata.com/api/v1/projects/{project}/files/completemultipartupload", "body": { "type": "json", "data": "{}" } }, "docs": "\n\n> **Required capabilities:** `filesAcl:WRITE`\n>\n> Or `dataModelsAcl:READ` (scope spaceId: `cdf_cdm`) and `dataModelInstancesAcl:WRITE`\n\nCompletes a multipart file upload.\nThis endpoint must be called by the client when an 'initMultiPartUpload' operation (POST /files/initmultipartupload) was called,\nand all file content parts have been successfully uploaded using PUT for all upload URLs.\nEither `id` or `externalId` must be specified in the request body, but not both. The `uploadId` is also requ" } ] } ], "bundled": true }