Harness

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

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.

Securityx-api-key
Request
query Parameters
orgIdentifier
string

Unique identifier of the organization within the account

projectIdentifier
string

Unique identifier of the project within the organization

convert
boolean
Default: false

When set to true, converts Backstage style YAML to Harness entity YAML format

dry_run
boolean
Default: false

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 Body schema: application/json
required

Entity YAML definition provided as a string. The YAML should conform to either the Harness entity format or the Backstage entity format, depending on the operation.

yaml
required
string

Entity YAML definition as a string. Should conform to either the Harness entity format or the Backstage entity format, depending on the operation.

Responses
201

Response containing a complete Entity definition including its metadata, relationships, and YAML representation.

post/v1/entities
Request samples
application/json
{
  • "yaml": "apiVersion: harness.io/v1\nkind: component\ntype: Service\nidentifier: my-sample-service\nname: my-sample-service\nowner: sample-owner\nspec:\n lifecycle: experimental\n ownedBy:\n - group/sample-group\nmetadata:\n description: My Sample service.\n annotations:\n backstage.io/source-location: url:https://github.com/sample/sample/tree/main/harness/sample/\n backstage.io/techdocs-ref: dir:.\n links:\n - title: Website\n url: http://my-sample-website.com\n tags:\n - my-sample\n"
}
Response samples
{
  • "identifier": "string",
  • "entity_ref": "string",
  • "orgIdentifier": "string",
  • "org_name": "string",
  • "projectIdentifier": "string",
  • "project_name": "string",
  • "scope": "ACCOUNT",
  • "referenceType": "INLINE",
  • "kind": "api",
  • "type": "string",
  • "name": "string",
  • "description": "string",
  • "owner": "string",
  • "tags": [
    ],
  • "lifecycle": "string",
  • "metadata": { },
  • "scorecards": {
    },
  • "yaml": "string",
  • "starred": true,
  • "status": [
    ],
  • "groups": [
    ]
}

Get Entities

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.

Securityx-api-key
Request
query Parameters
page
integer

Pagination page number strategy: Specify the page number within the paginated collection related to the number of items in each page

limit
integer <= 100
Default: 10

Maximum number of items to return per page (1-100, default: 10)

sort
string

Parameter on the basis of which sorting is done.

search_term
string

This would be used to filter resources having attributes matching the search term.

scopes
string

Filter entities by specific scopes (account.*, account, account.org, account.org.project, account.orgId, account.orgId.projectId, account.orgId.*)

entity_refs
string

Filter entities by their entity references (comma-separated list in the format of kind:scope/identifier)

owned_by_me
boolean

When true, returns only entities owned by the current user or their groups

favorites
boolean

When true, returns only entities marked as favorites by the current user

kind
string

Filter entities by their kind (e.g., component, api, resource, user, workflow)

type
string

Filter entities by their type (e.g., Service, Website)

owner
string

Filter entities by their owner references

lifecycle
string

Filter entities by their lifecycle stage (e.g., experimental, production)

tags
string

Filter entities by their associated tags (comma-separated list)

header Parameters
Harness-Account
string

Identifier field of the account the resource is scoped to.

Responses
200

Response containing a paginated list of Entities matching the filter criteria, along with pagination metadata and entity counts.

get/v1/entities
Request samples 
Response samples 
[
  • {
    }
]
Convert Entity Format
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.


Securityx-api-key 
Request 
path Parameters
option
required
string
Conversion direction - either convert from Backstage to Harness format or vice versa


 Enum: "backstage-to-harness" "harness-to-backstage"  
header Parameters
Harness-Account
string
Identifier field of the account the resource is scoped to.


 
Request Body schema: application/json
required
Entity YAML definition provided as a string. The YAML should conform to either the  Harness entity format or the Backstage entity format, depending on the operation.


yaml
required
string
Entity YAML definition as a string. Should conform to either the Harness entity format or the Backstage entity format, depending on the operation.


 
Responses 
200
Response containing the converted Entity YAML in the target format (either Backstage or Harness format).


post/v1/entities/convert/{option}
Request samples 
application/json
{
  • "yaml": "apiVersion: harness.io/v1\nkind: component\ntype: Service\nidentifier: my-sample-service\nname: my-sample-service\nowner: sample-owner\nspec:\n  lifecycle: experimental\n  ownedBy:\n    - group/sample-group\nmetadata:\n  description: My Sample service.\n  annotations:\n    backstage.io/source-location: url:https://github.com/sample/sample/tree/main/harness/sample/\n    backstage.io/techdocs-ref: dir:.\n  links:\n    - title: Website\n      url: http://my-sample-website.com\n  tags:\n    - my-sample\n"
}
Response samples 
{
  • "yaml": "string"
}
Update an Entity
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.


Securityx-api-key 
Request 
path Parameters
scope
required
string
Scope of the entity (account, account.orgId, account.orgId.projectId)


 
kind
required
string
Kind of the entity (e.g., component, api, resource, user, workflow)


 
identifier
required
string
Unique identifier of the entity within its scope and kind


 
query Parameters
orgIdentifier
string
Unique identifier of the organization within the account


 
projectIdentifier
string
Unique identifier of the project within the organization


 
header Parameters
Harness-Account
string
Identifier field of the account the resource is scoped to.


 
Request Body schema: application/json
required
Entity YAML definition provided as a string. The YAML should conform to either the  Harness entity format or the Backstage entity format, depending on the operation.


