catalog.entities.create

Create a new entity in your software catalog.

Facts


Method	`POST https://api.getdx.com/catalog.entities.create`
Required scope	`catalog:write:entities`

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`identifier`	`Text`	The user defined unique identifier for the entity.
`type`	`Text`	The identifier of the entity type.

Optional arguments

Name	Type	Description
`name`	`Text`	The name of the entity.
`description`	`Text`	The description of the entity.
`owner_team_ids`	`Array<Text>`	The IDs owner teams assigned to the entity.
`owner_user_ids`	`Array<Text>`	The IDs owner users assigned to the entity.
`properties`	`Entity Properties`	Key/Value object of the entity properties and their values on the entity.
`aliases`	`Aliases`	Key/Value object of the aliases assigned to the entity.
`relations`	`Relations`	Key/Value object of the relations and its entities.

Example request

This is a typical request:

curl -X POST https://api.getdx.com/catalog.entities.create \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  --data '{
    "type": "service",
    "name": "www",
    "identifier": "dx-marketing-site",
    "description": "The main DX marketing site",
    "owner_team_ids": ["MzI1NTk"],
    "properties": {
      "Language": ["Ruby", "HTML", "Shell"]
    },
    "aliases": {
      "github_repo": [
        {"identifier": "671150935"}
      ]
    }
  }'

Example response

This is a typical success response:

{
  "ok": true,
  "entity": {
    "created_at": "2025-01-02 20:48:45.77969",
    "updated_at": "2025-01-02 20:48:45.77969",
    "type": "service",
    "name": "www",
    "identifier": "dx-marketing-site",
    "description": "The main DX marketing site",
    "owner_teams": [{ "id": "MzI1NTk", "name": "Front-end" }],
    "properties": {
      "Language": ["Ruby", "HTML", "Shell"]
    },
    "aliases": {
      "github_repo": [
        {
          "identifier": "671150935",
          "name": "get-dx/www"
        }
      ]
    }
  }
}

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok param in the response.

Error	Description
`not_authed`	No authentication token provided.
`invalid_auth`	Some aspect of authentication cannot be validated.

Legacy path

This method is temporarily still available at the following legacy path:

POST https://api.getdx.com/entities.create