Unified Catalog Topology Query¶

POST /api/v1/unified_catalog/topology/query

Overview¶

Query the topology relationships of the Unified Catalog.

Body Request Parameters¶

Parameter	Type	Description
entityType	string	Entity type code; required when `filters` or `orderBy` involves health fields Allow empty: False
urn	string	Focus entity URN Allow empty: False
providers	array	List of source types Allow empty: False
relationTypes	array	List of relationship types, currently mainly `links` and `contains` Allow empty: False
orderBy	string	Sort field for the starting entity; `entityType` must be provided when using health fields Allow empty: False
filters	json	Entity filter fields, supports any field in `attributes` Allow empty: False
groupByFields	array	Multi-level grouping by array order; `entityType` reads the top-level field of the entity, other fields read from `attributes` Allow empty: False
search	string	Search keyword Allow empty: False

Parameter Supplementary Notes¶

Request Parameter Details

Parameter	Type	Required	Description
entityType	string	Required for health queries	Starting entity type code; must be uniquely specified when `filters/orderBy` involves health fields
urn	string	No	Focus entity URN
providers	array[string]	No	List of source types for the starting entity
relationTypes	array[string]	No	List of relationship types to return
orderBy	string	No	Sort field for the starting entity; `entityType` must be provided when using health fields
filters	json	No	Filter conditions for the starting entity, supports any field in `attributes` and top-level health fields
groupByFields	array[string]	No	List of fields for grouping topology entity nodes
search	string	No	Search keyword for the starting entity

Usage Notes for groupByFields

Performs multi-level grouping by array order, e.g., ["project","env","serviceType"].
entityType is read from the top-level field of the entity; other fields are read from the entity's attributes.
Grouping is based on entity nodes in the topology results, not on relationship edges.
groupInfo.groupByLayers[].groupByData.*.data[] and groupInfo.noGroupData[] return healthScore / healthStatus; healthScore preserves the actual 0 and null.

Calling Notes

entityType, providers, search, urn, and filters only affect the determination of the starting entity.
When filters involves healthStatus/healthScore/healthUpdateAt/brokenComponents and snake_case aliases, or when orderBy uses health fields, entityType must be provided. Studio filters and sorts based on the effective closed state, not directly trusting historical health values pending asynchronous cleanup in kodo.
The response structure is fixed as items + groupInfo.
In the platform's topology query results, the attributes of entity summaries at both ends of a relationship are returned in full.
Both ends of the relationship and grouped entities always return the health toggle and results. All types are computed based on the effective configuration of the entity and type, independent of the backend readiness cleanup progress.

Request Example¶

curl 'https://openapi.truewatch.com/api/v1/unified_catalog/topology/query' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"entityType":"service","filters":{"project":["demo"]},"groupByFields":["project"]}'

Response¶

{
    "code": 200,
    "content": {
        "items": [
            {
                "relationType": "links",
                "sourceUrn": "urn:system:default:core",
                "targetUrn": "urn:service:default:demo",
                "sourceUrnInfo": {
                    "urn": "urn:system:default:core",
                    "attributes": {
                        "project": "demo"
                    },
                    "healthConfig": {
                        "mode": "inherit"
                    },
                    "healthEnabled": true,
                    "healthScore": 67,
                    "healthStatus": "warning",
                    "healthUpdateAt": "2026-08-11 22:40:00"
                },
                "targetUrnInfo": {
                    "urn": "urn:service:default:demo",
                    "attributes": {
                        "project": "demo",
                        "env": "prod"
                    },
                    "healthConfig": {},
                    "healthEnabled": false,
                    "healthScore": null,
                    "healthStatus": "unknown",
                    "healthUpdateAt": null
                }
            }
        ],
        "groupInfo": {
            "groupByLayers": [
                {
                    "groupByField": "project",
                    "groupByData": {
                        "demo": {
                            "data": [
                                {
                                    "urn": "urn:system:default:core",
                                    "entityType": "system",
                                    "healthScore": 67,
                                    "healthStatus": "warning",
                                    "healthConfig": {
                                        "mode": "inherit"
                                    },
                                    "healthEnabled": true,
                                    "attributes": {
                                        "project": "demo"
                                    }
                                },
                                {
                                    "urn": "urn:service:default:demo",
                                    "entityType": "service",
                                    "healthScore": null,
                                    "healthStatus": "unknown",
                                    "healthConfig": {},
                                    "healthEnabled": false,
                                    "attributes": {
                                        "project": "demo",
                                        "env": "prod"
                                    }
                                }
                            ]
                        }
                    }
                }
            ],
            "noGroupData": []
        }
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-XXXX"
}