Python SDK

from cognite.client.data_classes.data_modeling import EdgeApply, NodeOrEdgeData, NodeApply
node = NodeApply("mySpace", "myNodeId")
res = client.data_modeling.instances.apply(node)

from cognite.client.data_classes.data_modeling import EdgeApply, NodeOrEdgeData, NodeApply, ViewId
actor = NodeApply(
    space="actors",
    external_id="arnold_schwarzenegger",
    sources=[
        NodeOrEdgeData(
            ViewId("mySpace", "PersonView", "v1"),
            {"name": "Arnold Schwarzenegger", "birthYear": 1947}
        ),
        NodeOrEdgeData(
            ViewId("mySpace", "ActorView", "v1"),
            {"wonOscar": False}
        )
    ]
)
movie = NodeApply(
    space="movies",
    external_id="Terminator",
    sources=[
        NodeOrEdgeData(
            ViewId("mySpace", "MovieView", "v1"),
            {"title": "Terminator", "releaseYear": 1984}
        )
    ]
)
# This is one-to-many edge, in this case from a person to a movie
actor_to_movie = EdgeApply(
    space="actors",
    external_id="relation:arnold_schwarzenegger:terminator",
    type=("types", "acts-in"),
    start_node=("actors", "arnold_schwarzenegger"),
    end_node=("movies", "Terminator"),
)
res = client.data_modeling.instances.apply([actor, movie], [actor_to_movie])

from cognite.client.data_classes.data_modeling import EdgeApply
actor_to_movie = EdgeApply(
    space="actors",
    external_id="relation:arnold_schwarzenegger:terminator",
    type=("types", "acts-in"),
    start_node=("actors", "arnold_schwarzenegger"),
    end_node=("movies", "Terminator"),
)
res = client.data_modeling.instances.apply(
    edges=actor_to_movie,
    auto_create_start_nodes=True,
    auto_create_end_nodes=True
)

from cognite.client.utils import datetime_to_ms_iso_timestamp
from datetime import datetime, timezone
my_date = datetime(2020, 3, 14, 15, 9, 26, 535000, tzinfo=timezone.utc)
data_model_timestamp = datetime_to_ms_iso_timestamp(my_date)  # "2020-03-14T15:09:26.535+00:00"

from cognite.client.data_classes.data_modeling import TypedNodeApply, PropertyOptions
class PersonApply(TypedNodeApply):
    birth_year = PropertyOptions(identifier="birthYear")

    def __init__(self, space: str, external_id, name: str, birth_year: int):
        super().__init__(space, external_id, type=("sp_model_space", "Person"))
        self.name = name
        self.birth_year = birth_year
    def get_source(self):
        return ViewId("sp_model_space", "Person", "v1")
person = PersonApply("sp_date_space", "my_person", "John Doe", 1980)
res = client.data_modeling.instances.apply(nodes=person)

curl --request POST \
  --url https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "instanceType": "node",
      "space": "<string>",
      "externalId": "<string>",
      "existingVersion": 123,
      "sources": [
        {
          "source": {
            "type": "view",
            "space": "<string>",
            "externalId": "<string>",
            "version": "<string>"
          },
          "properties": {
            "someStringProperty": "someStringValue",
            "someDirectRelation": {
              "space": "mySpace",
              "externalId": "someNode"
            },
            "someIntArrayProperty": [
              1,
              2,
              3,
              4
            ]
          }
        }
      ]
    }
  ],
  "delete": [
    {
      "space": "<string>",
      "externalId": "<string>",
      "existingVersion": 123
    }
  ],
  "autoCreateDirectRelations": true,
  "autoCreateStartNodes": false,
  "autoCreateEndNodes": false,
  "skipOnVersionConflict": false,
  "replace": false
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {
        instanceType: 'node',
        space: '<string>',
        externalId: '<string>',
        existingVersion: 123,
        sources: [
          {
            source: {type: 'view', space: '<string>', externalId: '<string>', version: '<string>'},
            properties: {
              someStringProperty: 'someStringValue',
              someDirectRelation: {space: 'mySpace', externalId: 'someNode'},
              someIntArrayProperty: [1, 2, 3, 4]
            }
          }
        ]
      }
    ],
    delete: [{space: '<string>', externalId: '<string>', existingVersion: 123}],
    autoCreateDirectRelations: true,
    autoCreateStartNodes: false,
    autoCreateEndNodes: false,
    skipOnVersionConflict: false,
    replace: false
  })
};

