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

# POST /entities

`POST /entities`

## Headers

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

## Request body

- CreateEntityParams
  - `confidence` number, double
  - `decisionTime` string, date-time
  - `draft` boolean, required
  - `entityTypeIds` VersionedUrl[], required
  - `entityUuid` string, uuid
  - `linkData` LinkData — The associated information for 'Link' entities.
    - `leftEntityConfidence` number, double
    - `leftEntityId` string, required
    - `leftEntityProvenance` PropertyProvenance
      - `sources` SourceProvenance[]
        - `authors` string[] — The people or organizations that authored the material.
        - `entityId` string
        - `firstPublished` string, date-time
        - `lastUpdated` string, date-time
        - `loadedAt` string, date-time
        - `location` Location — A location where the source material can be found.
          - `description` string — Encapsulates a message intended to be read by the end user.
          - `name` string — A string containing the name of the location.
          - `uri` string, uri — A string containing a valid relative or absolute URI.
        - `type` 'webpage' | 'document' | 'integration', required — The type of source material which was used to produce a value.
    - `rightEntityConfidence` number, double
    - `rightEntityId` string, required
    - `rightEntityProvenance` PropertyProvenance
      - `sources` SourceProvenance[]
        - `authors` string[] — The people or organizations that authored the material.
        - `entityId` string
        - `firstPublished` string, date-time
        - `lastUpdated` string, date-time
        - `loadedAt` string, date-time
        - `location` Location — A location where the source material can be found.
          - `description` string — Encapsulates a message intended to be read by the end user.
          - `name` string — A string containing the name of the location.
          - `uri` string, uri — A string containing a valid relative or absolute URI.
        - `type` 'webpage' | 'document' | 'integration', required — The type of source material which was used to produce a value.
  - `policies` object[]
  - `properties` PropertyObjectWithMetadata, required
    - `metadata` ObjectMetadata
      - `confidence` number, double
      - `provenance` PropertyProvenance
        - `sources` SourceProvenance[]
          - `authors` string[] — The people or organizations that authored the material.
          - `entityId` string
          - `firstPublished` string, date-time
          - `lastUpdated` string, date-time
          - `loadedAt` string, date-time
          - `location` Location — A location where the source material can be found.
            - `description` string — Encapsulates a message intended to be read by the end user.
            - `name` string — A string containing the name of the location.
            - `uri` string, uri — A string containing a valid relative or absolute URI.
          - `type` 'webpage' | 'document' | 'integration', required — The type of source material which was used to produce a value.
    - `value` object, required
  - `provenance` ProvidedEntityEditionProvenance, required
    - `actorType` 'user' | 'machine' | 'ai', required — Types of individual actors in the system. Represents the different categories of entities that can perform actions.
    - `origin` union, required
      - object
        - `apiKeyPublicId` string
        - `deviceId` string
        - `environment` string
        - `id` string
        - `semanticVersion` string
        - `sessionId` string
        - `type` 'web-app', required
        - `userAgent` string
        - `version` string — The origin version, in whatever format the origin natively provides.
      - object
        - `apiKeyPublicId` string
        - `deviceId` string
        - `environment` string
        - `id` string
        - `semanticVersion` string
        - `sessionId` string
        - `type` 'mobile-app', required
        - `userAgent` string
        - `version` string — The origin version, in whatever format the origin natively provides.
      - object
        - `apiKeyPublicId` string
        - `deviceId` string
        - `environment` string
        - `id` string
        - `semanticVersion` string
        - `sessionId` string
        - `type` 'browser-extension', required
        - `userAgent` string
        - `version` string — The origin version, in whatever format the origin natively provides.
      - object
        - `apiKeyPublicId` string
        - `deviceId` string
        - `environment` string
        - `id` string
        - `semanticVersion` string
        - `sessionId` string
        - `type` 'api', required
        - `userAgent` string
        - `version` string — The origin version, in whatever format the origin natively provides.
      - object
        - `apiKeyPublicId` string
        - `deviceId` string
        - `environment` string
        - `id` string
        - `semanticVersion` string
        - `sessionId` string
        - `stepIds` string[]
        - `type` 'flow', required
        - `userAgent` string
        - `version` string — The origin version, in whatever format the origin natively provides.
      - object
        - `apiKeyPublicId` string
        - `deviceId` string
        - `environment` string
        - `id` string
        - `semanticVersion` string
        - `sessionId` string
        - `type` 'migration', required
        - `userAgent` string
        - `version` string — The origin version, in whatever format the origin natively provides.
    - `sources` SourceProvenance[]
      - `authors` string[] — The people or organizations that authored the material.
      - `entityId` string
      - `firstPublished` string, date-time
      - `lastUpdated` string, date-time
      - `loadedAt` string, date-time
      - `location` Location — A location where the source material can be found.
        - `description` string — Encapsulates a message intended to be read by the end user.
        - `name` string — A string containing the name of the location.
        - `uri` string, uri — A string containing a valid relative or absolute URI.
      - `type` 'webpage' | 'document' | 'integration', required — The type of source material which was used to produce a value.
  - `readOnly` boolean — Marks the entity read-only, blocking later updates and archival by user actors. Set once at creation, e.g. by a one-way integration sync.
  - `webId` string, uuid, required

