--- title: "Retrieve the outgoing references for an item with the provided ID." method: GET path: "/authoring/v1/references/outgoing/{classification}/{id}" tags: ["Authoring reference"] --- # Retrieve the outgoing references for an item with the provided ID. `GET /authoring/v1/references/outgoing/{classification}/{id}` Use the /references/outgoing/{classification}/{id} endpoint to retrieve outgoing references for an item with the provided ID. The usage is similar to the batch outgoing reference endpoint (/reference/outgoing/) except the parameters are passed through query parameters and only one item can be requested at a time. ### Examples: ### #### A simple lookup of the outgoing references for one item #### The default depth to look for references in an item is `1`. If it is `depth.reached` and there are more references that are found in the item, the result `code` that is returned indicates that there are more references. You can either query at a higher depth or query for all items, which have non empty `excluded` arrays. 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 outgoing edge to another node. ##### Request: ##### ~~~ "{baseURL}/authoring/v1/references/outgoing/content/0e28db52-a916-49ea-9bde-9f014bc6f691" ~~~ ##### Response: ##### ~~~ { "root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "result": { "status": "ok", "depth": 1 }, "next": { "roots": [ [ "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0" ] ], "filters": { "filterType": "include", "classifications": [], "statuses": [] }, "depth": 1, "fl": [] }, "references": { "content:81baa86e-ee94-45de-8e90-b23d8ef84e45": { "id": "81baa86e-ee94-45de-8e90-b23d8ef84e45", "classification": "content", "included": [], "excluded": [ "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0" ] }, "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca": { "id": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "classification": "content-type", "included": [], "excluded": [] }, "content:0e28db52-a916-49ea-9bde-9f014bc6f691": { "id": "0e28db52-a916-49ea-9bde-9f014bc6f691", "classification": "content", "included": [ "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "content:81baa86e-ee94-45de-8e90-b23d8ef84e45" ], "excluded": [] } } } ~~~ #### A simple lookup of the outgoing references for one item with metadata #### Instead of just getting a graph of content hub IDs, you can also request to retrieve metadata for each item. The metadata returned are the default fields that are returned by authoring search API (`authoring/v1/search`). ##### Request: ##### ~~~ { "{baseURL}/authoring/v1/references/outgoing/content/0e28db52-a916-49ea-9bde-9f014bc6f691?include=metadata" } ~~~ ##### Response: ##### ~~~ { "root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "result": { "status": "ok", "depth": 1 }, "references": { "content:81baa86e-ee94-45de-8e90-b23d8ef84e45": { "id": "81baa86e-ee94-45de-8e90-b23d8ef84e45", "classification": "content", "metadata": { "id": "content:81baa86e-ee94-45de-8e90-b23d8ef84e45", "name": "Slide7", "classification": "content", "type": "Slide", "typeId": "cad2e430-beed-40d0-bb57-1c86c4f912c0", "locale": "en", "lastModified": "2017-06-09T01:21:31.369Z", "lastModifier": "Thomas Watson", "lastModifierId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "created": "2017-06-09T01:21:17.630Z", "creator": "Thomas Watson", "creatorId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "status": "ready" }, "included": [], "excluded": [ "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0" ] }, "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca": { "id": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "classification": "content-type", "metadata": { "id": "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "name": "Slideshow", "classification": "content-type", "lastModified": "2017-06-09T01:18:08.301Z", "lastModifier": "Thomas Watson", "lastModifierId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "created": "2017-06-09T01:15:56.578Z", "creator": "Thomas Watson", "creatorId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "status": "ready" }, "included": [], "excluded": [] }, "content:0e28db52-a916-49ea-9bde-9f014bc6f691": { "id": "0e28db52-a916-49ea-9bde-9f014bc6f691", "classification": "content", "metadata": { "id": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "name": "MySlideshow", "classification": "content", "type": "Slideshow", "typeId": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "locale": "en", "lastModified": "2017-06-09T01:22:34.049Z", "lastModifier": "Thomas Watson", "lastModifierId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "created": "2017-06-09T01:18:58.426Z", "creator": "Thomas Watson", "creatorId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "status": "ready" }, "included": [ "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "content:81baa86e-ee94-45de-8e90-b23d8ef84e45" ], "excluded": [] } } } ~~~ #### Using fl parameter to request specific metadata fields #### Just like the search API, the `fl` parameter can be used to request specific fields, which include the `document` field, which is the entire API representation of the item. Note: When the `fl` parameter is used, the `id` field is also always returned. ##### Request: ##### ~~~ { "{baseURL}/authoring/v1/references/outgoing/content/0e28db52-a916-49ea-9bde-9f014bc6f691?include=metadata&fl=name" } ~~~ ##### Response: ##### ~~~ { "root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "result": { "status": "ok", "depth": 1, "code": "depth.reached", "message": "Requested max level of 1 reached" }, "references": { "content:81baa86e-ee94-45de-8e90-b23d8ef84e45": { "id": "81baa86e-ee94-45de-8e90-b23d8ef84e45", "classification": "content", "metadata": { "id": "content:81baa86e-ee94-45de-8e90-b23d8ef84e45", "name": "Slide7" }, "included": [], "excluded": [ "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0" ] }, "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca": { "id": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "classification": "content-type", "metadata": { "id": "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "name": "Slideshow" }, "included": [], "excluded": [] }, "content:0e28db52-a916-49ea-9bde-9f014bc6f691": { "id": "0e28db52-a916-49ea-9bde-9f014bc6f691", "classification": "content", "metadata": { "id": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "name": "MySlideshow" }, "included": [ "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "content:81baa86e-ee94-45de-8e90-b23d8ef84e45" ], "excluded": [] } } } ~~~ #### Using Filters #### You can use some basic filters based on the item type such as content or asset and based on the status of the item such as ready or draft. For example, when you use the filter "content" it returns only items of type content. ##### Request: ##### ~~~ "{baseURL}/authoring/v1/references/outgoing/content/0e28db52-a916-49ea-9bde-9f014bc6f691?classifications=content" ~~~ ##### Response: ##### ~~~ { "root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "result": { "status": "ok", "depth": 1 }, "references": { "content:81baa86e-ee94-45de-8e90-b23d8ef84e45": { "id": "81baa86e-ee94-45de-8e90-b23d8ef84e45", "classification": "content", "included": [], "excluded": [] }, "content:0e28db52-a916-49ea-9bde-9f014bc6f691": { "id": "0e28db52-a916-49ea-9bde-9f014bc6f691", "classification": "content", "included": [ "content:81baa86e-ee94-45de-8e90-b23d8ef84e45" ], "excluded": [] } } } ~~~
User roles: admin, manager, editor, viewer ## Path parameters - `id` string, required - `classification` string, required ## Query parameters - `filterType` 'include' | 'exclude' - `depth` integer - `classifications` string[] - `statuses` string[] - `include` string[] - `fl` string[] ## Response `200` Successfully returns the fetched references. Remember to check the `result.status`property, it can be `ok` or `warn`. If it is `ok` the query ends normally. Otherwise, the query ends due to a limit but is still able to return an incomplete result set. For example, the query can end due to the current limit for a max depth of recursion of 10 and a max total references of 500. - object - `result` object - `status` 'ok' | 'partial' - `depth` integer - `next` object - `roots` string[] - `depth` integer - `fl` string[] - `metadata` boolean - `filters` object - `classifications` string[] - `statuses` string[] - `filterType` 'include' | 'exclude' - `root` string - `roots` string[] - `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)