catalog.entities.update

Update an entity in your software catalog.

Facts


Method	`POST https://api.getdx.com/catalog.entities.update`
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.

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 of teams assigned as entity owners.
`owner_user_ids`	`Array<Text>`	The DX user IDs assigned as entity owners.
`owner_user_emails`	`Array<Text>`	The email addresses assigned as entity owners. Each email must match a user in the account.
`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. Each alias entry can use `identifier` or `lookup`.

Example request

This is a typical request:

curl -X POST https://api.getdx.com/catalog.entities.update \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  --data '{
    "identifier": "www",
    "name": "Marketing Site",
    "description": "The main DX marketing site",
    "owner_team_ids": ["MzI1NTk"],
    "owner_user_emails": ["ada@example.com"],
    "properties": {
      "language": ["Ruby", "HTML", "Shell"]
    },
    "aliases": {
      "github_repo": [
        {"lookup": "get-dx/www"}
      ]
    }
  }'

Example response

This is a typical success response:

{
  "ok": true,
  "entity": {
    "identifier": "www",
    "created_at": "2025-01-02 20:48:45.77969",
    "updated_at": "2025-01-02 20:48:45.77969",
    "type": "service",
    "name": "Marketing Site",
    "description": "The main DX marketing site",
    "owner_teams": [{ "id": "MzI1NTk", "name": "Front end" }],
    "owner_users": [{ "id": "MzI1NYn", "email": "ada@example.com" }],
    "properties": {
      "language": ["Ruby", "HTML", "Shell"]
    },
    "aliases": {
      "github_repo": [
        {
          "identifier": "671150935",
          "name": "get-dx/www",
          "url": "https://github.com/get-dx/www"
        }
      ]
    }
  }
}

Use owner_user_emails to assign user owners by email address instead of DX user ID. The value must be an array of strings. Emails are matched case-insensitively after trimming surrounding whitespace, and each email must match a user in the account.

When you send owner_user_emails or owner_user_ids, the provided users become the full set of user owners for the entity. Omit both fields to preserve existing user owners. You can combine owner_user_emails with owner_user_ids; duplicate owners are stored once.

Removing Entity Properties

To remove an entity property, update or upsert a catalog entity with the desired property to remove and set null as the value. Omitted properties will not be affected.

Example:

{
  "language": null
}

Setting Aliases

When setting aliases, each alias entry must include either identifier or lookup. Use identifier when you know the external system’s unique identifier. Use lookup when you want the API to find a single matching alias entry by name or identifier from Data Cloud.

Example Request

{
  "github_repo": [
    {
      "lookup": "get-dx/payment-processing"
    }
  ]
}

Example Response

{
  "github_repo": [
    {
      "identifier": "671150935",
      "name": "get-dx/payment-processing",
      "url": "https://github.com/get-dx/payment-processing"
    }
  ]
}

Errors

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.
`alias_lookup_ambiguous`	An alias `lookup` matched multiple entries for the alias type. Use a more specific lookup.
`owner_user_validation_error`	An `owner_user_ids` value is malformed, or an `owner_user_emails` value is not an array of non-empty strings or cannot be matched to users in the account.

Legacy path

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

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