## Response `200`

The created entity

- Entity — A record of an entity that has been persisted in the datastore, with its associated metadata. An [`Entity`] represents a real-world object, concept, or thing within the knowledge graph. It contains structured data in the form of properties, optional link data for establishing relationships with other entities, and comprehensive metadata that describes the entity's provenance, types, temporal information, and more. Each entity is an instance of one or more [`EntityType`]s defined in the ontology. The relationship is similar to objects and classes in object-oriented programming: - [`EntityType`]s define the schema, structure, and constraints that entities must follow - [`Entity`] instances contain actual data conforming to those schemas An entity: - Is identified by a unique [`EntityId`] - Has one or more [`VersionedUrl`]s in its `entity_type_ids` field linking to its types - Contains a set of properties structured according to the schemas defined in its types - May have links to other entities, establishing relationships in the knowledge graph - Includes comprehensive metadata for tracking provenance, versioning, and confidence [`EntityType`]: crate::ontology::entity_type::EntityType [`VersionedUrl`]: crate::ontology::VersionedUrl
  - `linkData` LinkData — The associated information for 'Link' entities.
    - `leftEntityConfidence` number, double
    - `leftEntityId` string, required
    - `leftEntityProvenance` PropertyProvenance
      - `sources` SourceProvenance[]
        - `authors` string[] — The people or organizations that authored the material.
        - `entityId` string
        - `firstPublished` string, date-time
        - `lastUpdated` string, date-time
        - `loadedAt` string, date-time
        - `location` Location — A location where the source material can be found.
          - `description` string — Encapsulates a message intended to be read by the end user.
          - `name` string — A string containing the name of the location.
          - `uri` string, uri — A string containing a valid relative or absolute URI.
        - `type` 'webpage' | 'document' | 'integration', required — The type of source material which was used to produce a value.
    - `rightEntityConfidence` number, double
    - `rightEntityId` string, required
    - `rightEntityProvenance` PropertyProvenance
      - `sources` SourceProvenance[]
        - `authors` string[] — The people or organizations that authored the material.
        - `entityId` string
        - `firstPublished` string, date-time
        - `lastUpdated` string, date-time
        - `loadedAt` string, date-time
        - `location` Location — A location where the source material can be found.
          - `description` string — Encapsulates a message intended to be read by the end user.
          - `name` string — A string containing the name of the location.
          - `uri` string, uri — A string containing a valid relative or absolute URI.
        - `type` 'webpage' | 'document' | 'integration', required — The type of source material which was used to produce a value.
  - `metadata` EntityMetadata, required — Comprehensive metadata for an entity in the knowledge graph. [`EntityMetadata`] contains essential information about an entity beyond its properties, including its identity, temporal versioning, type information, provenance, and confidence. This metadata provides context for interpreting and validating the entity's properties.
    - `archived` boolean, required — Whether this entity has been archived. Archived entities are generally not included in regular queries but remain in the system for historical purposes. Note, that this will be replaced by cutting off the temporal versioning interval at the current transaction time in the future. This is a stopgap measure to ensure that archived entities are possible at the time of writing.
    - `confidence` number, double
    - `entityTypeIds` VersionedUrl[], required — The set of entity types this entity conforms to. Each entity must conform to at least one entity type, and may conform to multiple types simultaneously.
    - `properties` PropertyObjectMetadata
      - `metadata` ObjectMetadata
        - `confidence` number, double
        - `provenance` PropertyProvenance
          - `sources` SourceProvenance[]
            - `authors` string[] — The people or organizations that authored the material.
            - `entityId` string
            - `firstPublished` string, date-time
            - `lastUpdated` string, date-time
            - `loadedAt` string, date-time
            - `location` Location — A location where the source material can be found.
              - …
            - `type` 'webpage' | 'document' | 'integration', required — The type of source material which was used to produce a value.
      - `value` object, required — Metadata for each field in the object. The keys correspond to the property type URLs used in the object property.
    - `provenance` EntityProvenance, required
      - `createdAtDecisionTime` string, date-time, required
      - `createdAtTransactionTime` string, date-time, required
      - `createdById` string, uuid, required
      - `deletedAtDecisionTime` string, date-time
      - `deletedAtTransactionTime` string, date-time
      - `deletedById` string, uuid
      - `edition` EntityEditionProvenance, required
        - `actorType` 'user' | 'machine' | 'ai', required — Types of individual actors in the system. Represents the different categories of entities that can perform actions.
        - `origin` union, required
          - object
            - `apiKeyPublicId` string
            - `deviceId` string
            - `environment` string
            - `id` string
            - `semanticVersion` string
            - `sessionId` string
            - `type` 'web-app', required
            - `userAgent` string
            - `version` string — The origin version, in whatever format the origin natively provides.
          - object
            - `apiKeyPublicId` string
            - `deviceId` string
            - `environment` string
            - `id` string
            - `semanticVersion` string
            - `sessionId` string
            - `type` 'mobile-app', required
            - `userAgent` string
            - `version` string — The origin version, in whatever format the origin natively provides.
          - object
            - `apiKeyPublicId` string
            - `deviceId` string
            - `environment` string
            - `id` string
            - `semanticVersion` string
            - `sessionId` string
            - `type` 'browser-extension', required
            - `userAgent` string
            - `version` string — The origin version, in whatever format the origin natively provides.
          - object
            - `apiKeyPublicId` string
            - `deviceId` string
            - `environment` string
            - `id` string
            - `semanticVersion` string
            - `sessionId` string
            - `type` 'api', required
            - `userAgent` string
            - `version` string — The origin version, in whatever format the origin natively provides.
          - object
            - `apiKeyPublicId` string
            - `deviceId` string
            - `environment` string
            - `id` string
            - `semanticVersion` string
            - `sessionId` string
            - `stepIds` string[]
            - `type` 'flow', required
            - `userAgent` string
            - `version` string — The origin version, in whatever format the origin natively provides.
          - object
            - `apiKeyPublicId` string
            - `deviceId` string
            - `environment` string
            - `id` string
            - `semanticVersion` string
            - `sessionId` string
            - `type` 'migration', required
            - `userAgent` string
            - `version` string — The origin version, in whatever format the origin natively provides.
        - `sources` SourceProvenance[]
          - `authors` string[] — The people or organizations that authored the material.
          - `entityId` string
          - `firstPublished` string, date-time
          - `lastUpdated` string, date-time
          - `loadedAt` string, date-time
          - `location` Location — A location where the source material can be found.
            - `description` string — Encapsulates a message intended to be read by the end user.
            - `name` string — A string containing the name of the location.
            - `uri` string, uri — A string containing a valid relative or absolute URI.
          - `type` 'webpage' | 'document' | 'integration', required — The type of source material which was used to produce a value.
        - `archivedById` string, uuid
        - `createdById` string, uuid, required
      - `firstNonDraftCreatedAtDecisionTime` string, date-time
      - `firstNonDraftCreatedAtTransactionTime` string, date-time
    - `readOnly` boolean — Whether this entity is read-only and must not be modified by user actors.
    - `recordId` EntityRecordId, required
      - `editionId` string, uuid, required
      - `entityId` string, required
    - `temporalVersioning` EntityTemporalMetadata, required — Temporal metadata for tracking entity versions over time. [`EntityTemporalMetadata`] tracks two distinct time dimensions: - Decision time: When the entity was decided to exist in the real world - Transaction time: When the entity was recorded in the system This bi-temporal approach allows precise tracking of when information was known versus when it was recorded, enabling accurate historical queries.
      - `decisionTime` LeftClosedTemporalInterval, required
        - `end` union, required
          - object
            - `kind` 'exclusive', required
            - `limit` string, date-time, required
          - object
            - `kind` 'unbounded', required
        - `start` ClosedTemporalBound, required
          - `kind` 'inclusive', required
          - `limit` string, date-time, required
      - `transactionTime` LeftClosedTemporalInterval, required
        - `end` union, required
          - object
            - `kind` 'exclusive', required
            - `limit` string, date-time, required
          - object
            - `kind` 'unbounded', required
        - `start` ClosedTemporalBound, required
          - `kind` 'inclusive', required
          - `limit` string, date-time, required
  - `properties` PropertyObject, required

