---
title: "Retrieve the incoming references for items."
method: POST
path: "/authoring/v1/references/incoming"
tags: ["Authoring reference"]
---

# Retrieve the incoming references for items.

`POST /authoring/v1/references/incoming`

Use the `/references/incoming` endpoint to retrieve incoming references for items. This endpoint allows batch lookups by allowing multiple items to be looked at the same time
### Examples: ###
#### A simple lookup of the incoming references for one item ####

The results are returned in a key value format with the `references` field where the key is the content hub ID of the item.

In Graph terminology, each element in the references object is a Node and the array of IDs in the `included` array on each Node is an incoming edge to another node.
##### Request: #####
~~~
   {
     "root": "content:3e01a155-458e-4428-b24f-d91bfdd2c991"
   }
~~~
##### Response: #####
~~~
{
   "references": {
       "content:3e01a155-458e-4428-b24f-d91bfdd2c991": [
           {
               "uid": "content:7a061c8b-7fef-4fc9-89b0-6255f09697c6",
               "id": "7a061c8b-7fef-4fc9-89b0-6255f09697c6",
               "classification": "content",
               "metadata": {
                   "name": "Clean design"
               }
           },
           {
               "uid": "content:d01c64ee-0927-457a-a1e8-809c22a1f5cf",
               "id": "d01c64ee-0927-457a-a1e8-809c22a1f5cf",
               "classification": "content",
               "metadata": {
                   "name": "Editor's choice list sample"
               }
           }
       ]
   }
}
~~~
#### Multiple items can be looked up at once by specifying multiple roots ####
Note: Items are not duplicated twice in the references map. It is just a key value of content hub ID to data.
##### Request: #####
~~~
{
    "roots":[
       "content:3e01a155-458e-4428-b24f-d91bfdd2c991",
       "content:2d81b7e0-9a01-42aa-8c2a-b181d1abde8f",
       "page:9f32901d-95e5-4c2a-b136-a92bd2f370ae"
    ]
}
~~~
##### Response: #####
~~~
 {
     "references": {
         "content:3e01a155-458e-4428-b24f-d91bfdd2c991": [
             {
                 "uid": "content:7a061c8b-7fef-4fc9-89b0-6255f09697c6",
                 "id": "7a061c8b-7fef-4fc9-89b0-6255f09697c6",
                 "classification": "content",
                 "metadata": {
                     "name": "Clean design"
                 }
             },
             {
                 "uid": "content:d01c64ee-0927-457a-a1e8-809c22a1f5cf",
                 "id": "d01c64ee-0927-457a-a1e8-809c22a1f5cf",
                 "classification": "content",
                 "metadata": {
                     "name": "Editor's choice list sample"
                 }
             }
         ],
         "content:2d81b7e0-9a01-42aa-8c2a-b181d1abde8f": [
             {
                 "uid": "content:3872b3c8-f0f4-4eb4-8192-c6952cd8fd00",
                 "id": "3872b3c8-f0f4-4eb4-8192-c6952cd8fd00",
                 "classification": "content",
                 "metadata": {
                     "name": "Home"
                 }
             },
             {
                 "uid": "content:a05c4497-8d13-4a3a-8624-fcf48fad6288",
                 "id": "a05c4497-8d13-4a3a-8624-fcf48fad6288",
                 "classification": "content",
                 "metadata": {
                     "name": "Search results sample"
                 }
             },
             {
                 "uid": "content:ccc36bbc-791c-4212-b9e2-94b25080f36d:draft",
                 "id": "ccc36bbc-791c-4212-b9e2-94b25080f36d:draft",
                 "classification": "content",
                 "metadata": {
                     "name": "MyTestPage"
                 }
             }
         ],
         "page:9f32901d-95e5-4c2a-b136-a92bd2f370ae": []
     }
 }
~~~
#### Query on multiple roots with limit ####
##### Request: #####
~~~
 {
    "limit":1,
    "roots":[
       "content:3e01a155-458e-4428-b24f-d91bfdd2c991",
       "content:2d81b7e0-9a01-42aa-8c2a-b181d1abde8f",
       "page:9f32901d-95e5-4c2a-b136-a92bd2f370ae"
    ]
 }
~~~
##### Response: #####
~~~
 {
     "references": {
         "content:3e01a155-458e-4428-b24f-d91bfdd2c991": [
             {
                 "uid": "content:7a061c8b-7fef-4fc9-89b0-6255f09697c6",
                 "id": "7a061c8b-7fef-4fc9-89b0-6255f09697c6",
                 "classification": "content",
                 "metadata": {
                     "name": "Clean design"
                 }
             }
         ],
         "content:2d81b7e0-9a01-42aa-8c2a-b181d1abde8f": [
             {
                 "uid": "content:3872b3c8-f0f4-4eb4-8192-c6952cd8fd00",
                 "id": "3872b3c8-f0f4-4eb4-8192-c6952cd8fd00",
                 "classification": "content",
                 "metadata": {
                     "name": "Home"
                 }
             }
         ],
         "page:9f32901d-95e5-4c2a-b136-a92bd2f370ae": []
     }
 }
~~~
<br />User roles: admin, manager, editor, viewer

## Request body

- object
  - `limit` integer — maximum number of references return for each item.
  - `excludeRoots` boolean — excludes the references that are already in the requested roots.
  - `excludeSoftReferences` boolean — whether to exclude soft incoming references.
  - `root` string
  - `roots` string[]

## Response `200`

Successfully returns the fetched incoming references for given items.

- object
  - `references` object

## Other responses

- `429` — Too Many Requests, the server has reached a limit, the request must be sent again at a later time.
- `default` — Unexpected error.

---

[API](https://skmtc.net/goacoustic/apis/acoustic-content-api.md) · [All operations](https://skmtc.net/goacoustic/apis/acoustic-content-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/goacoustic/acoustic-content-api/revisions/677305266d89/schema)