# Entities

APIs for managing catalog Entities which represent the core components of your system. Entities can represent services, APIs, user groups, resources, and more. These endpoints allow you to create, retrieve, update, delete, and query entities across different scopes.

## Create an Entity

 - [POST /v1/entities](https://apidocs.harness.io/openapi-merged/entities/create-entity.md): 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.

## Get Entities

 - [GET /v1/entities](https://apidocs.harness.io/openapi-merged/entities/get-entities.md): Retrieves a paginated list of Entities based on the provided filters.  This endpoint supports comprehensive filtering options to help you find  specific entities across different scopes, kinds, and other properties. The response includes pagination metadata and counts for owned and favorite entities.

## Get entities by refs

 - [POST /v1/entities/by-refs](https://apidocs.harness.io/openapi-merged/entities/get-entities-by-refs.md): Fetches entities matching the entity references specified in the request body, in conjunction with other provided filters.

## Import an Entity from Git

 - [POST /v1/entities/import](https://apidocs.harness.io/openapi-merged/entities/import-entity.md): Imports a new Entity from Git in the specified scope (Account, Organization, or Project).

## Move an Entity

 - [POST /v1/entities/move/{scope}/{kind}/{identifier}](https://apidocs.harness.io/openapi-merged/entities/move-entity.md): Move an existing Inline entity to Remote.

## Update GitMetadata for Remote Entities

 - [PUT /v1/entities/git-metadata/{scope}/{kind}/{identifier}](https://apidocs.harness.io/openapi-merged/entities/update-git-metadata.md): Update GitMetadata for Remote Entities

## Convert Entity Format

 - [POST /v1/entities/convert/{option}](https://apidocs.harness.io/openapi-merged/entities/convert-entity.md): Converts entity YAML between Backstage and Harness formats. This is useful when  migrating entities between systems or when standardizing entity definitions across different platforms. The conversion preserves all semantic information while adapting to the target format conventions.

## Update an Entity

 - [PUT /v1/entities/{scope}/{kind}/{identifier}](https://apidocs.harness.io/openapi-merged/entities/update-entity.md): Updates an existing Entity identified by its scope, kind, and identifier. All fields in the entity definition will be replaced with the new values provided in the request. This operation is idempotent and will create the entity if it doesn't already exist.

## Delete an Entity

 - [DELETE /v1/entities/{scope}/{kind}/{identifier}](https://apidocs.harness.io/openapi-merged/entities/delete-entity.md): Permanently removes an Entity identified by its scope, kind, and identifier from the system. This operation cannot be undone, so use it with caution. Any references to the deleted entity from other entities will become invalid.

## Get Entity Details

 - [GET /v1/entities/{scope}/{kind}/{identifier}](https://apidocs.harness.io/openapi-merged/entities/get-entity.md): Retrieves the complete details of an Entity identified by its scope, kind, and identifier, including its YAML definition, metadata, and relationships with other entities. This endpoint provides the most comprehensive view of a specific entity.

## Get Entity Kinds

 - [GET /v1/entities/kinds](https://apidocs.harness.io/openapi-merged/entities/get-entities-kinds.md): Returns a list of all supported Entity Kinds along with their display names,  descriptions, and counts. This is useful for populating filter dropdowns in UIs and for understanding what kinds of entities are available in the system.

## Get Entity Filter Options

 - [GET /v1/entities/filters](https://apidocs.harness.io/openapi-merged/entities/get-entities-filters.md): Returns the available filter options that can be used when querying entities. This helps in building dynamic filter UIs for entity exploration and discovery. The response includes filter names and their possible values based on the current entities in the system.

## Get Entities Filters By Query

 - [POST /v1/entities/filters](https://apidocs.harness.io/openapi-merged/entities/get-entities-filters-by-query.md): Returns the available filter options that can be used when querying entities  based on the provided query.This helps in building dynamic filter UIs for entity  exploration and discovery.The response includes filter names and their possible  values based on the current entities in the system.

## Get Entity JSON Schema

 - [GET /v1/entities/json-schema](https://apidocs.harness.io/openapi-merged/entities/get-json-schema.md): Returns the JSON Schema for validating Entity definitions. This is useful for client-side validation before submitting entity creation or update requests. The schema can be filtered by entity kind to get specific validation rules.