## Other responses

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

## Changes

- **2026-07-10** `0f1f205334eb` — 1 breaking, 10 info
  - the `metadata/provenance` response's property type/format changed from ``/`` to `object`/`` for status `200`
  - added the optional property `metadata/provenance/deletedAtDecisionTime` to the response with the `200` status
  - added the optional property `metadata/provenance/deletedAtTransactionTime` to the response with the `200` status
  - added the optional property `metadata/provenance/deletedById` to the response with the `200` status
  - …7 more
- **2026-06-27** `9bba37c8461a` — 2 info
  - added the new optional request property `readOnly`
  - added the optional property `metadata/readOnly` to the response with the `200` status
- **2026-06-25** `d94249d1f3aa` — 3 warning
  - the `entityTypeIds/items/` request property's maxLength was set to `2048`
  - the `properties/value/additionalProperties/oneOf[#/components/schemas/PropertyValueWithMetadata]/metadata/dataTypeId/allOf[#/components/schemas/VersionedUrl -> subschema #1: Versioned URL]/` request property's maxLength was set to `2048`
  - the `properties/value/additionalProperties/oneOf[#/components/schemas/PropertyValueWithMetadata]/metadata/originalDataTypeId/allOf[#/components/schemas/VersionedUrl -> subschema #1: Versioned URL]/` request property's maxLength was set to `2048`
- …earlier changes not shown

[Full history](https://skmtc.dev/hashintel/apis/graph/changes/entities/post.md)

---

[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)