fetch('https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'items' => [
        [
                'instanceType' => 'node',
                'space' => '<string>',
                'externalId' => '<string>',
                'existingVersion' => 123,
                'sources' => [
                                [
                                                                'source' => [
                                                                                                                                'type' => 'view',
                                                                                                                                'space' => '<string>',
                                                                                                                                'externalId' => '<string>',
                                                                                                                                'version' => '<string>'
                                                                ],
                                                                'properties' => [
                                                                                                                                'someStringProperty' => 'someStringValue',
                                                                                                                                'someDirectRelation' => [
                                                                                                                                                                                                                                                                'space' => 'mySpace',
                                                                                                                                                                                                                                                                'externalId' => 'someNode'
                                                                                                                                ],
                                                                                                                                'someIntArrayProperty' => [
                                                                                                                                                                                                                                                                1,
                                                                                                                                                                                                                                                                2,
                                                                                                                                                                                                                                                                3,
                                                                                                                                                                                                                                                                4
                                                                                                                                ]
                                                                ]
                                ]
                ]
        ]
    ],
    'delete' => [
        [
                'space' => '<string>',
                'externalId' => '<string>',
                'existingVersion' => 123
        ]
    ],
    'autoCreateDirectRelations' => true,
    'autoCreateStartNodes' => false,
    'autoCreateEndNodes' => false,
    'skipOnVersionConflict' => false,
    'replace' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"instanceType\": \"node\",\n      \"space\": \"<string>\",\n      \"externalId\": \"<string>\",\n      \"existingVersion\": 123,\n      \"sources\": [\n        {\n          \"source\": {\n            \"type\": \"view\",\n            \"space\": \"<string>\",\n            \"externalId\": \"<string>\",\n            \"version\": \"<string>\"\n          },\n          \"properties\": {\n            \"someStringProperty\": \"someStringValue\",\n            \"someDirectRelation\": {\n              \"space\": \"mySpace\",\n              \"externalId\": \"someNode\"\n            },\n            \"someIntArrayProperty\": [\n              1,\n              2,\n              3,\n              4\n            ]\n          }\n        }\n      ]\n    }\n  ],\n  \"delete\": [\n    {\n      \"space\": \"<string>\",\n      \"externalId\": \"<string>\",\n      \"existingVersion\": 123\n    }\n  ],\n  \"autoCreateDirectRelations\": true,\n  \"autoCreateStartNodes\": false,\n  \"autoCreateEndNodes\": false,\n  \"skipOnVersionConflict\": false,\n  \"replace\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"instanceType\": \"node\",\n      \"space\": \"<string>\",\n      \"externalId\": \"<string>\",\n      \"existingVersion\": 123,\n      \"sources\": [\n        {\n          \"source\": {\n            \"type\": \"view\",\n            \"space\": \"<string>\",\n            \"externalId\": \"<string>\",\n            \"version\": \"<string>\"\n          },\n          \"properties\": {\n            \"someStringProperty\": \"someStringValue\",\n            \"someDirectRelation\": {\n              \"space\": \"mySpace\",\n              \"externalId\": \"someNode\"\n            },\n            \"someIntArrayProperty\": [\n              1,\n              2,\n              3,\n              4\n            ]\n          }\n        }\n      ]\n    }\n  ],\n  \"delete\": [\n    {\n      \"space\": \"<string>\",\n      \"externalId\": \"<string>\",\n      \"existingVersion\": 123\n    }\n  ],\n  \"autoCreateDirectRelations\": true,\n  \"autoCreateStartNodes\": false,\n  \"autoCreateEndNodes\": false,\n  \"skipOnVersionConflict\": false,\n  \"replace\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"instanceType\": \"node\",\n      \"space\": \"<string>\",\n      \"externalId\": \"<string>\",\n      \"existingVersion\": 123,\n      \"sources\": [\n        {\n          \"source\": {\n            \"type\": \"view\",\n            \"space\": \"<string>\",\n            \"externalId\": \"<string>\",\n            \"version\": \"<string>\"\n          },\n          \"properties\": {\n            \"someStringProperty\": \"someStringValue\",\n            \"someDirectRelation\": {\n              \"space\": \"mySpace\",\n              \"externalId\": \"someNode\"\n            },\n            \"someIntArrayProperty\": [\n              1,\n              2,\n              3,\n              4\n            ]\n          }\n        }\n      ]\n    }\n  ],\n  \"delete\": [\n    {\n      \"space\": \"<string>\",\n      \"externalId\": \"<string>\",\n      \"existingVersion\": 123\n    }\n  ],\n  \"autoCreateDirectRelations\": true,\n  \"autoCreateStartNodes\": false,\n  \"autoCreateEndNodes\": false,\n  \"skipOnVersionConflict\": false,\n  \"replace\": false\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "instanceType": "node",
      "version": 123,
      "wasModified": true,
      "space": "<string>",
      "externalId": "<string>",
      "createdTime": 1730204346000,
      "lastUpdatedTime": 1730204346000
    }
  ],
  "deleted": [
    {
      "externalId": "<string>",
      "space": "<string>"
    }
  ]
}

