View all methods

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 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.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"],
    "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": {
    "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" }],
    "owner_users": [{ "id": "MzI1NYn", "email": "ada@example.com" }],
    "properties": {
      "Language": ["Ruby", "HTML", "Shell"]
    },
    "aliases": {
      "github_repo": [
        {
          "identifier": "671150935",
          "name": "get-dx/www"
        }
      ]
    }
  }
}

Setting user owners by email

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.

You can combine owner_user_emails with owner_user_ids. Duplicate owners are stored once.

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.

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

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.create