openapi: 3.1.0
info:
title: Cognite 3D Asset Mapping Data products 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: Data products
description: "Data products are governed, ready-for-consumption data assets derived from data domains, following data mesh principles.\n\n **Key characteristics:**\n - **Clear ownership**: Defined data product owners with explicit access roles and accountability\n - **Rich metadata**: Comprehensive data modeling views, usage terms, access permissions, and descriptive documentation\n - **Self-service consumption**: Discoverable and well-documented for autonomous data consumer access\n - **Version management**: Immutable data modeling view versions with governed schemas and updatable metadata\n\n Data products act as a governance layer around data modeling, establishing trust and reliability for business decisions through clear ownership, comprehensive metadata, and standardized access patterns.\n\n **Space ownership**: A data product owns a schema space. The data modeling views that the data product governs live in that schema space. The schema space is exclusively owned by the data product.\n"
paths:
/dataproducts:
post:
tags:
- Data products
operationId: createDataProduct
summary: Create a data product
description: '
> **Required capabilities:** `dataProductsAcl:CREATE`
Creates a new data product. Maximum 100 data products allowed per project. Request body must contain an ''items'' array with up to 1 data product definition per request.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DataProductCreateRequest'
responses:
'201':
description: The created data product (as a single-item list).
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/DataProduct'
'400':
$ref: '#/components/responses/400ErrorResponse'
x-capability:
- dataProductsAcl:CREATE
get:
tags:
- Data products
operationId: listDataProducts
summary: List data products
description: '
> **Required capabilities:** `dataProductsAcl:READ`
List all data products, with pagination.'
parameters:
- $ref: '#/components/parameters/Cursor'
- in: query
name: limit
schema:
type: integer
format: int32
default: 10
minimum: 1
maximum: 100
description: Maximum number of data products to be returned. The maximum results returned by the server is 100 even if you specify a higher limit. The API may return fewer results than the specified limit. Only if a `nextCursor` is returned in the response are there more results to fetch.
responses:
'200':
description: A list of data products.
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/DataProduct'
nextCursor:
type: string
description: Cursor for the next page of results. If not present, there are no more results.
'400':
$ref: '#/components/responses/400ErrorResponse'
x-capability:
- dataProductsAcl:READ
/dataproducts/{externalId}:
get:
tags:
- Data products
operationId: getDataProduct
summary: Get a data product
description: '
> **Required capabilities:** `dataProductsAcl:READ`
Retrieves a specific data product by its external identifier.'
parameters:
- $ref: '#/components/parameters/dataProductExternalId'
responses:
'200':
description: The data product.
content:
application/json:
schema:
$ref: '#/components/schemas/DataProduct'
'404':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- dataProductsAcl:READ
/dataproducts/delete:
post:
tags:
- Data products
operationId: deleteDataProduct
summary: Delete a data product
description: '
> **Required capabilities:** `dataProductsAcl:DELETE`
Permanently removes a data product. A data product can not be deleted if it contains versions. This operation cannot be undone.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DataProductDeleteRequest'
responses:
'200':
description: The data product was successfully deleted.
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/400ErrorResponse'
'404':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- dataProductsAcl:DELETE
/dataproducts/update:
post:
tags:
- Data products
operationId: updateDataProduct
summary: Update a data product
description: '
> **Required capabilities:** `dataProductsAcl:UPDATE`
Update the attributes of a data product. Fields that aren''t included in the request aren''t changed.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DataProductUpdateRequest'
responses:
'200':
description: The updated data product (as a single-item list).
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/DataProduct'
'400':
$ref: '#/components/responses/400ErrorResponse'
'404':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- dataProductsAcl:UPDATE
/dataproducts/{externalId}/versions:
post:
tags:
- Data products
operationId: createDataProductVersion
summary: Create a data product version
description: '
> **Required capabilities:** `dataProductsAcl:UPDATE`
Creates a new data product version that references a collection of data modeling views. Once created, view references cannot be removed or modified, but view references can be added, and other properties can be updated.
A data product can have up to 10 versions.
The request body must contain an `items` array with exactly one data product version definition.'
parameters:
- $ref: '#/components/parameters/dataProductExternalId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DataProductVersionCreateRequest'
responses:
'201':
description: The created data product version (as a single-item list).
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/DataProductVersion'
'400':
$ref: '#/components/responses/400ErrorResponse'
'404':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- dataProductsAcl:UPDATE
get:
tags:
- Data products
operationId: listDataProductVersions
summary: List data product versions
description: '
> **Required capabilities:** `dataProductsAcl:READ`
List all versions of a data product, with pagination.'
parameters:
- $ref: '#/components/parameters/dataProductExternalId'
- $ref: '#/components/parameters/Cursor'
- in: query
name: limit
schema:
type: integer
format: int32
default: 10
minimum: 1
maximum: 10
description: Maximum number of data product versions to be returned. The maximum results returned by the server is 10 even if you specify a higher limit. The API may return fewer results than the specified limit. Only if a `nextCursor` is returned in the response are there more results to fetch.
responses:
'200':
description: All versions of a data product.
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/DataProductVersion'
nextCursor:
type: string
description: Cursor for the next page of results. If not present, there are no more results.
'404':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- dataProductsAcl:READ
/dataproducts/{externalId}/versions/{version}:
get:
tags:
- Data products
operationId: getDataProductVersion
summary: Get a data product version
description: '
> **Required capabilities:** `dataProductsAcl:READ`
Retrieves a specific version of a data product by its semantic version.'
parameters:
- $ref: '#/components/parameters/dataProductExternalId'
- in: path
name: version
required: true
schema:
allOf:
- $ref: '#/components/schemas/DataProductSemanticVersion'
- $ref: '#/components/schemas/DataProductSemanticVersionCompactDescription'
description: The semantic version of the data product version to retrieve.
responses:
'200':
description: The requested data product version.
content:
application/json:
schema:
$ref: '#/components/schemas/DataProductVersion'
'404':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- dataProductsAcl:READ
/dataproducts/{externalId}/versions/delete:
post:
tags:
- Data products
operationId: deleteDataProductVersions
summary: Delete data product versions
description: '
> **Required capabilities:** `dataProductsAcl:UPDATE`
Deletes one or more versions of a data product. Accepts a list of semantic versions. This operation cannot be undone.
'
parameters:
- $ref: '#/components/parameters/dataProductExternalId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DataProductVersionDeleteRequest'
responses:
'200':
description: The data product versions were successfully deleted.
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/400ErrorResponse'
'404':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- dataProductsAcl:UPDATE
/dataproducts/{externalId}/versions/update:
post:
tags:
- Data products
operationId: updateDataProductVersion
summary: Update data product version
description: '
> **Required capabilities:** `dataProductsAcl:UPDATE`
Update the attributes of a data product version. Fields that aren''t included in the request aren''t changed.
'
parameters:
- $ref: '#/components/parameters/dataProductExternalId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DataProductVersionUpdateRequest'
responses:
'200':
description: The updated data product version (as a single-item list).
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/DataProductVersion'
'400':
$ref: '#/components/responses/400ErrorResponse'
'404':
$ref: '#/components/responses/ErrorResponse'
x-capability:
- dataProductsAcl:UPDATE
components:
schemas:
SetStringField:
type: object
title: set
required:
- set
properties:
set:
type: string
ArrayPatchStringAddOrRemove:
title: add/remove
type: object
properties:
add:
uniqueItems: true
type: array
items:
type: string
remove:
uniqueItems: true
type: array
items:
type: string
DataProductSemanticVersion:
type: string
example: 1.2.34
pattern: ^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,3})$
minLength: 5
maxLength: 14
DataProductPatch:
type: object
description: Changes to apply to a data product
properties:
name:
$ref: '#/components/schemas/SetStringField'
description:
$ref: '#/components/schemas/SinglePatchString'
isGoverned:
$ref: '#/components/schemas/SinglePatchBoolean'
tags:
$ref: '#/components/schemas/ArrayPatchString'
DataProduct:
type: object
required:
- externalId
- name
- schemaSpace
- isGoverned
- domains
- tags
- createdTime
- lastUpdatedTime
properties:
externalId:
$ref: '#/components/schemas/DataProductExternalId'
name:
type: string
description: Human-readable name of the data product.
minLength: 1
maxLength: 50
schemaSpace:
allOf:
- $ref: '#/components/schemas/Space'
- readOnly: true
description: 'The schema space where the data product''s data modeling views are located. This space is exclusively owned by this data product.
'
description:
type: string
description: A description of the data product.
maxLength: 200
isGoverned:
type: boolean
description: Indicates whether the data product follows governance policies and standards. Note that this property is currently only informational.
tags:
type: array
items:
type: string
minLength: 1
maxLength: 20
description: A list of distinct tags for categorization and filtering.
minItems: 0
maxItems: 10
uniqueItems: true
domains:
type: array
readOnly: true
uniqueItems: true
items:
type: string
description: External ID of a data domain.
description: List of data domain external IDs that this data product is derived from. This field will be empty while the data domains feature is in development.
createdTime:
allOf:
- $ref: '#/components/schemas/EpochTimestamp'
readOnly: true
lastUpdatedTime:
allOf:
- $ref: '#/components/schemas/EpochTimestamp'
readOnly: true
ViewExternalId:
type: string
pattern: ^[a-zA-Z]([a-zA-Z0-9_]{0,253}[a-zA-Z0-9])?$
minLength: 1
maxLength: 255
description: The external ID of the view.
DataProductExternalId:
type: string
description: Data product external identifier
pattern: ^[a-z]([a-z0-9_-]{0,98}[a-z0-9])?$
minLength: 1
maxLength: 100
DataProductUpdateRequest:
type: object
required:
- items
properties:
items:
type: array
minItems: 1
maxItems: 1
items:
$ref: '#/components/schemas/DataProductChange'
description: List of data products to update.
ArrayPatchStringSet:
title: set
type: object
required:
- set
properties:
set:
uniqueItems: true
type: array
items:
type: string
DataProductChange:
type: object
required:
- externalId
- update
properties:
externalId:
$ref: '#/components/schemas/DataProductExternalId'
update:
$ref: '#/components/schemas/DataProductPatch'
Error:
type: object
required:
- code
- message
description: Cognite API error.
properties:
code:
type: integer
description: HTTP status code.
format: int32
example: 401
message:
type: string
description: Error message.
example: Could not authenticate.
missing:
type: array
description: List of lookup objects that do not match any results.
items:
type: object
additionalProperties: true
duplicated:
type: array
description: List of objects that are not unique.
items:
type: object
additionalProperties: true
DataProductVersionChange:
type: object
required:
- version
- update
properties:
version:
allOf:
- $ref: '#/components/schemas/DataProductSemanticVersion'
- description: The semantic version of the data product version to update.
update:
$ref: '#/components/schemas/DataProductVersionPatch'
DataProductVersionCreateRequest:
type: object
required:
- items
properties:
items:
type: array
minItems: 1
maxItems: 1
items:
$ref: '#/components/schemas/DataProductVersionCreate'
description: Array of data product versions to create.
DataProductVersion:
type: object
description: 'A version of a data product, with a collection of data modeling view references. Each item of the collection is immutable (it may not be modified or removed later), but items may be added later.
A data product can have up to 10 versions.
'
required:
- version
- views
- status
- terms
- createdTime
- lastUpdatedTime
properties:
version:
allOf:
- $ref: '#/components/schemas/DataProductSemanticVersion'
- $ref: '#/components/schemas/DataProductSemanticVersionExtendedDescription'
- readOnly: true
views:
type: array
minItems: 0
maxItems: 100
uniqueItems: true
description: 'A collection of references to views (with versions) that are associated with this data product version. Each item of the collection is immutable (it may not be modified or removed later), but items may be added later.
'
items:
type: object
required:
- space
- externalId
- version
properties:
space:
allOf:
- $ref: '#/components/schemas/Space'
- description: The space where the view is located.
externalId:
$ref: '#/components/schemas/ViewExternalId'
version:
type: string
description: The version of the view.
status:
$ref: '#/components/schemas/DataProductVersionStatus'
description:
type: string
description: A detailed description of this specific version of the data product. The text will be interpreted as markdown.
format: markdown
maxLength: 2000
terms:
type: object
description: Terms and conditions for using this data product version.
properties:
usage:
type: string
format: markdown
description: Permitted usage terms and conditions. The text will be interpreted as markdown.
maxLength: 2000
limitations:
type: string
format: markdown
description: Usage limitations and restrictions. The text will be interpreted as markdown.
maxLength: 500
createdTime:
allOf:
- $ref: '#/components/schemas/EpochTimestamp'
readOnly: true
lastUpdatedTime:
allOf:
- $ref: '#/components/schemas/EpochTimestamp'
readOnly: true
EpochTimestamp:
description: The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
type: integer
minimum: 0
format: int64
example: 1730204346000
DataProductDeleteRequest:
type: object
required:
- items
properties:
items:
type: array
uniqueItems: true
maxItems: 1
minItems: 1
description: List of ID objects
items:
type: object
required:
- externalId
properties:
externalId:
$ref: '#/components/schemas/DataProductExternalId'
DataProductCreateRequest:
type: object
required:
- items
properties:
items:
type: array
minItems: 1
maxItems: 1
items:
$ref: '#/components/schemas/DataProductCreate'
description: Array of data products to create.
DataProductSemanticVersionCompactDescription:
description: 'A semantic version number. We currently use a simplified version of what is described at [semver.org](https://semver.org/).
'
DataProductVersionTermsPatch:
title: modify
type: object
properties:
modify:
type: object
description: Modify terms fields
properties:
usage:
$ref: '#/components/schemas/SinglePatchString'
limitations:
$ref: '#/components/schemas/SinglePatchString'
description: Modify nested terms object fields.
ArrayPatchString:
type: object
oneOf:
- $ref: '#/components/schemas/ArrayPatchStringSet'
- $ref: '#/components/schemas/ArrayPatchStringAddOrRemove'
description: Change that will be applied to the array.
RemoveField:
title: remove
type: object
required:
- setNull
properties:
setNull:
type: boolean
example: true
DataProductVersionPatch:
type: object
description: Changes to apply to a data product version
properties:
status:
$ref: '#/components/schemas/SinglePatchDataProductVersionStatus'
description:
$ref: '#/components/schemas/SinglePatchString'
terms:
$ref: '#/components/schemas/DataProductVersionTermsPatch'
views:
$ref: '#/components/schemas/DataProductVersionViewsAdd'
DataProductCreate:
type: object
required:
- externalId
- name
properties:
externalId:
$ref: '#/components/schemas/DataProductExternalId'
name:
type: string
description: Human-readable name of the data product.
minLength: 1
maxLength: 50
schemaSpace:
allOf:
- $ref: '#/components/schemas/Space'
- description: 'The schema space where the data product''s data modeling views will be located.
This space will be exclusively owned by this data product.
If this field is specified, and the space does not exist or is already owned by another data product, the creation of the data product will fail.
If this field is not specified, this data product will claim ownership of the space whose name is equal to the `externalId` of the data product. If such a space does not exist or is already owned by another data product, the creation of the data product will fail.
'
description:
type: string
description: A description of the data product.
maxLength: 200
isGoverned:
type: boolean
default: false
description: Indicates whether the data product follows governance policies and standards. Note that this property is currently only informational.
tags:
type: array
items:
type: string
minLength: 1
maxLength: 20
description: A list of distinct tags for categorization and filtering. If the list contains duplicates, only one occurrence will be kept. The order of tags is not guaranteed to be preserved.
minItems: 0
maxItems: 10
uniqueItems: true
DataProductVersionCreate:
type: object
description: 'A new version of a data product, with a collection of data modeling view references. Each item of the collection is immutable (it may not be modified or removed later), but items may be added later.
A data product can have up to 10 versions.
'
required:
- version
- views
properties:
version:
allOf:
- $ref: '#/components/schemas/DataProductSemanticVersion'
- $ref: '#/components/schemas/DataProductSemanticVersionExtendedDescription'
views:
type: array
minItems: 0
maxItems: 100
uniqueItems: true
description: A collection of references to views (with versions) that will be associated with this data product version. The views must either reside in the schema space of the associated data product, or in a system space (one that begins with `cdf_`). The referenced views must already exist at the time of creation of this data product version. Each item of the collection is immutable (it may not be modified or removed later), but items may be added later.
items:
type: object
required:
- space
- externalId
- version
prop
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cognite/refs/heads/main/openapi/cognite-data-products-api-openapi.yml