{
  "error": {
    "code": 401,
    "message": "Could not authenticate.",
    "missing": [
      {}
    ],
    "duplicated": [
      {}
    ]
  }
}

{
  "error": {
    "code": 409,
    "message": "<string>",
    "isAutoRetryable": true
  }
}

Create or update nodes/edges

Required capabilities: dataModelsAcl:WRITE

Create or update nodes and edges in a transaction. The items field of the payload is an array of objects where each object describes a node or an edge to create, patch or replace. The instanceType field of each object must be node or edge and determines how the rest of the object is interpreted.

This operation is currently limited to 1000 nodes and/or edges at a time.

Individual nodes and edges are uniquely identified by their externalId and space.

Instances will be returned in the same order as they are supplied in the request.

For more details on ingesting instances into a graph, see [Ingesting instances] (https://docs.cognite.com/cdf/dm/dm_concepts/dm_ingestion).

Creating new instances

When there is no node or edge with the given externalId in the given space, a node will be created and the properties provided for each of the containers or views in the sources array will be populated for the node/edge. Nodes can also be created implicitly when an edge between them is created (if autoCreateStartNodes and/or autoCreateEndNodes is set), or when a direct relation property is set, the target node does not exist and autoCreateDirectRelations is set.

To add a node or edge, the user must have capabilities to access (write to) both the view(s) referenced in sources and the container(s) underlying these views, as well as any directly referenced containers.

Updating (patching) or replacing instances

When a node or edge (instance) with the given externalId already exists in a space, the properties named in the sources field will be written to the instance. Other properties will remain unchanged. To replace the whole set of properties for an instance (a node or an edge) rather than patch the instance, set the replace parameter to true.

Note: When using replace as true it will replace any omitted property to either it’s default value as defined on the container(s) or null if no default value is set. All properties on the related container(s) referenced in the provided sources view(s) will be replaced, so even when the provided view(s) only contains a subset of properties from a container all the properties in that container for that instance will be replaced. If the underlying container(s) have any required properties that are not provided, the operation will fail.

If you use a writable view to update properties (that is, the source you are referring to in sources is a view), you must have write access to the view as well as all of its backing containers.

No-change patch operations

When a node/edge item has no changes compared to the existing instance - that is, when the supplied property values are equal to the corresponding values in the existing node/edge, the node/edge will stay unchanged. In this case, the lastUpdatedTime values for the nodes/edges in question will not change.

Deleting instances

It’s also possible to delete instances by passing instance references to the delete field. Upserts and deletes can be combined in the same request and will be executed atomically. The total number of ingested and deleted items cannot exceed 1000. If an instance doesn’t exist, the delete operation skips it and it won’t be included in the response.

POST

models

instances

Python SDK

from cognite.client.data_classes.data_modeling import EdgeApply, NodeOrEdgeData, NodeApply
node = NodeApply("mySpace", "myNodeId")
res = client.data_modeling.instances.apply(node)

from cognite.client.data_classes.data_modeling import EdgeApply, NodeOrEdgeData, NodeApply, ViewId
actor = NodeApply(
    space="actors",
    external_id="arnold_schwarzenegger",
    sources=[
        NodeOrEdgeData(
            ViewId("mySpace", "PersonView", "v1"),
            {"name": "Arnold Schwarzenegger", "birthYear": 1947}
        ),
        NodeOrEdgeData(
            ViewId("mySpace", "ActorView", "v1"),
            {"wonOscar": False}
        )
    ]
)
movie = NodeApply(
    space="movies",
    external_id="Terminator",
    sources=[
        NodeOrEdgeData(
            ViewId("mySpace", "MovieView", "v1"),
            {"title": "Terminator", "releaseYear": 1984}
        )
    ]
)
# This is one-to-many edge, in this case from a person to a movie
actor_to_movie = EdgeApply(
    space="actors",
    external_id="relation:arnold_schwarzenegger:terminator",
    type=("types", "acts-in"),
    start_node=("actors", "arnold_schwarzenegger"),
    end_node=("movies", "Terminator"),
)
res = client.data_modeling.instances.apply([actor, movie], [actor_to_movie])

from cognite.client.data_classes.data_modeling import EdgeApply
actor_to_movie = EdgeApply(
    space="actors",
    external_id="relation:arnold_schwarzenegger:terminator",
    type=("types", "acts-in"),
    start_node=("actors", "arnold_schwarzenegger"),
    end_node=("movies", "Terminator"),
)
res = client.data_modeling.instances.apply(
    edges=actor_to_movie,
    auto_create_start_nodes=True,
    auto_create_end_nodes=True
)

from cognite.client.utils import datetime_to_ms_iso_timestamp
from datetime import datetime, timezone
my_date = datetime(2020, 3, 14, 15, 9, 26, 535000, tzinfo=timezone.utc)
data_model_timestamp = datetime_to_ms_iso_timestamp(my_date)  # "2020-03-14T15:09:26.535+00:00"

from cognite.client.data_classes.data_modeling import TypedNodeApply, PropertyOptions
class PersonApply(TypedNodeApply):
    birth_year = PropertyOptions(identifier="birthYear")

    def __init__(self, space: str, external_id, name: str, birth_year: int):
        super().__init__(space, external_id, type=("sp_model_space", "Person"))
        self.name = name
        self.birth_year = birth_year
    def get_source(self):
        return ViewId("sp_model_space", "Person", "v1")
person = PersonApply("sp_date_space", "my_person", "John Doe", 1980)
res = client.data_modeling.instances.apply(nodes=person)

curl --request POST \
  --url https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "instanceType": "node",
      "space": "<string>",
      "externalId": "<string>",
      "existingVersion": 123,
      "sources": [
        {
          "source": {
            "type": "view",
            "space": "<string>",
            "externalId": "<string>",
            "version": "<string>"
          },
          "properties": {
            "someStringProperty": "someStringValue",
            "someDirectRelation": {
              "space": "mySpace",
              "externalId": "someNode"
            },
            "someIntArrayProperty": [
              1,
              2,
              3,
              4
            ]
          }
        }
      ]
    }
  ],
  "delete": [
    {
      "space": "<string>",
      "externalId": "<string>",
      "existingVersion": 123
    }
  ],
  "autoCreateDirectRelations": true,
  "autoCreateStartNodes": false,
  "autoCreateEndNodes": false,
  "skipOnVersionConflict": false,
  "replace": false
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {
        instanceType: 'node',
        space: '<string>',
        externalId: '<string>',
        existingVersion: 123,
        sources: [
          {
            source: {type: 'view', space: '<string>', externalId: '<string>', version: '<string>'},
            properties: {
              someStringProperty: 'someStringValue',
              someDirectRelation: {space: 'mySpace', externalId: 'someNode'},
              someIntArrayProperty: [1, 2, 3, 4]
            }
          }
        ]
      }
    ],
    delete: [{space: '<string>', externalId: '<string>', existingVersion: 123}],
    autoCreateDirectRelations: true,
    autoCreateStartNodes: false,
    autoCreateEndNodes: false,
    skipOnVersionConflict: false,
    replace: false
  })
};

