---
title: "POST /entities/diff"
method: POST
path: "/entities/diff"
tags: ["Graph", "Entity"]
---

# POST /entities/diff

`POST /entities/diff`

## Headers

- `X-Authenticated-User-Actor-Id` string, uuid, required

## Request body

- DiffEntityParams
  - `firstDecisionTime` string, date-time, required
  - `firstEntityId` string, required
  - `firstTransactionTime` string, date-time, required
  - `secondDecisionTime` string, date-time, required
  - `secondEntityId` string, required
  - `secondTransactionTime` string, date-time, required

## Response `200`

The difference between the two entities

- DiffEntityResult
  - `draftState` boolean
  - `entityTypeIds` EntityTypeIdDiff[]
    - union
      - object
        - `added` string, uri, required — The versioned URL of a Block Protocol ontology type (the $id of the schema). It should be of the form `${baseUrl}v/${versionNumber}`
        - `op` 'added', required
      - object
        - `op` 'removed', required
        - `removed` string, uri, required — The versioned URL of a Block Protocol ontology type (the $id of the schema). It should be of the form `${baseUrl}v/${versionNumber}`
  - `properties` PropertyDiff[]
    - union — A representation of a difference between two property structures. [`PropertyDiff`] captures the nature of a change between two property values, including the path where the change occurred and the relevant property values (added, removed, or changed). This structure enables precise tracking of property modifications throughout the system. When comparing two property hierarchies, multiple diffs may be generated to represent all changes, with each diff capturing a specific modification at a particular path.
      - object — A property was added at the specified path. This variant indicates that a property that didn't exist in the original structure was added in the new one.
        - `added` union, required — Structured data that can be associated with an entity, conforming to property types defined in the ontology. The [`Property`] enum represents the hierarchical structure of data within an entity. Properties are instances of [`PropertyType`]s defined in the ontology. The relationship is similar to objects and classes in object-oriented programming: - [`PropertyType`]s define the schema, structure, and constraints that properties must follow - [`Property`] instances contain actual data conforming to those schemas Properties can be: - Arrays of other properties - Objects (maps) with property type URLs as keys and nested properties as values - Primitive values like strings, numbers, booleans, etc. Each property in an entity: - Corresponds to a specific [`PropertyType`] in the ontology - May have associated metadata tracking provenance, confidence, and other contextual information - Must satisfy the validation rules defined in its property type - Can be addressed using a [`PropertyPath`] for targeted access and modification Properties form the backbone of entity data representation in the system, allowing for flexible and structured knowledge organization that aligns with the ontology. [`PropertyType`]: crate::ontology::property_type::PropertyType
          - Property[] — An ordered collection of properties. Arrays can contain heterogeneous property types, though typically they contain properties of the same structure based on the entity type definition.
          - PropertyObject
          - unknown
        - `op` 'added', required
        - `path` PropertyPathElement[], required
          - union — An element in a property path that identifies a specific property location. [`PropertyPathElement`] represents a single step in navigating a property hierarchy, addressing either: - A specific property by its type URL (for object properties) - A specific index (for array properties) These elements can be chained together to form a [`PropertyPath`] that addresses deeply nested properties within the property hierarchy.
            - string, uri — The base URL of a Block Protocol ontology type (the $id of the schema, without the versioned suffix). It should be a valid URL, with a trailing slash.
            - integer — An array index that addresses a specific element in an array property.
      - object — A property was removed from the specified path. This variant indicates that a property that existed in the original structure was removed in the new one.
        - `op` 'removed', required
        - `path` PropertyPathElement[], required
          - union — An element in a property path that identifies a specific property location. [`PropertyPathElement`] represents a single step in navigating a property hierarchy, addressing either: - A specific property by its type URL (for object properties) - A specific index (for array properties) These elements can be chained together to form a [`PropertyPath`] that addresses deeply nested properties within the property hierarchy.
            - string, uri — The base URL of a Block Protocol ontology type (the $id of the schema, without the versioned suffix). It should be a valid URL, with a trailing slash.
            - integer — An array index that addresses a specific element in an array property.
        - `removed` union, required — Structured data that can be associated with an entity, conforming to property types defined in the ontology. The [`Property`] enum represents the hierarchical structure of data within an entity. Properties are instances of [`PropertyType`]s defined in the ontology. The relationship is similar to objects and classes in object-oriented programming: - [`PropertyType`]s define the schema, structure, and constraints that properties must follow - [`Property`] instances contain actual data conforming to those schemas Properties can be: - Arrays of other properties - Objects (maps) with property type URLs as keys and nested properties as values - Primitive values like strings, numbers, booleans, etc. Each property in an entity: - Corresponds to a specific [`PropertyType`] in the ontology - May have associated metadata tracking provenance, confidence, and other contextual information - Must satisfy the validation rules defined in its property type - Can be addressed using a [`PropertyPath`] for targeted access and modification Properties form the backbone of entity data representation in the system, allowing for flexible and structured knowledge organization that aligns with the ontology. [`PropertyType`]: crate::ontology::property_type::PropertyType
          - Property[] — An ordered collection of properties. Arrays can contain heterogeneous property types, though typically they contain properties of the same structure based on the entity type definition.
          - PropertyObject
          - unknown
      - object — A property at the specified path changed value. This variant indicates that a property existed in both structures but had different values.
        - `new` union, required — Structured data that can be associated with an entity, conforming to property types defined in the ontology. The [`Property`] enum represents the hierarchical structure of data within an entity. Properties are instances of [`PropertyType`]s defined in the ontology. The relationship is similar to objects and classes in object-oriented programming: - [`PropertyType`]s define the schema, structure, and constraints that properties must follow - [`Property`] instances contain actual data conforming to those schemas Properties can be: - Arrays of other properties - Objects (maps) with property type URLs as keys and nested properties as values - Primitive values like strings, numbers, booleans, etc. Each property in an entity: - Corresponds to a specific [`PropertyType`] in the ontology - May have associated metadata tracking provenance, confidence, and other contextual information - Must satisfy the validation rules defined in its property type - Can be addressed using a [`PropertyPath`] for targeted access and modification Properties form the backbone of entity data representation in the system, allowing for flexible and structured knowledge organization that aligns with the ontology. [`PropertyType`]: crate::ontology::property_type::PropertyType
          - Property[] — An ordered collection of properties. Arrays can contain heterogeneous property types, though typically they contain properties of the same structure based on the entity type definition.
          - PropertyObject
          - unknown
        - `old` union, required — Structured data that can be associated with an entity, conforming to property types defined in the ontology. The [`Property`] enum represents the hierarchical structure of data within an entity. Properties are instances of [`PropertyType`]s defined in the ontology. The relationship is similar to objects and classes in object-oriented programming: - [`PropertyType`]s define the schema, structure, and constraints that properties must follow - [`Property`] instances contain actual data conforming to those schemas Properties can be: - Arrays of other properties - Objects (maps) with property type URLs as keys and nested properties as values - Primitive values like strings, numbers, booleans, etc. Each property in an entity: - Corresponds to a specific [`PropertyType`] in the ontology - May have associated metadata tracking provenance, confidence, and other contextual information - Must satisfy the validation rules defined in its property type - Can be addressed using a [`PropertyPath`] for targeted access and modification Properties form the backbone of entity data representation in the system, allowing for flexible and structured knowledge organization that aligns with the ontology. [`PropertyType`]: crate::ontology::property_type::PropertyType
          - Property[] — An ordered collection of properties. Arrays can contain heterogeneous property types, though typically they contain properties of the same structure based on the entity type definition.
          - PropertyObject
          - unknown
        - `op` 'changed', required
        - `path` PropertyPathElement[], required
          - union — An element in a property path that identifies a specific property location. [`PropertyPathElement`] represents a single step in navigating a property hierarchy, addressing either: - A specific property by its type URL (for object properties) - A specific index (for array properties) These elements can be chained together to form a [`PropertyPath`] that addresses deeply nested properties within the property hierarchy.
            - string, uri — The base URL of a Block Protocol ontology type (the $id of the schema, without the versioned suffix). It should be a valid URL, with a trailing slash.
            - integer — An array index that addresses a specific element in an array property.

## Other responses

- `404` — Entity ID was not found
- `422` — Provided request body is invalid
- `500` — Store error occurred

---

[API](https://skmtc.dev/hashintel/apis/graph.md) · [All operations](https://skmtc.dev/hashintel/apis/graph/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hashintel/graph/revisions/ba95e69ddba8/schema)