API reference
Help centerCommunityDevelopersAcademyStatus

Retrieve the outgoing references for an item with the provided ID.

get
https://example.com/authoring/v1/references/outgoing//

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

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

Provide the ID of the item for which you want to fetch references.

string
required

Provide the classification of the item for which you want to fetch references.

Query Params
string
enum

Use the filterType parameter to inverse the filters. For example, if you are using classifications=content-type, it returns only content-types, however if you add filterType=exclude then, it returns everything besides content-types.

Allowed:
integer
Defaults to 1

The amount of depth to recursively look for references in an item. The default depth to look for references in an item is 1, so only direct outgoing references are returned. Use a higher amount of depth to get recursive references. Currently, you can request a maximum depth of 10 in one query. The filters like classifications and statuses can be used to limit amount of data that is returned when you work with references.

classifications
array of strings

Classification of items to filter references by.

classifications
statuses
array of strings

Provide the workflow status of the item to filter references. If items do not have workflow status, they are normally considered to be in the ready state for the purpose of this filtering.

statuses
Allowed:
include
array of strings

Use the 'include' parameter to add options to references that you fetch for an item. Currently, the only available option is metadata. When you use the metadata option in the include parameter, the returned code includes metadata about each of the references that are returned. The information that is returned can be controlled by using the fl parameter.

include
fl
array of strings

The fields that you can specify in the fl parameter are similar to the fl query parameters in /authoring/v1/search API. You can use the fl parameter only if you are also using the include=metadata parameter. For example, to retrieve all the document for each of the references use fl=document. If the field is not specified, the default fields are returned. The id field is always returned by default.

fl
Responses

Updated 3 months ago

Language
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 3 months ago