fetch('https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'items' => [
        [
                'instanceType' => 'node',
                'space' => '<string>',
                'externalId' => '<string>',
                'existingVersion' => 123,
                'sources' => [
                                [
                                                                'source' => [
                                                                                                                                'type' => 'view',
                                                                                                                                'space' => '<string>',
                                                                                                                                'externalId' => '<string>',
                                                                                                                                'version' => '<string>'
                                                                ],
                                                                'properties' => [
                                                                                                                                'someStringProperty' => 'someStringValue',
                                                                                                                                'someDirectRelation' => [
                                                                                                                                                                                                                                                                'space' => 'mySpace',
                                                                                                                                                                                                                                                                'externalId' => 'someNode'
                                                                                                                                ],
                                                                                                                                'someIntArrayProperty' => [
                                                                                                                                                                                                                                                                1,
                                                                                                                                                                                                                                                                2,
                                                                                                                                                                                                                                                                3,
                                                                                                                                                                                                                                                                4
                                                                                                                                ]
                                                                ]
                                ]
                ]
        ]
    ],
    'delete' => [
        [
                'space' => '<string>',
                'externalId' => '<string>',
                'existingVersion' => 123
        ]
    ],
    'autoCreateDirectRelations' => true,
    'autoCreateStartNodes' => false,
    'autoCreateEndNodes' => false,
    'skipOnVersionConflict' => false,
    'replace' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"instanceType\": \"node\",\n      \"space\": \"<string>\",\n      \"externalId\": \"<string>\",\n      \"existingVersion\": 123,\n      \"sources\": [\n        {\n          \"source\": {\n            \"type\": \"view\",\n            \"space\": \"<string>\",\n            \"externalId\": \"<string>\",\n            \"version\": \"<string>\"\n          },\n          \"properties\": {\n            \"someStringProperty\": \"someStringValue\",\n            \"someDirectRelation\": {\n              \"space\": \"mySpace\",\n              \"externalId\": \"someNode\"\n            },\n            \"someIntArrayProperty\": [\n              1,\n              2,\n              3,\n              4\n            ]\n          }\n        }\n      ]\n    }\n  ],\n  \"delete\": [\n    {\n      \"space\": \"<string>\",\n      \"externalId\": \"<string>\",\n      \"existingVersion\": 123\n    }\n  ],\n  \"autoCreateDirectRelations\": true,\n  \"autoCreateStartNodes\": false,\n  \"autoCreateEndNodes\": false,\n  \"skipOnVersionConflict\": false,\n  \"replace\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"instanceType\": \"node\",\n      \"space\": \"<string>\",\n      \"externalId\": \"<string>\",\n      \"existingVersion\": 123,\n      \"sources\": [\n        {\n          \"source\": {\n            \"type\": \"view\",\n            \"space\": \"<string>\",\n            \"externalId\": \"<string>\",\n            \"version\": \"<string>\"\n          },\n          \"properties\": {\n            \"someStringProperty\": \"someStringValue\",\n            \"someDirectRelation\": {\n              \"space\": \"mySpace\",\n              \"externalId\": \"someNode\"\n            },\n            \"someIntArrayProperty\": [\n              1,\n              2,\n              3,\n              4\n            ]\n          }\n        }\n      ]\n    }\n  ],\n  \"delete\": [\n    {\n      \"space\": \"<string>\",\n      \"externalId\": \"<string>\",\n      \"existingVersion\": 123\n    }\n  ],\n  \"autoCreateDirectRelations\": true,\n  \"autoCreateStartNodes\": false,\n  \"autoCreateEndNodes\": false,\n  \"skipOnVersionConflict\": false,\n  \"replace\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"instanceType\": \"node\",\n      \"space\": \"<string>\",\n      \"externalId\": \"<string>\",\n      \"existingVersion\": 123,\n      \"sources\": [\n        {\n          \"source\": {\n            \"type\": \"view\",\n            \"space\": \"<string>\",\n            \"externalId\": \"<string>\",\n            \"version\": \"<string>\"\n          },\n          \"properties\": {\n            \"someStringProperty\": \"someStringValue\",\n            \"someDirectRelation\": {\n              \"space\": \"mySpace\",\n              \"externalId\": \"someNode\"\n            },\n            \"someIntArrayProperty\": [\n              1,\n              2,\n              3,\n              4\n            ]\n          }\n        }\n      ]\n    }\n  ],\n  \"delete\": [\n    {\n      \"space\": \"<string>\",\n      \"externalId\": \"<string>\",\n      \"existingVersion\": 123\n    }\n  ],\n  \"autoCreateDirectRelations\": true,\n  \"autoCreateStartNodes\": false,\n  \"autoCreateEndNodes\": false,\n  \"skipOnVersionConflict\": false,\n  \"replace\": false\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "instanceType": "node",
      "version": 123,
      "wasModified": true,
      "space": "<string>",
      "externalId": "<string>",
      "createdTime": 1730204346000,
      "lastUpdatedTime": 1730204346000
    }
  ],
  "deleted": [
    {
      "externalId": "<string>",
      "space": "<string>"
    }
  ]
}

