Sign in

v1

latestOpenAPI 3.0.02026-07-2417611.8 MB
Authoring assets

Create an asset.

Use this endpoint to create an asset. There are two ways to use this endpoint. The first method is to create a resource separately, then provide the resource id in the json body of the request along with any other desired data. The second method is to provide resource binary as a multipart field. Another multipart field containing any additional data can then be optionally provided. The second method allows the asset and resource to be created simultaneously. Note:- If AI tag analysis is enabled, it starts in the background. AI analyzes and provides tag recommendations for the asset that is created.

Method 1 (Create asset and resource separately):

Create the resource

See POST /resource for details on how to create a resource.

Create the asset

Create an asset by providing the resource id obtained from the previous step. Additional data about the asset can also be optionally provided. If an asset exists in the specified path, it is overwritten. The path that you provide must contain a leading slash. The path and name fields are optional and are generated from the resource’s name by default.

Example request body:

  {
    "resource": "8d21025d21e7b3595cbf630fb9d7212b",
    "path": "/Screen Shot 2016-05-11 at 6.52.22 PM",
    "description": "Screenshot",
    "name": "Important screenshot",
    "tags": {
      "values": [
        "screenshot"
      ]
    },
    "status": "draft"
  }

Method 2 (Create asset and resource simultaneously):

Set the Content-Type header

Set the Content-Type header to 'multipart/form-data'.

Set the 'resource' field on the multipart form

The resource field on the multipart form should contain your resource binary. The following headers are required on this form part:

  1. Content-Type header specifying the format of the resource.
  2. The filename field on the Content-Disposition header of this form part specifying the resource name.

Set the 'data' field on the multipart form (optional)

Additional data about the asset can be optionally provided. If an asset exists in the specified path, it is overwritten. The path that you provide must contain a leading slash. The path and name fields are optional and are generated from the resource’s name by default.

Example value in field:

  {
    "path": "/Screen Shot 2016-05-11 at 6.52.22 PM",
    "description": "Screenshot",
    "name": "Important screenshot",
    "tags": {
      "values": [
        "screenshot"
      ]
    },
    "status": "draft"
  }

Create the asset and resource

Create the asset and resource simultaneously by posting the form.

<br />User roles: admin, manager, editor

post/authoring/v1/assets

Query parameters

md5string

Provide the Base64 encoded MD5 checksum of the resource. This is only used when creating the asset and resource simultaneously.

fieldsstring[]

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.

includestring[]

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

analyzeboolean

Set the analyze parameter to true to enable the AI tag analysis. Analysis will only occur for managed assets.

autocurateboolean

Set the autocurate parameter to true automatically curate and accept all suggested tags.

Headers

x-ibm-dx-publish-priority'now' | 'next' string

Specify now to bypass the publishing schedule. Specify next to use publishing schedule.

Request body

resourcestring required

The id of the resource this asset is for

namestring

Name of the asset

pathstring

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. Paths begining with "/dxdam/" are managed assets.

descriptionstring

Description of the asset

idstring

The id of the asset to create

categoryIdsstring[]

The IDs of the categories that define how this asset is categorized.

status'ready' | 'draft' | 'retired'

The workflow status of the asset. This value can only be set for managed assets.

Example request

{
  "resource": "8d21025d21e7b3595cbf630fb9d7212b",
  "path": "/Screen Shot 2016-05-11 at 6.52.22 PM",
  "description": "Screenshot",
  "name": "Important screenshot",
  "tags": {
    "values": [
      "screenshot"
    ]
  },
  "status": "draft"
}

Response

Successfully created a new asset.

idstring

The id of the asset.

revstring

The revision of the asset.

namestring

Name of the asset.

classification'asset'

The classification of the asset is always "asset".

assetType'image' | 'video' | 'file'

The type of asset. Determined by the media type of the resource.

descriptionstring

Description of the asset.

creatorIdstring

The ID of the user that created the asset.

createdstring date-time

The date and time the asset was created.

creatorstring

The name of the user who originally created the asset.

lastModifierIdstring

The ID of the user that last modified the asset.

lastModifiedstring date-time

The date and time the asset was last modified.

lastModifierstring

The name of the user who last modified the item.

systemModifiedstring date-time

The date and time the asset was last modified by the system.

fileNamestring

The file name of the asset's resource.

fileSizeinteger

The size of the asset's resource in bytes.

mediaTypestring

Media type of the asset's resource.

keywordsstring[]

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.

resourcestring required

The ID of the uploaded resource this asset contains.

digeststring

The Base64 encoded MD5 digest of the resouce the asset contains.

pathstring

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.

categoryIdsstring[]