yaml
required
string
Entity YAML definition as a string. Should conform to either the Harness entity format or the Backstage entity format, depending on the operation.


 
Responses 
200
Response containing a complete Entity definition including its metadata, relationships, and YAML representation.


put/v1/entities/{scope}/{kind}/{identifier}
Request samples 
application/json
{
  • "yaml": "apiVersion: harness.io/v1\nkind: component\ntype: Service\nidentifier: my-sample-service\nname: my-sample-service\nowner: sample-owner\nspec:\n  lifecycle: experimental\n  ownedBy:\n    - group/sample-group\nmetadata:\n  description: My Sample service.\n  annotations:\n    backstage.io/source-location: url:https://github.com/sample/sample/tree/main/harness/sample/\n    backstage.io/techdocs-ref: dir:.\n  links:\n    - title: Website\n      url: http://my-sample-website.com\n  tags:\n    - my-sample\n"
}
Response samples 
{
  • "identifier": "string",
  • "entity_ref": "string",
  • "orgIdentifier": "string",
  • "org_name": "string",
  • "projectIdentifier": "string",
  • "project_name": "string",
  • "scope": "ACCOUNT",
  • "referenceType": "INLINE",
  • "kind": "api",
  • "type": "string",
  • "name": "string",
  • "description": "string",
  • "owner": "string",
  • "tags": [
    ],
  • "lifecycle": "string",
  • "metadata": { },
  • "scorecards": {
    },
  • "yaml": "string",
  • "starred": true,
  • "status": [
    ],
  • "groups": [
    ]
}
Delete an Entity
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.


Securityx-api-key 
Request 
path Parameters
scope
required
string
Scope of the entity (account, account.orgId, account.orgId.projectId)


 
kind
required
string
Kind of the entity (e.g., component, api, resource, user, workflow)


 
identifier
required
string
Unique identifier of the entity within its scope and kind


 
query Parameters
orgIdentifier
string
Unique identifier of the organization within the account


 
projectIdentifier
string
Unique identifier of the project within the organization


 
header Parameters
Harness-Account
string
Identifier field of the account the resource is scoped to.


 
Responses 
204
Entity successfully deleted with no content returned


delete/v1/entities/{scope}/{kind}/{identifier}
Request samples 
Get Entity Details
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.


Securityx-api-key 
Request 
path Parameters
scope
required
string
Scope of the entity (account, account.orgId, account.orgId.projectId)


 
kind
required
string
Kind of the entity (e.g., component, api, resource, user, workflow)


 
identifier
required
string
Unique identifier of the entity within its scope and kind


 
query Parameters
orgIdentifier
string
Unique identifier of the organization within the account


 
projectIdentifier
string
Unique identifier of the project within the organization


 
header Parameters
Harness-Account
string
Identifier field of the account the resource is scoped to.


 
Responses 
200
Response containing a complete Entity definition including its metadata, relationships, and YAML representation.


get/v1/entities/{scope}/{kind}/{identifier}
Request samples 
Response samples 
{
  • "identifier": "string",
  • "entity_ref": "string",
  • "orgIdentifier": "string",
  • "org_name": "string",
  • "projectIdentifier": "string",
  • "project_name": "string",
  • "scope": "ACCOUNT",
  • "referenceType": "INLINE",
  • "kind": "api",
  • "type": "string",
  • "name": "string",
  • "description": "string",
  • "owner": "string",
  • "tags": [
    ],
  • "lifecycle": "string",
  • "metadata": { },
  • "scorecards": {
    },
  • "yaml": "string",
  • "starred": true,
  • "status": [
    ],
  • "groups": [
    ]
}
Get Entity Kinds
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.


Securityx-api-key 
Request 
query Parameters
accountIdentifier
required
string
Unique identifier of the account to operate on


 
orgIdentifier
string
Unique identifier of the organization within the account


 
projectIdentifier
string
Unique identifier of the project within the organization


 
header Parameters
Harness-Account
string
Identifier field of the account the resource is scoped to.


 
Responses 
200
Response containing a list of all supported Entity Kinds along with their display names, descriptions, and counts.


get/v1/entities/kinds
Request samples 
Response samples 
[
  • {
    }
]
Get Entity Filter Options
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.


Securityx-api-key 
Request 
query Parameters
accountIdentifier
required
string
Unique identifier of the account to operate on


 
kind
string
Filter entities by their kind (e.g., component, api, resource, user, workflow)


 
scopes
string
Filter entities by specific scopes (account.*, account, account.org, account.org.project, account.orgId, account.orgId.projectId, account.orgId.*)


 
header Parameters
Harness-Account
string
Identifier field of the account the resource is scoped to.


 
Responses 
200
Response containing available filter options that can be used when querying entities, including filter names and their possible values.


get/v1/entities/filters
Request samples 
Response samples 
[
  • {
    }
]
Get Entity JSON Schema
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.


Securityx-api-key 
Request 
query Parameters
kind
string
Filter entities by their kind (e.g., component, api, resource, user, workflow)


 
Responses 
200
Response containing the JSON Schema for validating Entity definitions, which can be used for client-side validation.


get/v1/entities/json-schema
Request samples 
Response samples 
{ }
➔ Next to Catalog Custom Properties