Acoustic Content API

{
 "openapi": "3.0.0",
 "info": {
  "version": "1.0.142",
  "x-ibm-name": "ibm-watson-content-hub-api",
  "title": "Acoustic Content API",
  "description": "Copyright \u00a9 Acoustic, L.P. 2019"
 },
 "tags": [
  {
   "name": "Authoring assets",
   "description": "\n## General\nUse the Content Asset service Rest APIs to work with assets. Assets are file types that are uploaded or created such as an image file, video file, or text that are used in content items. You can create, retrieve, update, and delete assets in a database. Managed assets are those located in the root dxdam directory as specified by its path and are visible on the Content UI.\n## Content workflow (status)\nThe status of a content item can be determined by the **suffix** of the ID:\n- An ID like xxxx:**draft** indicates that the item is a draft. This is the initial status of a new content item until it is published. A draft of a published content item will also have this suffix.\n- An ID like xxxx:***[publishing_job_id]*** - indicates that the content item has been scheduled for publish in the given publishing job.\n- An ID like xxxx with no suffix indicates that the content is **published** or **retired**.\nA draft can be created from published. When such a draft is published, it will override the previously published content.\n\n**Key notes:**\n- The base ID (xxxx) does not change. Only the suffix changes according to the workflow status of the item.\n- Where content and assets are referenced from within a content item, the 'raw' ID form, without a suffix, is always used. For example, when a draft content item is referenced by another draft content item, the reference appears as a raw ID, and thus does not change when the items are published.\n- API clients should not depend on the ID format and should not attempt to parse it. Instead, the ***linkedDocId*** and ***links*** properties should be used.\n- Draft item have a property ***linkedDocId***. This is the Id that the draft item will have when it is published.\n- Draft items that have a published version will have a ***linkedDoc*** property within the ***links*** property. This property will not appear for drafts that do not have a published version."
  },
  {
   "name": "Authoring categories",
   "description": "Use the Acoustic Content category authoring data service Rest APIs to work with category and taxonomy items."
  },
  {
   "name": "Authoring changes",
   "description": "Use the Content Authoring Changes Rest APIs to apply changes, including bulk actions, to multiple types of Content items."
  },
  {
   "name": "Authoring comments",
   "description": "Use the Content Authoring comment APIs to work with comments. Comments are a simple way to associate a message to an item in Content. Comments are associated with a single item and user (creatorId). An item can have many comments. You can create, retrieve, and delete comments from a database."
  },
  {
   "name": "Authoring content",
   "description": " ## General\nUse the Content content authoring data service Rest APIs to work with content documents. Content includes items that you compose in your content hub and upload from outside your content subscription. You can create, retrieve, and update content documents in a database. You can also create draft versions, change the status, and get a count of the total content in your database.\n\n## Content workflow (status)\nThe status of a content item can be determined by the **suffix** of the ID:\n- An ID like xxxx:**draft** indicates that the item is a draft. This is the initial status of a new content item until it is published. A draft of a published content item will also have this suffix.\n- An ID like xxxx:***[publishing_job_id]*** - indicates that the content item has been scheduled for publish in the given publishing job.\n- An ID like xxxx with no suffix indicates that the content is **published** or **retired**.\nA draft can be created from published. When such a draft is published, it will override the previously published content.\n\n**Key notes:**\n- The base ID (xxxx) does not change. Only the suffix changes according to the workflow status of the item.\n- Where content and assets are referenced from within a content item, the 'raw' ID form, without a suffix, is always used. For example, when a draft content item is referenced by another draft content item, the reference appears as a raw ID, and thus does not change when the items are published.\n- API clients should not depend on the ID format and should not attempt to parse it. Instead, the ***linkedDocId*** and ***links*** properties should be used.\n- Draft item have a property ***linkedDocId***. This is the Id that the draft item will have when it is published.\n- Draft items that have a published version will have a ***linkedDoc*** property within the ***links*** property. This property will not appear for drafts that do not have a published version."
  },
  {
   "name": "Authoring Import",
   "description": "Provides generic copying and importing functionality"
  },
  {
   "name": "Authoring layouts",
   "description": "Use the Content content authoring layout service Rest APIs to work with layouts and layout mappings.\n\nLayouts define the template for the type documents. They define the markup and how to add content properties and elements into the markup. For example, the layouts 'Article', and 'Event' would define what an article or event looks like on the web site, or email.\n\nLayout Mappings define an association between a content-type and one or more layouts. Specifically marking those layouts as valid for the given content-type.\n"
  },
  {
   "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."
  },
  {
   "name": "Authoring renditions",
   "description": "Use the Content renditions data service Rest APIs to work with image renditions. A 'rendition' of an image defines how you can customize a source image such as the width and height to be shown for a particular device or context. Renditions that are not referenced by an asset or content will be cleaned up periodically."
  },
  {
   "name": "Authoring image profiles",
   "description": "Use the Acoustic Content authoring image profile service Rest APIs to work with image profiles. You can create, retrieve, and update image profiles in a database."
  },
  {
   "name": "Authoring resources",
   "description": "Use the Content resources data service Rest APIs to work with resources. Resources are binary files that are stored in the CMS and used in content or site design. Resources that are not referenced by an asset or content will be cleaned up periodically."
  },
  {
   "name": "Authoring review",
   "description": "Use the Content Review Rest APIs to review assets and content. Use reviews to receive feedback from other members of your team. You can start, update, and complete the reviews that are set up. You can approve the content and assets under review."
  },
  {
   "name": "Authoring search",
   "description": " ## General\nUse the Content authoring search service REST API to access assets, categories, content, content types, image profiles, and taxonomies by searching the content hub. You need prior authentication to use the authoring search service. The authoring search service contains content in all states including draft, ready, and retired.\n## Content workflow (status)\nThe status of a content item can be determined by the **suffix** of the ID:\n- An ID like xxxx:**draft** indicates that the item is a draft. This is the initial status of a new content item until it is published. A draft of a published content item will also have this suffix.\n- An ID like xxxx:***[publishing_job_id]*** - indicates that the content item has been scheduled for publish in the given publishing job.\n- An ID like xxxx with no suffix indicates that the content is **published** or **retired**.\nA draft can be created from published. When such a draft is published, it will override the previously published content.\n\n**Key notes:**\n- The base ID (xxxx) does not change. Only the suffix changes according to the workflow status of the item.\n- Where content and assets are referenced from within a content item, the 'raw' ID form, without a suffix, is always used. For example, when a draft content item is referenced by another draft content item, the reference appears as a raw ID, and thus does not change when the items are published.\n"
  },
  {
   "name": "Authoring sites",
   "description": "Use the Content authoring sites service Rest APIs to work with sites. Sites are comprised of a site metadata and a hierarchy of pages. You can retrieve or update site metadata and create, read, update, and delete site pages belonging to a site. The out-of-the-box site has an ID of 'default'.\n"
  },
  {
   "name": "Authoring types",
   "description": "Use the Acoustic Content authoring type service Rest APIs to work with content type documents. Content types define a set of related elements that are used to create content. You can create, retrieve, and update content type documents in a database. You can also validate documents.\n\nNote: Documents created or updated in the old 1.0 format will be migrated to the 1.1 format on save.\n"
  },
  {
   "name": "Authoring version",
   "description": "Use the Content version Rest APIs to work with authoring items that have versions. Versioned documents currently includes assets and content items within Content. The version APIs allow you to retrieve versions."
  },
  {
   "name": "Authoring context search",
   "description": "The Authoring context search is a discretional middleware service that is positioned before the Search service. Use the Authoring context search Rest APIs to retrieve user targeted content items. You can target specific content items by providing the condition requests as filters. The filters that are currently supported by the API are  \n1. `accept-language` : Use this filter to target content items in a language of your preference.  \n2. `location` : Use this filter to target content items that are available in a location, that is, proximity to current location (within `distance` radius) of your preference.\n3. `similar` : Use this filter to target content items or assets that are similar to a specified item.\n"
  },
  {
   "name": "Delivery context search",
   "description": "The Delivery context search is a discretional middleware service that is positioned before the Search service. Use the Delivery context search Rest APIs to retrieve user targeted content items. You can target specific content items by providing the condition requests as filters. The filters that are currently supported by the API are  \n1. `accept-language` : Use this filter to target content items in a language of your preference.  \n2. `location` : Use this filter to target content items that are available in a location, that is, proximity to current location (within `distance` radius) of your preference.\n3. `similar` : Use this filter to target content items or assets that are similar to a specified item.\n"
  },
  {
   "name": "Delivery content",
   "description": "Use the Content delivery content service REST API to retrieve published content items.\n\nYou can use the /delivery/v1/content routes to access content items as an unauthenticated user or the\n/mydelivery/v1/content routes to access content items including restricted ones as an authenticated user.\nWhile access to the latter routes requires at least Viewer role, accessing the anonymous routes does not\nrequire any authentication.\n\nYou can retrieve a single content item by its ID or retrieve a collection of content items by passing in\nan array of IDs. You can also give one or more field names to these APIs so that only those fields (if\nthey exist) are returned.\n\nTo access draft content items you need to access the system in preview mode. For more information on the\npreview mode and previewing in general, please refer to https://developer.goacoustic.com/acoustic-content/docs/preview-content.\n"
  },
  {
   "name": "Delivery render",
   "description": "The Content Delivery rendering REST API provides information to render content and pages in client-side applications.\n\n**Client-side programming support**\n\nIf you want to create a client-side application with Angular 4, you can use the [Acoustic Angular SDK for Content](https://www.npmjs.com/package/@acoustic-content-sdk/ng-api). With the Angular SDK, you can retrieve and render content and pages from Content without any need to interact with the REST API directly.\n\n**Conditional GET requests**\n\nThe API supports ETag and Last-modified [conditional GET requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests). It is highly recommended to use conditional GET requests with ETags to decrease the communication data between client and API. The API provides ETag and Last-modified header response information if available. The client can send conditional GET requests with ETag and Last-modified information to validate local client data. The API responds with a `304 - Not modified response` with empty content if the condition is still valid.\n\n**JSONP support**\n\nThe API has [JSONP support](https://www.w3schools.com/js/js_json_jsonp.asp). The client can activate the JSONP support by providing the JSONP callback name query parameter.\n\n**Preview support**\n\nThe API supports the previewing of content information as described [here](https://developer.goacoustic.com/acoustic-content/docs/preview-content).\n\n\n**Usage**\n\nIn order to render content and the page structure in client-side applications you must to consider the following aspects:\n\n* Identify the addressed page that correlates to the application routing state.\n* Identify the addressed content and layout information and render the content.\n\nWith the following steps you can achieve these aspects:\n\n1. Retrieve the site and page information by using the \"Delivery Site By ID\" API route. The response contains information to identify the page that correlates to the navigational state (route) of the application.\n2. The page information has the property \"contentId\" that references the content of the page. Use that property to get the content ID.\n3. Use the content ID in combination with the \"Delivery Rendering Context By ID\" API route to retrieve the rendering context information of the content item. The rendering context contains the layout information of the content item and content references, including the resolved rendering context of the referenced items.\n4. Based on the provided layout information, identify the related the layout component of your application and render the content item by using the layout component. If required the layout can render nested layouts.\n"
  },
  {
   "name": "Delivery resources",
   "description": "The Delivery Resource Service (DRS) provides access to the published resources in Akamai.\n\nThe recommended URL for addressing published resources is the Akamai URL which is a static file access.\nFor more information see [here](https://developer.goacoustic.com/acoustic-content/docs/publishing-and-delivering-content).\n\nYou can use the /delivery/v1/resources routes to access resources as an unauthenticated user or the\n/mydelivery/v1/resources routes to access resources including restricted ones as an authenticated user.\nWhile access to the latter routes requires at least Viewer role, accessing the anonymous routes does not\nrequire any authentication.\n\nTo access draft resources you need to access the system in preview mode. For more information on the\npreview mode and previewing in general, please refer to https://developer.goacoustic.com/acoustic-content/docs/preview-content.\n"
  },
  {
   "name": "Delivery search",
   "description": "Use the Watson Content Hub delivery search REST API to search for published  assets, content items, categories and pages. You can use the /delivery/v1/search route to perform anonymous searches or the /mydelivery/v1/search route to perform authenticated searches that include restricted items. While access to the latter route requires at least Authenticated visitor role, accessing the anonymous route does not require any authentication. The delivery search provides access to published items only. To include draft items into your search, you can access this delivery search via the preview host. For more information on the preview host and previewing in general, please refer to https://developer.goacoustic.com/acoustic-content/docs/preview-content"
  },
  {
   "name": "Delivery sites",
   "description": "Use the Content delivery sites service Rest APIs to retrieve published site artefacts.\n"
  },
  {
   "name": "Tenant Registry"
  },
  {
   "name": "Login service",
   "description": "Login service offers endpoint to login into Acoustic Content."
  },
  {
   "name": "Administering user profiles"
  },
  {
   "name": "Webhook profiles",
   "description": "Use the Content webhook service Rest APIs to work with webhook profiles. You can create, retrieve and update webhook profiles in a database.\n\n### Webhook Timeouts and Retry policy\nWebhooks will automatically timeout (with no retry) after 5s which means that receivers should always perform their processing in background threads. The only situation whereby webhooks will be retried/re-sent is in the event of a communication error, and in this case only a single retry will occur.\nNote: Non-2xx responses from receivers are explicitly not retried\n"
  },
  {
   "name": "Publishing",
   "description": "Use the Content Publishing APIs to update the default site revision, which is a snapshot of your published site at a specific time. current-job instance is used to track the state of the job.\n A site revision represents a specific revision of a site."
  }
 ],
 "paths": {
  "/authoring/v1/assets": {
   "get": {
    "tags": [
     "Authoring assets"
    ],
    "summary": "Retrieve all assets.",
    "description": "Use this endpoint to retrieve all assets from the database.<br />User roles: admin, manager, editor, viewer",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "description": "Set the limit for the maximum number of assets to return in a single result. Set to 50 by default.",
      "required": false,
      "schema": {
       "type": "integer",
       "default": 50
      }
     },
     {
      "name": "offset",
      "in": "query",
      "description": "Use the offset parameter to specify the number of assets to skip from the beginning of the list and return the rest.",
      "required": false,
      "schema": {
       "type": "integer",
       "default": 0
      }
     },
     {
      "name": "fields",
      "in": "query",
      "description": "Only the asset fields that are specified here are returned for each result. Any asset field is a valid value and these can be specified in a comma-separated list. For example, to list the asset fields name and ID, provide the value ID, and name. All asset fields are returned by default.",
      "required": false,
      "allowEmptyValue": true,
      "style": "form",
      "explode": false,
      "schema": {
       "type": "array",
       "items": {
        "type": "string"
       }
      }
     },
     {
      "name": "include",
      "in": "query",
      "description": "Optional: Parameters used to include additional fields inside each returned asset. Use \"links\" to include the links section, which contains URLs for actions that can be performed on the asset. Use \"metadata\" to include additional fields for each of the items referenced by the asset You can specify multiple fields as a comma-separated value. For example, \"include=links,metadata\".",
      "required": false,
      "style": "form",
      "explode": false,
      "schema": {
       "type": "array",
       "items": {
        "type": "string"
       }
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Successfully lists a paged result view of all the asset in the database.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "limit": {
           "type": "integer",
           "description": "The page size. Set to 50 by default.",
           "example": 50
          },
          "offset": {
           "type": "integer",
           "description": "The number of items to skip from the beginning of the list.",
           "example": 0
          },
          "href": {
           "type": "string",
           "description": "A link to the current page.",
           "example": "/asset?offset=50&limit=50"
          },
          "next": {
           "type": "string",
           "description": "A link to the next page. Only shown if a next page exists.",
           "example": "/asset?offset=100&limit=50"
          },
          "previous": {
           "type": "string",
           "description": "A link to the previous page. Only shown if a previous page exists.",
           "example": "/asset?offset=0&limit=50"
          },
          "items": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "string",
              "description": "The id of the asset.",
              "readOnly": true,
              "example": "0a800487f06d71eaf4cffdfde1ab28bc",
              "maxLength": 100,
              "pattern": "^[a-zA-Z0-9*.\\-_:]*$"
             },
             "rev": {
              "type": "string",
              "description": "The revision of the asset.",
              "readOnly": true,
              "pattern": "^[0-9]+-.*$",
              "example": "2-c839bbb8844549c2e298275c4b2adcb8"
             },
             "name": {
              "type": "string",
              "description": "Name of the asset."
             },
             "classification": {
              "type": "string",
              "readOnly": true,
              "enum": [
               "asset"
              ],
              "description": "The classification of the asset is always \"asset\"."
             },
             "assetType": {
              "type": "string",
              "readOnly": true,
              "description": "The type of asset. Determined by the media type of the resource.",
              "enum": [
               "image",
               "video",
               "file"
              ]
             },
             "description": {
              "type": "string",
              "description": "Description of the asset.",
              "example": "This is an image of a person.",
              "maxLength": 500
             },
             "creatorId": {
              "type": "string",
              "readOnly": true,
              "description": "The ID of the user that created the asset.",
              "example": "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e"
             },
             "created": {
              "type": "string",
              "format": "date-time",
              "readOnly": true,
              "description": "The date and time the asset was created."
             },
             "creator": {
              "type": "string",
              "readOnly": true,
              "description": "The name of the user who originally created the asset."
             },
             "lastModifierId": {
              "type": "string",
              "readOnly": true,
              "description": "The ID of the user that last modified the asset.",
              "example": "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e"
             },
             "lastModified": {
              "type": "string",
              "format": "date-time",
              "readOnly": true,
              "description": "The date and time the asset was last modified."
             },
             "lastModifier": {
              "type": "string",
              "readOnly": true,
              "description": "The name of the user who last modified the item."
             },
             "systemModified": {
              "type": "string",
              "format": "date-time",
              "readOnly": true,
              "description": "The date and time the asset was last modified by the system."
             },
             "fileName": {
              "type": "string",
              "readOnly": true,
              "description": "The file name of the asset's resource.",
              "example": "hub.png"
             },
             "fileSize": {
              "type": "integer",
              "readOnly": true,
              "description": "The size of the asset's resource in bytes.",
              "example": 123125
             },
             "mediaType": {
              "type": "string",
              "readOnly": true,
              "description": "Media type of the asset's resource.",
              "example": "image/png"
             },
             "keywords": {
              "type": "array",
              "readOnly": true,
              "items": {
               "type": "string"
              },
              "description": "When AI analysis is complete, the document type assets will be automatically updated with keywords generated by the analysis. Keywords are updated only for PDF, doc, html, and plain text files."
             },
             "tags": {
              "title": "Tags",
              "type": "object",
              "description": "The \"values\" array defines the user selected tags. The other two properties \"declined\" and \"suggested\" relate directly to the interaction with the cognitive analysis feature.",
              "properties": {
               "values": {
                "type": "array",
                "description": "Tags can be set here. Tags suggested by cognitive analysis should be copied into this array if you wish to accept them.",
                "items": {
                 "type": "string"
                },
                "example": [
                 "faces:Lebron James",
                 "sports",
                 "basketball"
                ]
               },
               "declined": {
                "type": "array",
                "description": "This editable field is given for the store values from cogntivie analysis that the user has dismissed/rejected. This essentially. It is up to the API client to update this field. This field is not indexed for search.",
                "items": {
                 "type": "string"
                }
               },
               "suggested": {
                "readOnly": true,
                "description": "Suggested field is a read only field that is populated if cognitive analysis is done on this asset. Once reviewed the suggestions can be cleared with a query parameter see update endpoint. The tags come in the form of \"prefix:tag\" e.g. \"classification:sky\" This field is not indexed for search.",
                "type": "array",
                "items": {
                 "type": "string"
                }
               },
               "analysis": {
                "description": "This field indicates the progress of AI analysis.",
                "readOnly": true,
                "type": "string",
                "enum": [
                 "complete",
                 "failed",
                 "none",
                 "pending"
                ]
               },
               "analysisStarted": {
                "description": "This field exists when analysis is launched but not complete. The value is the epoch time of when the analysis began.",
                "type": "integer",
                "readOnly": true
               }
              },
              "required": [
               "values",
               "declined"
              ]
             },
             "resource": {
              "type": "string",
              "description": "The ID of the uploaded resource this asset contains.",
              "example": "67c621ed48921b7338b84b4f415cba6b"
             },
             "digest": {
              "type": "string",
              "description": "The Base64 encoded MD5 digest of the resouce the asset contains.",
              "example": "9jwWuI3TN+PhGfHcrSJHcQ==",
              "readOnly": true
             },
             "path": {
              "type": "string",
              "pattern": "^/[\\s\\S]+[^/]$",
              "maxLength": 650,
              "description": "The path to this asset, must begin with a leading slash. A unique constraint is placed on this path so that no other asset can have the same path. When updating path a collision results in error. Paths begining with \"/dxdam/\" are managed assets.",
              "example": "/sales/images/hub.png"
             },
             "categoryIds": {
              "type": "array",
              "description": "The IDs of the categories that define how this asset is categorized.",
              "items": {
               "type": "string"
              },
              "example": []
             },
             "profiles": {
              "type": "array",
              "description": "The IDs of image profiles to add to use on this asset.",
              "items": {
               "type": "string"
              },
              "example": [
               "8b4698e3-6283-4bc5-9e1e-fff69c2b48be"
              ]
             },
             "profileRenditions": {
              "type": "array",
              "description": "The transform instructions for each of the renditions in the \"profiles\" array. If a rendition for one of those image profiles is not defined, a rendition with the best fit will automatically be generated.",
              "items": {
               "title": "Profile Rendition",
               "type": "object",
               "properties": {
                "profileId": {
                 "type": "string",
                 "description": "The ID of the image profile this rendition belongs to. This ID must also be specified in the \"profiles\" array."
                },
                "profileName": {
                 "type": "string",
                 "readOnly": true,
                 "description": "The name of the image profile this rendition belongs to. This field will only be included when metadata is provided as a value of the include query parameter."
                },
                "key": {
                 "type": "string",
                 "description": "The key to this rendition."
                },
                "label": {
                 "type": "string",
                 "readOnly": true,
                 "description": "The label to this rendition. This field will only be included when metadata is provided as a value of the include query parameter."
                },
                "uri": {
                 "type": "string",
                 "readOnly": true,
                 "description": "The URI to the resource in this rendition's dimensions."
                },
                "width": {
                 "type": "number",
                 "readOnly": true,
                 "description": "The width defined for this rendition."
                },
                "height": {
                 "type": "number",
                 "readOnly": true,
                 "description": "The height defined for this rendition."
                },
                "transform": {
                 "title": "Transform",
                 "type": "object",
                 "description": "The transform instructions to achieve this rendition's dimensions. If not specified, a best fit transformation will automatically be generated.",
                 "properties": {
                  "scale": {
                   "type": "number",
                   "description": "The scale to perform on the original resource. The value must be between 0 (exclusive) and 1 (inclusive)."
                  },
                  "crop": {
                   "title": "Crop",
                   "type": "object",
                   "description": "The crop to apply on the resource after any scaling has been done.",
                   "properties": {
                    "x": {
                     "type": "number",
                     "description": "The X coordinate to start the crop from"
                    },
                    "y": {
         

# --- truncated at 32 KB (3695 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/acoustic/refs/heads/main/openapi/acoustic-content-openapi-original.json