> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/6/release-notes/deprecations/retrieve-references-endpoint-replaced/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Retrieve references endpoint replaced

> Notice that the /references-to endpoint is deprecated in Platform 6 and replaced by the /discoverReferences endpoint, with migration examples.

## Deprecation notice

Beginning with the Platform 6 release, the `/references-to` endpoint is deprecated in favor of the `/discoverReferences` endpoint.

## Retrieve references prior to Platform 6

In early versions of Itential Platform (IP/2022.1 through IP/2023.2), the `/references-to` endpoint was used to retrieve assets that reference a target asset. The endpoint requires two query parameters: `target-type` and `target-identifiers`.

The examples below demonstrate a proper GET request to `/references-to` and the expected response. In this example, the target asset is a workflow named `childWorkflow` that is referenced by two other workflows named `parentWorkflow1` and `parentWorkflow2`.

### GET request

```
/automation-studio/references-to?target-type=workflow&target-identifiers=a5dd53e1-0459-4616-bbe3-50b29da3a299
```

### Response

```json
{
    "referencesByTarget": [
        {
            "target": {
                "identifier": "a5dd53e1-0459-4616-bbe3-50b29da3a299",
                "type": "workflow",
                "name": "childWorkflow"
            },
            "totalReferencingInstances": 2,
            "totalReferences": 2,
            "references": [
                {
                    "type": "workflow",
                    "_id": "56cb9387-2238-400f-9068-6e45e8bec241",
                    "name": "parentWorkflow1",
                    "canvasVersion": 3,
                    "referencePaths": [
                        "tasks.b700.variables.incoming.workflow"
                    ]
                },
                {
                    "type": "workflow",
                    "_id": "96e76283-de19-4085-bb90-d8563d7a5985",
                    "name": "parentWorkflow2",
                    "canvasVersion": 3,
                    "referencePaths": [
                        "tasks.9c41.variables.incoming.workflow"
                    ]
                }
            ]
        }
    ]
}
```

`/references-to` can only look "upward." In a child-parent relationship like this example, running `/references-to` on one of the parent workflows returns no assets, since nothing is referencing either of them.

## Retrieve references in Platform 6 and later

With the Platform 6 release, the `/discoverReferences` endpoint provides a wider range of functionality for retrieving relevant assets for a particular asset, including projects. With `/discoverReferences`, you can specify the direction to search relative to the target asset (`up`, `down`, or `all`) and whether the search should be executed recursively past just one layer up or down (`recursive: true` or `false`).

This endpoint fully encompasses the designed functionality of `/references-to`. The previous example can be reproduced with `/discoverReferences` as shown below.

### POST request

`/automation-studio/discoverReferences`

With the following body:

```json
{
    "resourceIdentifiers": [
        {
            "resourceType": "workflow",
            "resourcePointer": "name",
            "resourceId": "childWorkflow"
        }
    ],
    "includeResources": false,
    "recursive": false,
    "include": {
        "workflow": "up"
    }
}
```

In this example, only workflow references are searched, but any of the asset tags listed in the `metadata.ignore` of the response can be added to the `include` property with a specified direction (`up`, `down`, or `all`).

### Response

A data array containing the root resource and the retrieved assets:

```json
{
    "message": "Successfully discovered references",
    "data": [
        {
            "resourceType": "workflow",
            "resourcePointer": "/_id",
            "resourceId": "a5dd53e1-0459-4616-bbe3-50b29da3a299",
            "parents": [
                {
                    "resourceType": "workflow",
                    "resourcePointer": "/_id",
                    "resourceId": "96e76283-de19-4085-bb90-d8563d7a5985",
                    "parentPointer": "/tasks/9c41/variables/incoming/workflow"
                },
                {
                    "resourceType": "workflow",
                    "resourcePointer": "/_id",
                    "resourceId": "56cb9387-2238-400f-9068-6e45e8bec241",
                    "parentPointer": "/tasks/b700/variables/incoming/workflow"
                }
            ],
            "root": true
        },
        {
            "resourceType": "workflow",
            "resourcePointer": "/_id",
            "resourceId": "56cb9387-2238-400f-9068-6e45e8bec241",
            "parents": []
        },
        {
            "resourceType": "workflow",
            "resourcePointer": "/_id",
            "resourceId": "96e76283-de19-4085-bb90-d8563d7a5985",
            "parents": []
        }
    ],
    "metadata": {
        "ignore": {
            "jsonForm": "all",
            "mopCommandTemplate": "all",
            "mopAnalyticTemplate": "all",
            "transformation": "all",
            "template": "all",
            "goldenConfig": "all",
            "compliancePlan": "all",
            "resourceModel": "all",
            "automation": "all",
            "trigger": "all",
            "form": "all",
            "configParser": "all",
            "configSpec": "all",
            "deviceBackup": "all",
            "deviceGroup": "all",
            "group": "all",
            "integrationModel": "all",
            "jsonSpec": "all",
            "project": "all",
            "role": "all",
            "serverProfile": "all",
            "serviceConfig": "all",
            "tag": "all",
            "user": "all"
        }
    }
}
```

If you set `includeResources` to `true` in the POST request body, each item in the data array will include a `resource` property containing the entire data object for that asset.

### Enable the recursive property

If you add another workflow named `grandparentWorkflow` that references `parentWorkflow1` and switch the `recursive` property to `true`, the response includes `grandparentWorkflow` even though it does not directly reference `childWorkflow` — it is found through the recursive upward search.

**Response:**

```json
{
    "message": "Successfully discovered references",
    "data": [
        {
            "resourceType": "workflow",
            "resourcePointer": "/_id",
            "resourceId": "a5dd53e1-0459-4616-bbe3-50b29da3a299",
            "parents": [
                {
                    "resourceType": "workflow",
                    "resourcePointer": "/_id",
                    "resourceId": "96e76283-de19-4085-bb90-d8563d7a5985",
                    "parentPointer": "/tasks/9c41/variables/incoming/workflow"
                },
                {
                    "resourceType": "workflow",
                    "resourcePointer": "/_id",
                    "resourceId": "56cb9387-2238-400f-9068-6e45e8bec241",
                    "parentPointer": "/tasks/b700/variables/incoming/workflow"
                }
            ],
            "root": true
        },
        {
            "resourceType": "workflow",
            "resourcePointer": "/_id",
            "resourceId": "56cb9387-2238-400f-9068-6e45e8bec241",
            "parents": [
                {
                    "resourceType": "workflow",
                    "resourcePointer": "/_id",
                    "resourceId": "9d0784a6-c3a9-4879-bdbc-07c46ade39eb",
                    "parentPointer": "/tasks/2372/variables/incoming/workflow"
                }
            ]
        },
        {
            "resourceType": "workflow",
            "resourcePointer": "/_id",
            "resourceId": "96e76283-de19-4085-bb90-d8563d7a5985",
            "parents": []
        },
        {
            "resourceType": "workflow",
            "resourcePointer": "/_id",
            "resourceId": "9d0784a6-c3a9-4879-bdbc-07c46ade39eb",
            "parents": []
        }
    ],
    "metadata": {
        "ignore": { }
    }
}
```

> Notice that the /references-to endpoint is deprecated in Platform 6 and replaced by the /discoverReferences endpoint, with migration examples.