Cognite Data models API
The Data models API from Cognite — 3 operation(s) for data models.
OpenAPI Specification
openapi: 3.1.0
info:
title: Cognite 3D Asset Mapping Data models 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 models
paths:
/models/datamodels:
post:
tags:
- Data models
summary: Create or update data models
description: '
> **Required capabilities:** `dataModelsAcl:WRITE`
Add or update (upsert) data models. For unchanged data model specifications, the operation completes without making any changes. We will not update the ```lastUpdatedTime``` value for models that remain unchanged.'
operationId: createDataModels
requestBody:
description: List of data models to add
content:
application/json:
schema:
$ref: '#/components/schemas/DataModelCreateCollection'
required: true
x-capability:
- dataModelsAcl:WRITE
responses:
'200':
$ref: '#/components/responses/DataModelCollectionResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
'409':
description: Data model conflict
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertConflict'
x-code-samples:
- lang: Python
label: Python SDK
source: "from cognite.client.data_classes.data_modeling import DataModelApply\ndata_models = [\n DataModelApply(space=\"mySpace\",external_id=\"myDataModel\",version=\"v1\"),\n DataModelApply(space=\"mySpace\",external_id=\"myOtherDataModel\",version=\"v1\")]\nres = client.data_modeling.data_models.apply(data_models)\n"
get:
tags:
- Data models
summary: List data models defined in the project
description: '
> **Required capabilities:** `dataModelsAcl:READ`
List data models defined in the project. You can filter the returned models by the specified space.'
operationId: listDataModels
parameters:
- $ref: '#/components/parameters/ReducedLimit'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/InlineViews'
- $ref: '#/components/parameters/Space'
- $ref: '#/components/parameters/AllVersions'
- $ref: '#/components/parameters/IncludeGlobal'
x-capability:
- dataModelsAcl:READ
responses:
'200':
$ref: '#/components/responses/DataModelCollectionResponseWithCursor'
'400':
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Python
label: Python SDK
source: "data_model_list = client.data_modeling.data_models.list(limit=5)\n\nfor data_model in client.data_modeling.data_models:\n data_model # do something with the data_model\n\nfor data_model_list in client.data_modeling.data_models(chunk_size=10):\n data_model_list # do something with the data model\n"
/models/datamodels/byids:
post:
tags:
- Data models
summary: Retrieve data models by their external ids
description: '
> **Required capabilities:** `dataModelsAcl:READ`
Retrieve up to 100 data models by their external ids. Views can be auto-expanded when the ```InlineViews``` query parameter is set.'
operationId: byExternalIdsDataModels
parameters:
- $ref: '#/components/parameters/InlineViews'
requestBody:
description: List of external-ids of data models to retrieve.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ListOfVersionReferences'
- $ref: '#/components/schemas/ListOfAllVersionsReferences'
required: true
x-capability:
- dataModelsAcl:READ
responses:
'200':
$ref: '#/components/responses/DataModelCollectionResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Python
label: Python SDK
source: 'res = client.data_modeling.data_models.retrieve(("mySpace", "myDataModel", "v1"))
'
/models/datamodels/delete:
post:
tags:
- Data models
summary: Delete data models
description: '
> **Required capabilities:** `dataModelsAcl:WRITE`
Delete one or more data models. Currently limited to 100 models at a time. This does not delete the views, nor the containers they reference.'
operationId: deleteDataModels
requestBody:
description: List of references to data models you wish to delete
content:
application/json:
schema:
$ref: '#/components/schemas/ListOfVersionReferences'
required: true
x-capability:
- dataModelsAcl:WRITE
responses:
'200':
$ref: '#/components/responses/VersionReferencesCollectionResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Python
label: Python SDK
source: 'client.data_modeling.data_models.delete(("mySpace", "myDataModel", "v1"))
'
components:
responses:
VersionReferencesCollectionResponse:
description: Items affected by the request
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
minItems: 1
maxItems: 100
items:
type: object
required:
- space
- externalId
- version
properties:
externalId:
description: External id for the requested item
allOf:
- $ref: '#/components/schemas/DMSExternalId'
space:
description: Space the requested item belongs to
allOf:
- $ref: '#/components/schemas/SpaceSpecification'
version:
description: Version of the requested item
allOf:
- $ref: '#/components/schemas/DMSVersion'
DataModelCollectionResponseWithCursor:
description: List of data models
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
description: List of data models
items:
$ref: '#/components/schemas/DataModel'
nextCursor:
$ref: '#/components/schemas/NextCursorV3'
ErrorResponse:
description: The response for a failed request.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/Error'
DataModelCollectionResponse:
description: List of data models
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
description: List of data models
items:
$ref: '#/components/schemas/DataModel'
schemas:
ReverseDirectRelationConnectionRead:
allOf:
- $ref: '#/components/schemas/ReverseDirectRelationConnection'
- type: object
required:
- targetsList
properties:
targetsList:
description: Whether or not this reverse direct relation targets a _list_ of direct relations.
type: boolean
UsedFor:
type: string
description: Should this operation apply to nodes, edges, records, or both nodes and edges. **NB!** Currently ```all``` applies to nodes and edges, but not records.
enum:
- node
- edge
- record
- all
default: node
DataModel:
allOf:
- $ref: '#/components/schemas/DataModelCore'
- type: object
required:
- createdTime
- lastUpdatedTime
- isGlobal
properties:
views:
type: array
description: 'List of views included in this data model. We can expand the views to use the full view definitions,
i.e. with all the dependent views.
Use the ```InlineViews``` query parameter to request expansion. If you do not set the
```InlineViews``` query parameter, we will return the references to views instead.
'
items:
$ref: '#/components/schemas/DataModelProperty'
createdTime:
$ref: '#/components/schemas/EpochTimestamp'
lastUpdatedTime:
$ref: '#/components/schemas/EpochTimestamp'
isGlobal:
description: Is this a global data model.
type: boolean
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
ListOfVersionReferences:
type: object
required:
- items
properties:
items:
type: array
minItems: 1
maxItems: 100
items:
type: object
required:
- space
- externalId
- version
properties:
externalId:
description: External id for the requested item
allOf:
- $ref: '#/components/schemas/DMSExternalId'
space:
description: Space id for the requested item
allOf:
- $ref: '#/components/schemas/SpaceSpecification'
version:
description: Version of the requested item
allOf:
- $ref: '#/components/schemas/DMSVersion'
DataModelCore:
type: object
required:
- space
- externalId
- version
properties:
space:
description: Id of the space that the data model belongs to
allOf:
- $ref: '#/components/schemas/SpaceSpecification'
externalId:
description: External id that uniquely identifies this data model
allOf:
- $ref: '#/components/schemas/DMSExternalId'
name:
type: string
description: Readable name meant for use in UIs
maxLength: 255
description:
type: string
description: Description of the content and intended use of the data model
maxLength: 1024
version:
description: Data model version (opaque string controlled by client applications)
allOf:
- $ref: '#/components/schemas/DMSVersion'
DMSExternalId:
type: string
pattern: ^[a-zA-Z]([a-zA-Z0-9_]{0,253}[a-zA-Z0-9])?$
minLength: 1
maxLength: 255
ViewDefinition:
allOf:
- type: object
required:
- externalId
properties:
externalId:
description: External id uniquely identifying this view
allOf:
- $ref: '#/components/schemas/DMSExternalId'
- $ref: '#/components/schemas/ViewCommon'
- type: object
required:
- createdTime
- lastUpdatedTime
- writable
- queryable
- properties
- usedFor
- isGlobal
- mappedContainers
properties:
createdTime:
$ref: '#/components/schemas/EpochTimestamp'
lastUpdatedTime:
$ref: '#/components/schemas/EpochTimestamp'
writable:
type: boolean
description: Does the view support write operations, i.e. is it ```writable```? You can write to a view if the view maps all non-nullable properties.
queryable:
type: boolean
description: Does the view support queries, i.e. is it queryable? You can query a view if it either has a filter or at least one property mapped to a container.
usedFor:
$ref: '#/components/schemas/UsedFor'
isGlobal:
type: boolean
description: Is this a global view.
properties:
type: object
description: List of properties and connections included in this view. The view identifier has to have a length of between 1 and 255 characters. It must also match the pattern ```^[a-zA-Z0-9][a-zA-Z0-9_-]{0,253}[a-zA-Z0-9]?$```.
additionalProperties:
x-additionalPropertiesName: view-property-identifier
allOf:
- $ref: '#/components/schemas/ViewDefinitionProperty'
mappedContainers:
type: array
description: List of containers with properties mapped by this view.
items:
$ref: '#/components/schemas/ContainerReference'
MatchAllFilter:
type: object
title: matchAll
required:
- matchAll
properties:
matchAll:
description: All the listed items must match the clause.
type: object
maxProperties: 0
DMSVersion:
type: string
pattern: ^[a-zA-Z0-9]([.a-zA-Z0-9_-]{0,41}[a-zA-Z0-9])?$
minLength: 1
maxLength: 43
NextCursorV3:
description: The cursor value used to return (paginate to) the next page of results, when more data is available.
type: string
ReverseDirectRelationConnection:
type: object
required:
- connectionType
- source
- through
description: Describes the direct relation(s) pointing to instances read through this view. This connection type is used to aid in discovery and documentation of the view.
properties:
connectionType:
type: string
description: The type of connection. The ```single_reverse_direct_relation``` type is used to indicate that only a single direct relation is expected to exist. The ```multi_reverse_direct_relation``` type is used to indicate that multiple direct relations are expected to exist.
enum:
- single_reverse_direct_relation
- multi_reverse_direct_relation
name:
type: string
description: Readable property name.
maxLength: 255
description:
type: string
description: Description of the content and suggested use for this property.
maxLength: 1024
source:
description: The node(s) containing the direct relation property can be read through the view specified in 'source'.
allOf:
- $ref: '#/components/schemas/ViewReference'
through:
description: The view or container of the node containing the direct relation property.
allOf:
- $ref: '#/components/schemas/ThroughReference'
EqualsFilterV3:
type: object
title: equals
required:
- equals
properties:
equals:
required:
- property
- value
description: Matches items that contain the exact value in the provided property.
type: object
properties:
property:
$ref: '#/components/schemas/DMSFilterProperty'
value:
$ref: '#/components/schemas/FilterValue'
EdgeConnection:
type: object
required:
- type
- source
description: Describes the edge(s) that are likely to exist to aid in discovery and documentation of the view. A listed edge is not required. i.e. It does not have to exist when included in this list. A connection has a max distance of one hop.
properties:
connectionType:
type: string
description: The type of connection, either a single or multi edge connections are expected to exist.
enum:
- single_edge_connection
- multi_edge_connection
default: multi_edge_connection
name:
type: string
description: Readable property name.
maxLength: 255
description:
type: string
description: Description of the content and suggested use for this property.
maxLength: 1024
type:
$ref: '#/components/schemas/DirectRelationReference'
source:
description: The target node(s) of this connection can be read through the view specified in 'source'.
allOf:
- $ref: '#/components/schemas/ViewReference'
edgeSource:
description: The edge(s) of this connection can be read through the view specified in 'edgeSource'.
allOf:
- $ref: '#/components/schemas/ViewReference'
direction:
type: string
enum:
- outwards
- inwards
default: outwards
CDFExternalIdReference:
type: object
description: 'An external-id reference to an existing CDF resource type item, such as a time series.
An example could be that for an existing time series stored in the CDF time series resource type with the
external-id 21PT0293, then the value would be set to "21PT029", and the type would be set to "timeseries". There
are no referential integrity guarantees for this, and the client should handle if the time series has been removed
or the client may not have access to it.
Currently, time series, sequence and file references are supported.
CDF external ID reference types (timeseries, file, sequence) are not allowed for containers with ```usedFor``` set to ```record```.
'
required:
- type
properties:
type:
type: string
enum:
- timeseries
- file
- sequence
list:
description: 'Specifies that the data type is a list of values. The ordering of values is preserved.
'
type: boolean
default: false
maxListSize:
type: integer
description: Specifies the maximum number of values in the list
ViewReference:
type: object
description: Reference to a view
required:
- type
- space
- externalId
- version
properties:
type:
type: string
enum:
- view
space:
description: Id of the space that the view belongs to
allOf:
- $ref: '#/components/schemas/SpaceSpecification'
externalId:
description: External-id of the view
allOf:
- $ref: '#/components/schemas/DMSExternalId'
version:
description: Version of the view
allOf:
- $ref: '#/components/schemas/DMSVersion'
PrimitiveProperty:
type: object
description: 'Primitive types for the property.
We expect dates to be in the ISO-8601 format, while timestamps are expected to be an epoch value with
millisecond precision. JSON values have to be valid JSON fragments. The maximum allowed size for a JSON
object is 40960 bytes. For list of json values, the size of the entire list must be within this limit.
The maximum allowed length of a key is 128, while the maximum allowed size of a value is 10240 bytes
and you can have up to 256 key-value pairs.
'
required:
- type
properties:
type:
type: string
enum:
- boolean
- float32
- float64
- int32
- int64
- timestamp
- date
- json
unit:
type: object
description: 'The unit of the data stored in this property, can only be assign to type float32 or float64.
ExternalId needs to match with a unit in the Cognite unit catalog.
'
required:
- externalId
example: 'externalId: temperature:deg_c, sourceUnit: Celsius
'
properties:
externalId:
$ref: '#/components/schemas/NodeOrEdgeExternalId'
sourceUnit:
type: string
list:
description: 'Specifies that the data type is a list of values. The ordering of values is preserved.
'
type: boolean
default: false
maxListSize:
type: integer
description: Specifies the maximum number of values in the list
FilterValueRange:
oneOf:
- $ref: '#/components/schemas/RangeValue'
- $ref: '#/components/schemas/ReferencedPropertyValueV3'
ReferencedPropertyValueV3:
title: property reference
description: A property reference value
type: object
required:
- property
properties:
property:
type: array
items:
type: string
minItems: 2
maxItems: 4
ViewCreateDefinitionProperty:
description: 'A reference to a container property or a connection describing edges that are expected to
exist (ConnectionDefinition).
If the referenced container property is a direct relation, a view of the node can be specified. The view is
a hint to the consumer on what type of data is expected to be of interest in the context of this view.
A connection describes the edges that are likely to exist to aid in discovery and documentation of the view.
A listed edge is not required. i.e. It does not have to exist when included in this list. The target nodes of
this connection will match the view specified in the source property. A connection has a max distance of one hop
in the underlying graph.
'
oneOf:
- $ref: '#/components/schemas/CreateViewProperty'
- $ref: '#/components/schemas/ConnectionDefinition'
InFilterV3:
type: object
title: in
required:
- in
properties:
in:
required:
- property
- values
description: Matches items where the property **exactly** matches one of the given values.
type: object
properties:
property:
$ref: '#/components/schemas/DMSFilterProperty'
values:
$ref: '#/components/schemas/FilterValueList'
HasExistingDataFilterV3:
type: object
title: hasData
required:
- hasData
properties:
hasData:
type: array
description: Matches instances that have data in the referenced views or containers.
items:
$ref: '#/components/schemas/SourceReference'
ViewDirectNodeRelation:
description: Direct node relation. Can include a hint to specify the view that this direct relation points to. This hint is optional.
allOf:
- $ref: '#/components/schemas/DirectNodeRelation'
- type: object
properties:
source:
description: The hint showing the view what the direct relation points to.
allOf:
- $ref: '#/components/schemas/ViewReference'
DMSExistsFilter:
type: object
title: exists
required:
- exists
properties:
exists:
required:
- property
description: 'Will match items that have a value in the specified property.
'
type: object
properties:
property:
$ref: '#/components/schemas/DMSFilterProperty'
ContainerReference:
type: object
description: Reference to an existing container
required:
- type
- space
- externalId
properties:
type:
type: string
enum:
- container
space:
description: Id of the space hosting (containing) the container
allOf:
- $ref: '#/components/schemas/SpaceSpecification'
externalId:
description: External-id of the container
allOf:
- $ref: '#/components/schemas/DMSExternalId'
SpaceSpecification:
type: string
pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,41}[a-zA-Z0-9]?$
minLength: 1
maxLength: 43
DirectNodeRelation:
type: object
description: Direct node relation
required:
- type
properties:
type:
type: string
enum:
- direct
container:
description: The (optional) required type for the node the direct relation points to. If specified, the node must exist before the direct relation is referenced and of the specified type. If no container specification is used, the node will be auto created with the built-in ```node``` container type, and it does not explicitly have to be created before the node that references it. For records, the container type constraint is not enforced and targets are not auto-created. Only the target space existence is validated.
allOf:
- $ref: '#/components/schemas/ContainerReference'
list:
description: 'Specifies that the data type is a list of values. The ordering of values is preserved.
'
type: boolean
default: false
maxListSize:
type: integer
description: Specifies the maximum number of values in the list
EnumValueProperties:
type: object
description: Metadata of the enum value.
properties:
name:
type: string
description: Name of the enum value.
maxLength: 255
description:
type: string
description: Description of the enum value.
maxLength: 1024
OverlapsFilterV3:
type: object
title: overlaps
required:
- overlaps
properties:
overlaps:
type: object
description: 'Matches items where the range made up of the two properties overlap with the provided range.
Not available for search queries.'
required:
- startProperty
- endProperty
properties:
startProperty:
$ref: '#/components/schemas/DMSFilterProperty'
# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cognite/refs/heads/main/openapi/cognite-data-models-api-openapi.yml