# Create an Entity

Creates a new Entity in the specified scope (Account, Organization, or Project).  Entities are the core components of the catalog system and can represent various  resources such as services, APIs, user groups, and more. Each entity has a specific  kind and type that defines its purpose in the system.

Endpoint: POST /v1/entities
Version: 1.0
Security: x-api-key

## Query parameters:

  - `orgIdentifier` (string)
    Unique identifier of the organization within the account

  - `projectIdentifier` (string)
    Unique identifier of the project within the organization

  - `convert` (boolean)
    When set to true, converts Backstage style YAML to Harness entity YAML format

  - `dry_run` (boolean)
    When set to true, validates the entity creation without actually creating it

## Header parameters:

  - `Harness-Account` (string)
    Identifier field of the account the resource is scoped to.

## Request fields (application/json):

  - `yaml` (string, required)
    Entity YAML (to be passed as a String).

  - `git_details` (object)
    Contains parameters related to creating an Entity for Git Experience.

  - `git_details.branch_name` (string)
    Name of the branch.

  - `git_details.file_path` (string)
    File path of the Entity in the repository.

  - `git_details.commit_message` (string)
    Commit message used for the merge commit.

  - `git_details.base_branch` (string)
    Name of the default branch (this checks out a new branch titled by branch_name).

  - `git_details.connector_ref` (string)
    Identifier of the Harness Connector used for CRUD operations on the Entity.

  - `git_details.store_type` (string)
    Specifies whether the Entity is to be stored in Git or not.
    Enum: "INLINE", "REMOTE"

  - `git_details.repo_name` (string)
    Name of the repository.

  - `git_details.is_harness_code_repo` (boolean)
    Is Git Experience repo harness code.

## Response 201 fields (application/json):

  - `identifier` (string, required)
    Unique identifier of the entity within its scope and kind

  - `entity_ref` (string, required)
    Full entity reference in the format scope/kind/identifier

  - `orgIdentifier` (string)
    Identifier of the organization that the entity belongs to

  - `org_name` (string)
    Display name of the organization that the entity belongs to

  - `projectIdentifier` (string)
    Identifier of the project that the entity belongs to

  - `project_name` (string)
    Display name of the project that the entity belongs to

  - `scope` (string, required)
    Scope of the entity (account, organization, or project level)
    Enum: "ACCOUNT", "ORGANIZATION", "PROJECT"

  - `referenceType` (string, required)
    Type of reference for the entity (inline definition or Git-sourced)
    Enum: "INLINE", "GIT"

  - `kind` (string, required)
    Kind of the entity (defines its core purpose)
    Enum: "api", "component", "group", "resource", "user", "workflow"

  - `type` (string)
    Type of the entity within its kind (e.g., Service, Website)

  - `name` (string)
    Display name of the entity

  - `description` (string)
    Descriptive text about the entity

  - `owner` (string)
    Owner reference for the entity (user or group)

  - `tags` (array)
    Tags associated with the entity for categorization

  - `lifecycle` (string)
    Lifecycle stage of the entity (e.g., experimental, production)

  - `metadata` (object)
    Additional metadata associated with the entity

  - `git_details` (object)
    Git Experience related details of the Entity.

  - `git_details.branch_name` (string)
    Name of the branch.

  - `git_details.file_path` (string)
    File path of the Entity in the repository.

  - `git_details.file_url` (string)
    File URL of the Entity.

  - `git_details.commit_message` (string)
    Commit message used for the merge commit.

  - `git_details.object_id` (string)
    Object identifier (for Github only).

  - `git_details.base_branch` (string)
    Name of the default branch (this checks out a new branch titled by branch_name).

  - `git_details.commit_id` (string)
    Commit identifier.

  - `git_details.connector_ref` (string)
    Identifier of the Harness Connector used for CRUD operations on the Entity.

  - `git_details.store_type` (string)
    Specifies whether the Entity is to be stored in Git or not.
    Enum: "INLINE", "REMOTE"

  - `git_details.repo_name` (string)
    Name of the repository.

  - `git_details.repo_url` (string)
    Repository URL of the Entity.

  - `git_details.is_harness_code_repo` (boolean)
    Is Git Experience repo harness code.

  - `cache_response_data` (object)

  - `cache_response_data.cache_state` (string)
    Tells the state of cache.
    Enum: "VALID_CACHE", "STALE_CACHE", "UNKNOWN"

  - `cache_response_data.ttl_left` (integer)
    Time left till cache expriry.

  - `cache_response_data.last_updated_at` (integer)
    Time when the cache was last updated at.

  - `cache_response_data.is_sync_enabled` (boolean)

  - `entity_validity_details` (object)

  - `entity_validity_details.is_valid` (boolean)

  - `entity_validity_details.error_messages` (array)

  - `scorecards` (object)
    Scorecard information for the entity

  - `scorecards.average` (number)
    Average score across all scorecards

  - `scorecards.scores` (array)

  - `scorecards.scores.scorecard` (string)
    Name of the scorecard

  - `scorecards.scores.score` (number)
    Numeric score (typically 0-100)

  - `scorecards.scores.total_checks` (number)
    Total number of checks in the scorecard

  - `scorecards.scores.passed_checks` (number)
    Number of checks that passed

  - `yaml` (string, required)
    Complete entity YAML definition

  - `starred` (boolean)
    Whether the entity is marked as a favorite by the current user

  - `status` (array)
    Status information for the entity

  - `status.type` (string)
    Type of status information

  - `status.level` (string)
    Severity level (info, warning, error)

  - `status.message` (string)
    Status message text

  - `groups` (array)
    Groups that the entity belongs to

  - `groups.org_identifier` (string)
    Organization identifier

  - `groups.org_name` (string)
    Organization name

  - `groups.project_identifier` (string)
    Project identifier

  - `groups.project_name` (string)
    Project name

  - `groups.scope` (string)
    Scope level
    Enum: "ACCOUNT", "ORGANIZATION", "PROJECT"

  - `groups.group_identifier` (string)
    Group identifier

  - `groups.group_name` (string)
    Group display name

  - `groups.group_description` (string)
    Group description

  - `groups.group_icon` (string)
    Group icon URL