The IDs of the categories that define how this asset is categorized.

profilesstring[]

The IDs of image profiles to add to use on this asset.

status'ready' | 'draft' | 'retired'

The workflow status of the asset.

validboolean

Boolean that indicates if an asset can be transitioned from draft to ready. Only available on draft assets.

draftStatus'in-review' | 'in-progress' | 'approved'

This property shows the status of the draft and is only valid for draft items. By default, it is in-progress.

isManagedboolean

This field indicates whether the asset is managed or not. An asset is considered managed only if its asset path starts with "dxdam".

altTextstring

A text description of the asset, used when the asset itself is not available or not displayed.

captionstring

A caption of the asset image.

linkedDocIdstring

Provided on drafts of existing items. This is the ID of the primary item.

categoriesstring[]
isSystemboolean

Indicates whether this item is a 'system item' or not. 'System item' means that this is an item managed internally by Acoustic.

libraryIdstring

If this property is set it points to library id that the item is assigned to.

Example response

{
  "id": "0a800487f06d71eaf4cffdfde1ab28bc",
  "rev": "2-c839bbb8844549c2e298275c4b2adcb8",
  "description": "This is an image of a person.",
  "creatorId": "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
  "lastModifierId": "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
  "fileName": "hub.png",
  "fileSize": 123125,
  "mediaType": "image/png",
  "tags": {
    "values": [
      "faces:Lebron James",
      "sports",
      "basketball"
    ]
  },
  "resource": "67c621ed48921b7338b84b4f415cba6b",
  "digest": "9jwWuI3TN+PhGfHcrSJHcQ==",
  "path": "/sales/images/hub.png",
  "categoryIds": [],
  "profiles": [
    "8b4698e3-6283-4bc5-9e1e-fff69c2b48be"
  ],
  "profileRenditions": [
    {
      "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
    }
  ],
  "links": {
    "self": {
      "href": "/authoring/v1/assets/1e5fecbb-04aa-4ed2-a014-8e544ad97597:draft"
    },
    "media": {
      "href": "/authoring/v1/resource/myResource.jpeg"
    },
    "thumbnail": {
      "href": "/authoring/v1/resource/myResource.jpeg?fit=around|220:145&crop=220:145;*,*"
    },
    "ready": {
      "href": "/authoring/v1/changes/asset/1e5fecbb-04aa-4ed2-a014-8e544ad97597:draft/status/ready"
    },
    "retire": {
      "href": "/authoring/v1/changes/asset/1e5fecbb-04aa-4ed2-a014-8e544ad97597:draft/status/retire"
    },
    "linkedDoc": {
      "href": "/authoring/v1/assets/1e5fecbb-04aa-4ed2-a014-8e544ad97597"
    }
  },
  "usageRights": {
    "categories": [
      {
        "id": "00000000-0000-0000-0000-021000c8e20",
        "path": "Usage rights/Rights managed/Usage realm/Advertising"
      }
    ],
    "expiration": "2017-08-28T14:00:00Z"
  },
  "review": {
    "id": "3356c048-96d0-4d8d-9afe-5e7ae47b127a",
    "name": "my review",
    "started": "2017-07-10T03:20:10Z",
    "ends": "2017-07-10T03:20:10Z",
    "ended": "2017-07-12T19:40:10Z"
  },
  "metadata": {
    "width": 1000,
    "height": 1000,
    "camera": {
      "make": "NIKON CORPORATION",
      "model": "NIKON D90",
      "focalLength": 35,
      "shutterSpeed": "1/200",
      "iso": 100,
      "aperture": 8
    },
    "coverage": "1972-",
    "creator": "Acoustic",
    "Date": "2017-10-23T01:23:57Z",
    "description": "The Acoustic logo.",
    "publisher": "Acoustic",
    "rights": "Acoustic",
    "source": "Acoustic",
    "title": "Acoustic Logo",
    "headline": "The Acoustic logo."
  },
  "cognitive": {
    "faces": [
      {
        "name": "Brad Pitt",
        "gender": "Male",
        "age": {
          "minimum": 35,
          "maximum": 44
        }
      }
    ],
    "colors": {
      "vibrant": "#c78061",
      "muted": "#ae7157",
      "darkVibrant": "#4c2c1c",
      "darkMuted": "#50453f",
      "lightVibrant": "#d4a185",
      "lightMuted": "#d4bcac"
    },
    "entities": "people"
  },
  "altText": "This is an image of the Acoustic logo.",
  "caption": "Acoustic",
  "linkedDocId": "b289c02e-2c61-4643-aba6-e6b4e94c76e3",
  "categories": [
    "banner"
  ]
}