{
  "error": {
    "code": 401,
    "message": "Could not authenticate.",
    "missing": [
      {}
    ],
    "duplicated": [
      {}
    ]
  }
}

{
  "error": {
    "code": 409,
    "message": "<string>",
    "isAutoRetryable": true
  }
}

Authorizations

Authorization

string

header

required

Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.

Body

application/json

Nodes/edges to add or update.

items

object[]

required

List of nodes and edges to create/update

Maximum array length: 1000

Node to create or update

Option 1
Option 2

Show child attributes

delete

object[]

List of nodes and edges to delete

Maximum array length: 1000

Show child attributes

autoCreateDirectRelations

boolean

default:true

Should we create missing target nodes of direct relations? If the target-container constraint has been specified for a direct relation, the target node cannot be auto-created. If you want to point direct relations to a space where you have only read access, this option must be set to false.

autoCreateStartNodes

boolean

default:false

Should we create missing start nodes for edges when ingesting? By default, the start node of an edge must exist before we can ingest the edge.

autoCreateEndNodes

boolean

default:false

Should we create missing end nodes for edges when ingesting? By default, the end node of an edge must exist before we can ingest the edge.

skipOnVersionConflict

boolean

default:false

If existingVersion is specified on any of the nodes/edges in the input, the default behaviour is that the entire ingestion will fail when version conflicts occur. If skipOnVersionConflict is set to true, items with version conflicts will be skipped instead. If no version is specified for nodes/edges, it will do the write directly.

replace

boolean

default:false

How do we behave when a property value exists? Do we replace all matching and existing values with the supplied values (true)? Or should we merge in new values for properties together with the existing values (false)? Note: This setting applies for all nodes or edges specified in the ingestion call.

Response

Created, deleted, and updated instances

items

object[]

required

List of nodes and edges that were created or updated

Node

Option 1
Option 2

Show child attributes

deleted

object[]

required

List of deleted instances

Required array length: 1 - 1000 elements

Show child attributes

Last modified on July 31, 2026

Aggregate data across nodes/edges

Delete nodes/edges

⌘I