catalog.relationEdges.bulkUpsert

Create or update multiple relation edges for a single relation type in your software catalog. Each key in edges is a source entity identifier, and each value is a corresponding array of target entity identifiers.

Validation and cardinality rules match catalog.relationEdges.add for every implied source-target pair.

Facts


HTTP Method	`POST https://api.getdx.com/catalog.relationEdges.bulkUpsert`
Scope	`catalog:write:entities`

Arguments

Required arguments

Parameter	Type	Description
`relation_identifier`	`string`	The identifier of the relation type.
`edges`	`object`	Map from source entity identifier (string) to an array of target entity identifiers (strings).

The relation identifier must exist for the account. Every source and target entity identifier must exist and must match the expected entity types for that relation (for example, a relation from service to resource rejects a widget used as a source).

The request must not reference more than 100 relation edges in total (count each source→target pair once). Exceeding that limit returns too_many_edges.

Example request

This is a typical request:

curl -X POST https://api.getdx.com/catalog.relationEdges.bulkUpsert \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  --data '{
    "relation_identifier": "service-depends-on-service",
    "edges": {
      "login-frontend": ["authn-backend", "feature-flag-backend"],
      "core-frontend": ["messaging-backend", "feature-flag-backend", "payments-backend"]
    }
  }'

In this example, the payload expresses that login-frontend depends on authn-backend and feature-flag-backend, while core-frontend depends on messaging-backend, feature-flag-backend, and payments-backend. The payload includes a total of 5 relation edges, so it meets the limit requirement.

Example response

This is a typical success response:

{
  "ok": true
}

Errors

Error	Description
`not_authed`	No authentication token provided.
`invalid_auth`	Some aspect of authentication cannot be validated.
`invalid_arguments`	Missing required parameters or malformed request body. Error details will indicate the specific issue.
`too_many_edges`	The request implies more than 100 relation edges (sum of target array lengths).
`relation_not_found`	The relation identifier does not exist for the account.
`entity_not_found`	A source or target entity identifier does not exist for the account.
`invalid_cardinality`	Applying the requested edges would violate the cardinality configured on the relation type.
`invalid_entity_type`	A source or target entity identifier is of the wrong entity type for the relation (e.g. passing a `widget` identifier where a `service` is expected).

This table lists only the common expected errors for this method. You should also expect standard service availability errors.