Skip to main content
POST
/
streams
/
{streamId}
/
records
/
upsert
Upsert (create or update) records into a stream
curl --request POST \
  --url https://{cluster}.cognitedata.com/api/v1/projects/{project}/streams/{streamId}/records/upsert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "space": "mySpace",
      "externalId": "some_id",
      "sources": [
        {
          "source": {
            "type": "container,",
            "space": "mySpace,",
            "externalId": "myContainer"
          },
          "properties": {
            "someStringProperty": "someStringValue",
            "someDirectRelation": {
              "space": "mySpace",
              "externalId": "someNode"
            },
            "someIntArrayProperty": [
              1,
              2,
              3,
              4
            ]
          }
        }
      ]
    }
  ]
}
'
{}

Documentation Index

Fetch the complete documentation index at: https://docs.cognite.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

Path Parameters

​
streamId
string
required

An identifier of the stream where the records are stored.

Required string length: 1 - 100
Pattern: ^[a-z]([a-z0-9_-]{0,98}[a-z0-9])?$
Example:

"test1"

Body

application/json

Records to upsert into a stream.

​
items
recordItem · object[]
required

List of records to write.

Required array length: 1 - 1000 elements

Response

An empty response is returned if all records from the request are successfully accepted to be created or updated.

Empty JSON object indicates all records are successfully accepted.

Last modified on May 13, 2026