Get Advisor Tree (Reserved)

RESERVED: The keyword RESERVED annotation means that the API is available for use but is not yet part of the officially supported specification. Its behavior, interface, or output may change in future releases without backward compatibility guarantees.

Expands the requested parent step IDs (from GET /steps, or a BRANCHING_STEP child ID returned by a previous call to this endpoint) into their immediate children, grouped by requested parent. Do not pass a TASK child ID back into this endpoint; a TASK ID is an AdvisorRule ID, not a strategy ID, and this endpoint has nothing further to expand for it — use /rules/:id/details for its guidance metadata. Retrieving its affected objects (/rules/:id/objects) is not yet implemented.

URI

POST /rest/applications/{application}/advisors/tree

Use the existing authentication and x-user-tenant header. The application name must be URL-encoded when necessary and cannot contain quote or backquote characters. This endpoint is available in Unified builds only.

Request body

{
  "ids": [200],
  "migration": "Move to AWS",
  "version": "3.6.0"
}

Field	Meaning
`ids`	One or more parent step IDs to expand (from `GET /steps` or a `BRANCHING_STEP` child of a previous call); must be non-empty and contain only positive IDs
`migration`	The migration name returned as `migration` from `GET /steps`; required
`version`	The Advisor version returned from `GET /steps`; required

Response

Illustrative response (IDs and counts are examples):

{
  "results": [
    {
      "id": 200,
      "step": "Database Migration to AWS Services",
      "migration": "Move to AWS",
      "version": "3.6.0",
      "rationale": "Why this step exists.",
      "tasks": [
        {
          "id": 201,
          "step": "Database drivers",
          "label": "BRANCHING_STEP",
          "count": 6,
          "effort": "moderate",
          "rationale": "Guidance for this branch.",
          "nextEfforts": [
            {"effort": "low", "count": 3},
            {"effort": "moderate", "count": 2},
            {"effort": "high", "count": 1}
          ]
        },
        {
          "id": 9001,
          "step": "Avoid deprecated driver API",
          "label": "TASK",
          "count": 4,
          "effort": "moderate",
          "rationale": "Guidance for this rule."
        }
      ]
    }
  ]
}

Field	Meaning
`id`	The requested parent’s ID, echoed back
`step`	The requested parent’s own name (e.g. its strategy name)
`migration`	The requested migration, echoed back from the request — not the parent’s own name
`version`	The requested Advisor version
`rationale`	Explanation for the requested parent; omitted when empty
`tasks[].id`	For `label: "BRANCHING_STEP"`, a numeric AdvisorStrategy AipId to pass back into this endpoint. For `label: "TASK"`, a numeric AdvisorRule AipId to pass to `/rules/:id/details` — not a strategy ID
`tasks[].step`	Child step or task name
`tasks[].label`	`BRANCHING_STEP` when the requested parent has further intermediate steps before reaching rules (this child is another strategy to expand); `TASK` when the requested parent directly owns rules (this child is one of those rules, and is terminal — do not call this endpoint with a `TASK` ID)
`tasks[].count`	For `label: "BRANCHING_STEP"`, count of distinct relevant rules beneath the child. For `label: "TASK"`, count of distinct affected objects for that rule — these are different quantities; do not assume one meaning across both labels
`tasks[].effort`	Child effort; missing values default to `low`, matching the service
`tasks[].rationale`	Child explanation; omitted when empty
`tasks[].nextEfforts`	For `label: "BRANCHING_STEP"`, relevant rule counts by effort beneath the child; rules without effort count as low. Omitted for `label: "TASK"` — a terminal rule has no further steps to break down by effort

Requested IDs that do not resolve to a step under the given migration/version return 200 with {"results":[]}, consistent with GET /steps. This includes a step ID that exists but belongs to a different migration’s hierarchy — see the correction below. Standard API errors apply for invalid application identifiers, missing tenants, malformed request bodies (missing/empty ids, migration, or version, or non-positive IDs), and database failures.

This endpoint preserves the service’s rationale selection and its two-branch traversal (branching step vs. terminal task). Unlike the source’s tree response, step and migration are kept separate: the source overloads a single migration field with the parent’s own name, which this API does not reproduce.

A parent that both leads to further steps and directly owns rules produces two raw matches internally (one per traversal case); these are merged into one entry per requested id before the response is built, so a given id never appears twice in results.

Deliberate corrections versus the source query:

migration now also scopes which requested step can be expanded, not just which text the rationale is read from. The source only checks the requested ID against the version, so a valid step ID from a different migration could still be expanded under a migration it does not belong to; it now resolves to {"results":[]} instead.
TASK entries’ affected-object count is now filtered by version, matching every other count in this API. The source’s TASK-count query has no version filter, so an older version’s data for the same rule could inflate the count.
label is derived directly from which traversal case produced the entry, not from labels(node)[0]. Label order on a Neo4j node is not guaranteed, so the source’s approach could non-deterministically misclassify a node carrying more than one label.
Rationale/effort-count queries are batched (one call across every BRANCHING_STEP child in the response, not one call per child) and anchored on the requested ids before checking migration reachability, instead of traversing the whole Advisor hierarchy first. The anchoring change has not been PROFILEd against real data.