Acoustic Authoring reference API

openapi: 3.2.0
info:
  title: Acoustic Authoring reference API
  version: 1.0.142
  x-ibm-name: ibm-watson-content-hub-api
  description: 'Operations tagged Authoring reference across 2 of this provider''s published API definitions: acoustic-content-openapi-original.json, acoustic-content-swagger2-original.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: Authoring reference
  description: The Content Authoring reference API is used to retrieve information about references between items in the system. The type of relationships that are tracked  depends on the type of item. Typically, if an item has an editable property that points to an ID of another item, it is tracked. You can use the API to fetch both incoming and outgoing references for any item.
paths:
  /authoring/v1/references/outgoing:
    post:
      tags:
      - Authoring reference
      summary: Retrieve the outgoing references for items.
      description: "Use the `/references/outgoing` endpoint to retrieve outgoing references for items. This endpoint allows batch lookups by allowing multiple items to be looked at the same time\n### Examples: ###\n#### A simple lookup of the outgoing references for one item ####\nThe 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.\nYou can then either query at a higher depth or query for all items which have non empty `excluded` arrays.\n\nThe results are returned in a key value format with the `references` field where the key is the content hub ID of the item.\n\nIn 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.\n##### Request: #####\n~~~\n   {\n     \"root\" : \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\"\n   }\n~~~\n##### Response: #####\n~~~\n{\n   \"root\": \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n   \"result\": {\n     \"status\": \"ok\",\n     \"depth\": 1\n   },\n   \"next\": {\n     \"roots\": [\n       [\n         \"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0\"\n       ]\n     ],\n     \"filters\": {\n       \"filterType\": \"include\",\n       \"classifications\": [],\n       \"statuses\": []\n     },\n     \"depth\": 1,\n     \"metadata\": true,\n     \"fl\": []\n   },\n   \"references\": {\n     \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\": {\n       \"id\": \"81baa86e-ee94-45de-8e90-b23d8ef84e45\",\n       \"classification\": \"content\",\n       \"included\": [],\n       \"excluded\": [\n         \"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0\"\n       ]\n     },\n     \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\": {\n       \"id\": \"bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n       \"classification\": \"content-type\",\n       \"included\": [],\n       \"excluded\": []\n     },\n     \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\": {\n       \"id\": \"0e28db52-a916-49ea-9bde-9f014bc6f691\",\n       \"classification\": \"content\",\n       \"included\": [\n         \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n         \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\"\n       ],\n       \"excluded\": []\n     }\n   }\n }\n~~~\n#### A simple lookup of the outgoing references for one item with metadata ####\nInstead of just getting a graph of content hub IDs, you can also request to retrieve metadata for each item.\n\nThe metadata returned are the default fields that are returned by the authoring search API (`authoring/v1/search`).\n##### Request: #####\n~~~\n   {\n     \"root\" : \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n     \"metadata\" : true\n   }\n~~~\n##### Response: #####\n~~~\n{\n   \"root\": \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n   \"result\": {\n     \"status\": \"ok\",\n     \"depth\": 1\n   },\n   \"references\": {\n     \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\": {\n       \"id\": \"81baa86e-ee94-45de-8e90-b23d8ef84e45\",\n       \"classification\": \"content\",\n       \"metadata\": {\n         \"id\": \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\",\n         \"name\": \"Slide7\",\n         \"classification\": \"content\",\n         \"type\": \"Slide\",\n         \"typeId\": \"cad2e430-beed-40d0-bb57-1c86c4f912c0\",\n         \"locale\": \"en\",\n         \"lastModified\": \"2017-06-09T01:21:31.369Z\",\n         \"lastModifier\": \"Thomas Watson\",\n         \"lastModifierId\": \"8bd88336-648c-46a6-80d4-73c0e81fb4fa\",\n         \"created\": \"2017-06-09T01:21:17.630Z\",\n         \"creator\": \"Thomas Watson\",\n         \"creatorId\": \"8bd88336-648c-46a6-80d4-73c0e81fb4fa\",\n         \"status\": \"ready\"\n       },\n       \"included\": [],\n       \"excluded\": [\n         \"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0\"\n       ]\n     },\n     \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\": {\n       \"id\": \"bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n       \"classification\": \"content-type\",\n       \"metadata\": {\n         \"id\": \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n         \"name\": \"Slideshow\",\n         \"classification\": \"content-type\",\n         \"lastModified\": \"2017-06-09T01:18:08.301Z\",\n         \"lastModifier\": \"Thomas Watson\",\n         \"lastModifierId\": \"8bd88336-648c-46a6-80d4-73c0e81fb4fa\",\n         \"created\": \"2017-06-09T01:15:56.578Z\",\n         \"creator\": \"Thomas Watson\",\n         \"creatorId\": \"8bd88336-648c-46a6-80d4-73c0e81fb4fa\",\n         \"status\": \"ready\"\n       },\n       \"included\": [],\n       \"excluded\": []\n     },\n     \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\": {\n       \"id\": \"0e28db52-a916-49ea-9bde-9f014bc6f691\",\n       \"classification\": \"content\",\n       \"metadata\": {\n         \"id\": \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n         \"name\": \"MySlideshow\",\n         \"classification\": \"content\",\n         \"type\": \"Slideshow\",\n         \"typeId\": \"bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n         \"locale\": \"en\",\n         \"lastModified\": \"2017-06-09T01:22:34.049Z\",\n         \"lastModifier\": \"Thomas Watson\",\n         \"lastModifierId\": \"8bd88336-648c-46a6-80d4-73c0e81fb4fa\",\n         \"created\": \"2017-06-09T01:18:58.426Z\",\n         \"creator\": \"Thomas Watson\",\n         \"creatorId\": \"8bd88336-648c-46a6-80d4-73c0e81fb4fa\",\n         \"status\": \"ready\"\n       },\n       \"included\": [\n         \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n         \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\"\n       ],\n       \"excluded\": []\n     }\n   }\n }\n~~~\n#### Using fl parameter to request specific metadata fields ####\nJust 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.\n\nNote: When the `fl` parameter is used, the `id` field is also always returned.\n##### Request: #####\n~~~\n   {\n     \"root\" : \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n     \"metadata\" : true,\n     \"fl\" : [\"name\"]\n   }\n~~~\n##### Response: #####\n~~~\n {\n   \"root\": \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n   \"result\": {\n     \"status\": \"ok\",\n     \"depth\": 1\n   },\n   \"references\": {\n     \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\": {\n       \"id\": \"81baa86e-ee94-45de-8e90-b23d8ef84e45\",\n       \"classification\": \"content\",\n       \"metadata\": {\n         \"id\": \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\",\n         \"name\": \"Slide7\"\n       },\n       \"included\": [],\n       \"excluded\": [\n         \"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0\"\n       ]\n     },\n     \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\": {\n       \"id\": \"bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n       \"classification\": \"content-type\",\n       \"metadata\": {\n         \"id\": \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n         \"name\": \"Slideshow\"\n       },\n       \"included\": [],\n       \"excluded\": []\n     },\n     \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\": {\n       \"id\": \"0e28db52-a916-49ea-9bde-9f014bc6f691\",\n       \"classification\": \"content\",\n       \"metadata\": {\n         \"id\": \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n         \"name\": \"MySlideshow\"\n       },\n       \"included\": [\n         \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n         \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\"\n       ],\n       \"excluded\": []\n     }\n   }\n }\n~~~\n#### Multiple items can be looked up at once by specifying multiple roots ####\nNote: Items are not duplicated twice in the references map. It is just a key value of content hub ID to data.\n##### Request: #####\n~~~\n{\n \"roots\" : [ \"content:7015a689-91df-407e-9c1b-39ead6c37e89\",\n       \"content:af988817-fcae-4070-a987-93cb99e4f81d\"]\n}\n~~~\n##### Response: #####\n~~~\n {\n   \"roots\": [\n     \"content:7015a689-91df-407e-9c1b-39ead6c37e89\",\n     \"content:af988817-fcae-4070-a987-93cb99e4f81d\"\n   ],\n   \"result\": {\n     \"status\": \"ok\",\n     \"depth\": 1\n   },\n   \"references\": {\n     \"content:7015a689-91df-407e-9c1b-39ead6c37e89\": {\n       \"id\": \"7015a689-91df-407e-9c1b-39ead6c37e89\",\n       \"classification\": \"content\",\n       \"included\": [\n         \"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0\"\n       ],\n       \"excluded\": []\n     },\n     \"content:af988817-fcae-4070-a987-93cb99e4f81d\": {\n       \"id\": \"af988817-fcae-4070-a987-93cb99e4f81d\",\n       \"classification\": \"content\",\n       \"included\": [\n         \"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0\"\n       ],\n       \"excluded\": []\n     },\n     \"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0\": {\n       \"id\": \"cad2e430-beed-40d0-bb57-1c86c4f912c0\",\n       \"classification\": \"content-type\",\n       \"included\": [],\n       \"excluded\": []\n     }\n   }\n }\n\n~~~\n#### Using Filters ####\nYou 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.\n\nFor example, when you use the filter \"content\" it returns only items of type content.\n##### Request: #####\n~~~\n {\n    \"root\":\"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n    \"filters\":{\n       \"classifications\":[\n          \"content\"\n       ]\n    }\n }\n~~~\n##### Response: #####\n~~~\n{\n   \"root\": \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n  \"result\": {\n     \"status\": \"ok\",\n     \"depth\": 1\n   },\n   \"references\": {\n     \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\": {\n       \"id\": \"81baa86e-ee94-45de-8e90-b23d8ef84e45\",\n       \"classification\": \"content\",\n       \"included\": [],\n       \"excluded\": []\n     },\n     \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\": {\n       \"id\": \"0e28db52-a916-49ea-9bde-9f014bc6f691\",\n       \"classification\": \"content\",\n       \"included\": [\n         \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\"\n       ],\n       \"excluded\": []\n     }\n   }\n }\n~~~\n<br />User roles: admin, manager, editor, viewer"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: object
                  properties:
                    classifications:
                      type: array
                      items:
                        type: string
                    statuses:
                      type: array
                      items:
                        enum:
                        - draft
                        - ready
                        - retired
                    filterType:
                      enum:
                      - include
                      - exclude
                  additionalProperties: false
                depth:
                  type: integer
                fl:
                  type: array
                  items:
                    type: string
                metadata:
                  type: boolean
                root:
                  type: string
                roots:
                  type: array
                  items:
                    type: string
              additionalProperties: false
        description: Provide the request details in the body.
        required: true
      responses:
        '200':
          description: 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 max total references of 500.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      status:
                        enum:
                        - ok
                        - partial
                      depth:
                        type: integer
                  next:
                    type: object
                    properties:
                      roots:
                        type: array
                        items:
                          type: string
                      depth:
                        type: integer
                      fl:
                        type: array
                        items:
                          type: string
                      metadata:
                        type: boolean
                      filters:
                        type: object
                        properties:
                          classifications:
                            type: array
                            items:
                              type: string
                          statuses:
                            type: array
                            items:
                              enum:
                              - draft
                              - ready
                              - retired
                          filterType:
                            enum:
                            - include
                            - exclude
                        additionalProperties: false
                  root:
                    type: string
                  roots:
                    type: array
                    items:
                      type: string
                  references:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        id:
                          type: string
                        classification:
                          type: string
                          example: content
                          description: Every item in content hub has a classification the classification and id combine to make a unique id across different types of items in content hub.
                        metadata:
                          type: object
                          description: 'The metadata property is only added if you use include=metadata. Additionally the contents of this object mirrors what is returned by search which is why the search `fl` parameter is available for use here. So with fl=id,name The name and id will be added. The id will always be included '
                          example:
                          - name: Article 1
                          - id: content:9aefea92-2dd4-42c3-8999-10acbcfcc054
                        included:
                          description: 'The included are outgoing references of this item we also fetched for metadata and references. Another way to put it is in the Graph traversal of the reference we walked these edges. Every id in here is guaranteed to also have a corresponding object in the references. '
                          example:
                          - content:2a1e4698-2b95-4f61-be9f-1a1ca477b3c1
                          - asset:792c31ac-3a79-4183-8b7e-fce05e6dcc39
                          - content-type:5b839b21-0b6e-412c-8421-6bde66ca624c
                          type: array
                          items:
                            type: string
                        excluded:
                          description: 'If an outgoing reference is not included, then it is excluded. If its excluded we didn''t attempt to fetch information about these items (and their references). This can happen for a couple of reasons. The common one is because the reference was filtered out. See the filter information to find out how filters work. Another reason is if the query terminated early. This can happen if the '
                          type: array
                          items:
                            type: string
                      additionalProperties: false
        '429':
          description: Too Many Requests, the server has reached a limit, the request must be sent again at a later time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                type: object
                description: an error response.
                properties:
                  requestId:
                    type: string
                    description: The current request ID
                  service:
                    type: string
                    description: The name of the service that produced the error
                  requestMethod:
                    type: string
                    description: The Http method type of the current request
                  requestUri:
                    type: string
                    description: The request uri
                  errors:
                    type: array
                    items:
                      type: object
                      description: an individual error, info or warning message.
                      properties:
                        code:
                          type: integer
                          description: The message code
                        key:
                          type: string
                          description: The message key
                        message:
                          type: string
                          description: The error message
                        description:
                          type: string
                          description: Optional detailed error message
                        more_info:
                          type: string
                          description: Optional additional information for the message
                        category:
                          type: string
                          description: The message category whereby only user messages are designed to be shown to an end user
                          enum:
                          - API
                          - USER
                        level:
                          type: string
                          description: Indicates the message level
                          enum:
                          - INFO
                          - WARNING
                          - ERROR
                        parameters:
                          type: object
                          description: The message parameters of this message.
                        field:
                          type: string
                          description: Only present on field validation errors, indicates the field in error.
                        locale:
                          type: string
                          description: The current locale used to produce the error message.
                      required:
                      - code
                      - key
                      - message
                      - description
                      - more_info
                      - category
                      - level
                      - parameters
                      - field
                      - locale
                required:
                - requestId
                - service
                - requestMethod
                - requestUri
                - errors
      x-ibm-dx-security-user-roles:
      - admin
      - manager
      - editor
      - viewer
  /authoring/v1/references/outgoing/{classification}/{id}:
    get:
      tags:
      - Authoring reference
      summary: Retrieve the outgoing references for an item with the provided ID.
      description: "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.\n\n ### Examples: ###\n #### A simple lookup of the outgoing references for one item ####\n 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.\n You can either query at a higher depth or query for all items, which have non empty `excluded` arrays.\n\n The results are returned in a key value format with the `references` field where the key is the content hub ID of the item.\n\n 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.\n ##### Request: #####\n ~~~\n     \"{baseURL}/authoring/v1/references/outgoing/content/0e28db52-a916-49ea-9bde-9f014bc6f691\"\n ~~~\n ##### Response: #####\n ~~~\n {\n    \"root\": \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n    \"result\": {\n      \"status\": \"ok\",\n      \"depth\": 1\n    },\n    \"next\": {\n      \"roots\": [\n        [\n          \"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0\"\n        ]\n      ],\n      \"filters\": {\n        \"filterType\": \"include\",\n        \"classifications\": [],\n        \"statuses\": []\n      },\n      \"depth\": 1,\n      \"fl\": []\n    },\n    \"references\": {\n      \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\": {\n        \"id\": \"81baa86e-ee94-45de-8e90-b23d8ef84e45\",\n        \"classification\": \"content\",\n        \"included\": [],\n        \"excluded\": [\n          \"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0\"\n        ]\n      },\n      \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\": {\n        \"id\": \"bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n        \"classification\": \"content-type\",\n        \"included\": [],\n        \"excluded\": []\n      },\n      \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\": {\n        \"id\": \"0e28db52-a916-49ea-9bde-9f014bc6f691\",\n        \"classification\": \"content\",\n        \"included\": [\n          \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n          \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\"\n        ],\n        \"excluded\": []\n      }\n    }\n  }\n ~~~\n #### A simple lookup of the outgoing references for one item with metadata ####\n Instead of just getting a graph of content hub IDs, you can also request to retrieve metadata for each item.\n\n The metadata returned are the default fields that are returned by authoring search API (`authoring/v1/search`).\n ##### Request: #####\n ~~~\n    {\n     \"{baseURL}/authoring/v1/references/outgoing/content/0e28db52-a916-49ea-9bde-9f014bc6f691?include=metadata\"\n    }\n ~~~\n ##### Response: #####\n ~~~\n {\n    \"root\": \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n    \"result\": {\n      \"status\": \"ok\",\n      \"depth\": 1\n    },\n    \"references\": {\n      \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\": {\n        \"id\": \"81baa86e-ee94-45de-8e90-b23d8ef84e45\",\n        \"classification\": \"content\",\n        \"metadata\": {\n          \"id\": \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\",\n          \"name\": \"Slide7\",\n          \"classification\": \"content\",\n          \"type\": \"Slide\",\n          \"typeId\": \"cad2e430-beed-40d0-bb57-1c86c4f912c0\",\n          \"locale\": \"en\",\n          \"lastModified\": \"2017-06-09T01:21:31.369Z\",\n          \"lastModifier\": \"Thomas Watson\",\n          \"lastModifierId\": \"8bd88336-648c-46a6-80d4-73c0e81fb4fa\",\n          \"created\": \"2017-06-09T01:21:17.630Z\",\n          \"creator\": \"Thomas Watson\",\n          \"creatorId\": \"8bd88336-648c-46a6-80d4-73c0e81fb4fa\",\n          \"status\": \"ready\"\n        },\n        \"included\": [],\n        \"excluded\": [\n          \"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0\"\n        ]\n      },\n      \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\": {\n        \"id\": \"bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n        \"classification\": \"content-type\",\n        \"metadata\": {\n          \"id\": \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n          \"name\": \"Slideshow\",\n          \"classification\": \"content-type\",\n          \"lastModified\": \"2017-06-09T01:18:08.301Z\",\n          \"lastModifier\": \"Thomas Watson\",\n          \"lastModifierId\": \"8bd88336-648c-46a6-80d4-73c0e81fb4fa\",\n          \"created\": \"2017-06-09T01:15:56.578Z\",\n          \"creator\": \"Thomas Watson\",\n          \"creatorId\": \"8bd88336-648c-46a6-80d4-73c0e81fb4fa\",\n          \"status\": \"ready\"\n        },\n        \"included\": [],\n        \"excluded\": []\n      },\n      \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\": {\n        \"id\": \"0e28db52-a916-49ea-9bde-9f014bc6f691\",\n        \"classification\": \"content\",\n        \"metadata\": {\n          \"id\": \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n          \"name\": \"MySlideshow\",\n          \"classification\": \"content\",\n          \"type\": \"Slideshow\",\n          \"typeId\": \"bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n          \"locale\": \"en\",\n          \"lastModified\": \"2017-06-09T01:22:34.049Z\",\n          \"lastModifier\": \"Thomas Watson\",\n          \"lastModifierId\": \"8bd88336-648c-46a6-80d4-73c0e81fb4fa\",\n          \"created\": \"2017-06-09T01:18:58.426Z\",\n          \"creator\": \"Thomas Watson\",\n          \"creatorId\": \"8bd88336-648c-46a6-80d4-73c0e81fb4fa\",\n          \"status\": \"ready\"\n        },\n        \"included\": [\n          \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n          \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\"\n        ],\n        \"excluded\": []\n      }\n    }\n  }\n ~~~\n #### Using fl parameter to request specific metadata fields ####\n 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.\n\n Note: When the `fl` parameter is used, the `id` field  is also always returned.\n ##### Request: #####\n ~~~\n    {\n     \"{baseURL}/authoring/v1/references/outgoing/content/0e28db52-a916-49ea-9bde-9f014bc6f691?include=metadata&fl=name\"\n    }\n ~~~\n ##### Response: #####\n ~~~\n  {\n    \"root\": \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n    \"result\": {\n      \"status\": \"ok\",\n      \"depth\": 1,\n      \"code\": \"depth.reached\",\n      \"message\": \"Requested max level of 1 reached\"\n    },\n    \"references\": {\n      \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\": {\n        \"id\": \"81baa86e-ee94-45de-8e90-b23d8ef84e45\",\n        \"classification\": \"content\",\n        \"metadata\": {\n          \"id\": \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\",\n          \"name\": \"Slide7\"\n        },\n        \"included\": [],\n        \"excluded\": [\n          \"content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0\"\n        ]\n      },\n      \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\": {\n        \"id\": \"bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n        \"classification\": \"content-type\",\n        \"metadata\": {\n          \"id\": \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n          \"name\": \"Slideshow\"\n        },\n        \"included\": [],\n        \"excluded\": []\n      },\n      \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\": {\n        \"id\": \"0e28db52-a916-49ea-9bde-9f014bc6f691\",\n        \"classification\": \"content\",\n        \"metadata\": {\n          \"id\": \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n          \"name\": \"MySlideshow\"\n        },\n        \"included\": [\n          \"content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca\",\n          \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\"\n        ],\n        \"excluded\": []\n      }\n    }\n  }\n ~~~\n #### Using Filters ####\n 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.\n For example, when you use the filter \"content\" it returns only items of type content.\n ##### Request: #####\n ~~~\n   \"{baseURL}/authoring/v1/references/outgoing/content/0e28db52-a916-49ea-9bde-9f014bc6f691?classifications=content\"\n ~~~\n ##### Response: #####\n ~~~\n {\n    \"root\": \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\",\n   \"result\": {\n      \"status\": \"ok\",\n      \"depth\": 1\n    },\n    \"references\": {\n      \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\": {\n        \"id\": \"81baa86e-ee94-45de-8e90-b23d8ef84e45\",\n        \"classification\": \"content\",\n        \"included\": [],\n        \"excluded\": []\n      },\n      \"content:0e28db52-a916-49ea-9bde-9f014bc6f691\": {\n        \"id\": \"0e28db52-a916-49ea-9bde-9f014bc6f691\",\n        \"classification\": \"content\",\n        \"included\": [\n          \"content:81baa86e-ee94-45de-8e90-b23d8ef84e45\"\n        ],\n        \"excluded\": []\n      }\n    }\n  }\n ~~~\n<br />User roles: admin, manager, editor, viewer"
      parameters:
      - name: id
        in: path
        description: Provide the ID of the item for which you want to fetch references.
        required: true
        schema:
          type: string
      - name: classification
        in: path
        description: Provide the classification of the item for which you want to fetch references.
        required: true
        schema:
          type: string
      - name: filterType
        in: query
        description: 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.
        schema:
          type: string
          enum:
          - include
          - exclude
      - name: depth
        in: query
        description: 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.
        schema:
          type: integer
          default: 1
      - name: classifications
        description: Classification of items to filter references by.
        in: query
        required: false
        allowEmptyValue: true
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: statuses
        description: 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.
        in: query
        required: false
        allowEmptyValue: true
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - draft
            - ready
            - retired


# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/acoustic/refs/heads/main/openapi/acoustic-authoring-reference-api-openapi.yml