Acoustic Authoring assets API

openapi: 3.2.0
info:
  title: Acoustic Authoring assets API
  version: 1.0.142
  x-ibm-name: ibm-watson-content-hub-api
  description: 'Operations tagged Authoring assets 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 assets
  description: '

    ## General

    Use 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.

    ## Content workflow (status)

    The status of a content item can be determined by the **suffix** of the ID:

    - 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.

    - An ID like xxxx:***[publishing_job_id]*** - indicates that the content item has been scheduled for publish in the given publishing job.

    - An ID like xxxx with no suffix indicates that the content is **published** or **retired**.

    A draft can be created from published. When such a draft is published, it will override the previously published content.


    **Key notes:**

    - The base ID (xxxx) does not change. Only the suffix changes according to the workflow status of the item.

    - 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.

    - 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.

    - Draft item have a property ***linkedDocId***. This is the Id that the draft item will have when it is published.

    - 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.'
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:
                                        type: number
                                        description: The Y coordinate to start the crop from
                                      width:
                                        type: number
                                        description: The width to crop out
                                      height:
                                        type: number
                                        description: The height to crop out
                          example:
                          - profileId: a35f02ce-9f31-4832-8ed5-2b6d9c8b8d86
                            profileName: Profile E
                            key: renditionF
                            label: Rendition F
                            transform:
                              scale: 0.0862
                              crop:
                                x: 0
                                y: 0
                                width: 10
                                height: 10
                            uri: /authoring/v1/resources/e17b2c51-a74e-4332-80df-0f6d9340426c?resize=10px:10px&crop=10:10;0,0
                            width: 10
                            height: 10
                          - profileId: a35f02ce-9f31-4832-8ed5-2b6d9c8b8d86
                            profileName: Profile E
                            key: renditionG
                            label: Rendition G
                            transform:
                              scale: 0.17241
                              crop:
                                x: 0
                                y: 0
                                width: 20
                                height: 20
                            uri: /authoring/v1/resources/e17b2c51-a74e-4332-80df-0f6d9340426c?resize=20px:20px&crop=20:20;0,0
                            width: 20
                            height: 20
                        renditions:
                          title: Renditions Metadata
                          type: object
                          description: The renditions for the asset. Mandatory for an image asset. Does not appear for a video or file asset.
                          properties:
                            default:
                              type: object
                              properties:
                                id:
                                  type: string
                                  readOnly: true
                                  description: The ID of the rendition.
                                source:
                                  type: string
                                  readOnly: true
                                  description: The link to the rendition binary.
                        status:
                          type: string
                          readOnly: true
                          description: The workflow status of the asset.
                          enum:
                          - ready
                          - draft
                          - retired
                        valid:
                          type: boolean
                          readOnly: true
                          description: Boolean that indicates if an asset can be transitioned from draft to ready. Only available on draft assets.
                        draftStatus:
                          type: string
                          description: This property shows the status of the draft and is only valid for draft items. By default, it is in-progress.
                          default: in-progress
                          enum:
                          - in-review
                          - in-progress
                          - approved
                        links:
                          type: object
                          title: Asset Links
                          readOnly: true
                          properties:
                            self:
                              type: object
                              description: Relative link to the asset itself.
                              readOnly: true
                              properties:
                                href:
                                  type: string
                                  readOnly: true
                                  example: /authoring/v1/assets/1e5fecbb-04aa-4ed2-a014-8e544ad97597:draft
                            media:
                              type: object
                              description: The link to the resource binary.
                              readOnly: true
                              properties:
                                href:
                                  type: string
                                  readOnly: true
                                  example: /authoring/v1/resource/myResource.jpeg
                            thumbnail:
                              type: object
                              description: The link to a thumbnail of the image. Only avaliable for certain assets of type image.
                              readOnly: true
                              properties:
                                href:
                                  type: string
                                  readOnly: true
                                  example: /authoring/v1/resource/myResource.jpeg?fit=around|220:145&crop=220:145;*,*
                            ready:
                              type: object
                              description: This link will appear for items that can be transitioned to the ready state.
                              properties:
                                href:
                                  type: string
                              example:
                                href: /authoring/v1/changes/asset/1e5fecbb-04aa-4ed2-a014-8e544ad97597:draft/status/ready
                            retire:
                              type: object
                              description: This link will appear for items that can be transitioned to the retired state.
                              properties:
                                href:
                                  type: string
                              example:
                                href: /authoring/v1/changes/asset/1e5fecbb-04aa-4ed2-a014-8e544ad97597:draft/status/retire
                            linkedDoc:
                              type: object
                              description: This link will appear if this item is a draft of an existing item. The link points to the primary item.
                              properties:
                                href:
                                  type: string
                              example:
                                href: /authoring/v1/assets/1e5fecbb-04aa-4ed2-a014-8e544ad97597
                        usageRights:
                          title: Usage Rights
                          type: object
                          description: Usage rights are assigned to assets to help composers understand where and when an asset can be used. For example, an asset might be used only in print, only for an advertising campaign, and only for a limited time.
                          properties:
                            categories:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: string
                                    description: The ID of the usage rights category associated to the asset.
                                    example: 00000000-0000-0000-0000-021000c8e20
                                  path:
                                    type: string
                                    description: Name path of the usage rights category associated to the asset. This field will only be included when metadata is provided as a value of the include query parameter.
                                    example: Usage rights/Rights managed/Usage realm/Advertising
                            expiration:
                              type: string
                              format: date-time
                              description: The user will have up until this ISO 8601 specified date-time value before they no longer have permission to use the asset.
                              example: '2017-08-28T14:00:00Z'
                        review:
                          type: object
                          description: Information and/or state about the review.
                          properties:
                            id:
                              type: string
                              description: ID of the review.
                              example: 3356c048-96d0-4d8d-9afe-5e7ae47b127a
                            name:
                              type: string
                              description: Name of the review.
                              example: my review
                            started:
                              type: string
                              format: date-time
                              description: The ISO 8601 date-time that the review started.
                              example: '2017-07-10T03:20:10Z'
                            ends:
                              type: string
                              format: date-time
                              description: The ISO 8601 date-time that the review is to be completed by.
                              example: '2017-07-10T03:20:10Z'
                            ended:
                              type: string
                              format: date-time
                              description: The ISO 8601 date-time that the review actually finished on.
                              example: '2017-07-12T19:40:10Z'
                            ownerId:
                              type: string
                          additionalProperties: false
                          required:
                          - id
                          - name
                          - started
                          - ownerId
                        metadata:
                          type: object
                          description: Information extracted from an image asset's metadata.
                          properties:
                            width:
                              type: integer
                              description: Width of the image.
                              readOnly: true
                              example: 1000
                            height:
                              type: integer
                              description: Height of the image.
                              readOnly: true
                              example: 1000
                            camera:
                              type: object
                              description: Digital camera information extracted from the image asset's metadata.
                              properties:
                                make:
                                  type: string
                                  description: The manufacturer of the camera used to take the photo.
                                  readOnly: true
                                  example: NIKON CORPORATION
                                model:
                                  type: string
                                  description: The model of the camera used to take the photo.
                                  readOnly: true
                                  example: NIKON D90
                                focalLength:
                                  type: integer
                                  description: The focal length of the lens used to take the photo.
                                  readOnly: true
                                  example: 35
                                shutterSpeed:
                                  type: string
                                  description: The shutter speed setting of the camera used to take the photo.
                                  readOnly: true
                                  example: 1/200
                                iso:
                                  type: integer
                                  description: The ISO setting of the camera used to take the photo.
                                  readOnly: true
                                  example: 100
                                aperture:
                                  type: integer
                                  description: The aperture of the lens used to take the photo.
                                  readOnly: true
                                  example: 8
                            coverage:
                              type: string
                              description: Scope of the image. Possible uses include a location or a time period.
                              readOnly: true
                              example: 1972-
                            creator:
                              type: string
                              description: Creator of the image.
                              readOnly: true
                              example: Acoustic
                            Date:
                              type: string
                              description: Creation date and time of the image.
                              readOnly: true
                              example: '2017-10-23T01:23:57Z'
                            description:
                              type: string
                              description: Description of the image.
                              readOnly: true
                              example: The Acoustic logo.
                            publisher:
                              type: string
                              description: Publisher of the image.
                              readOnly: true
                              example: Acoustic
                            rights:
                              type: string
                              description: Rights information of the image.
                              readOnly: true
                              example: Acoustic
                            source:
                              type: string
                              description: Source information of the image.
                              readOnly: true
                              example: Acoustic
                            subject:
                              type: array
                              description: Topic(s) of the image.
                              readOnly: true
                              items:
                                ty

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