IBM Watson Content Hub

Live

IBM Watson Content Hub

+ Day(s) remaining in the trial

Overview

IBM Watson Content Hub is a cloud content management system with integrated asset classification features from IBM Watson. Developers can use APIs to create and manage content, and to integrate content into their mobile applications, web apps, or any other channel where content is required. The product also provides a graphical user interface for business users to create and manage content. The following APIs are now available for Watson Content Hub: - Authoring services APIs, which require authentication and are not optimized for retrieval by applications in production. - Delivery services APIs, which can be accessed anonymously and are optimized for caching and performance. The two APIs are similar and you can switch between the authoring and delivery services by changing the URL path in the code. For example, change the path from authoring to resources in the following authoring resource URL https://{DomainName}/{path}/authoring/v1/resources/{resource-id} to switch to the delivery resource service URL https://{DomainName}/{path}/delivery/v1/resources/{resource-id}. Note: Since the Authoring services require authentication you can switch from the delivery resource URL only after the log in call.

Getting started

Authentication

Most of the IBM Watson Content Hub REST API services require authentication before you can access them. The following instructions describe how to get authentication and then call the authenticated APIs.

To make authenticated IBM Watson Content Hub REST API calls, you need the following information:

  1. The API URL for your tenant, for example https://my12.digitalexperience.ibm.com/api/12345678-9abc-def0-1234-56789abcdef0.
  2. A cookie that contains the authentication token.

Note: Although the samples on the right hand side of the IBM Watson Content Hub API documentation mention setting the headers X-IBM-Client-Id and X-IBM-Client-Secret they are currently not needed. For more information, see the API Keys section.

Obtaining the API URL for your tenant to use the IBM Watson Content Hub API

You can get the API URL in one of the following ways:

  1. From the IBM Watson Content Hub user interface

    Open the User menu by clicking the drop down arrow near the user name and then click Hub information. A pop-up window displays the items Content hub ID and Domain name.

    In the IBM Watson Content Hub API, besides the place-holder {DomainName} the place-holder {path} is used which is constructed as {path} = api/{Content hub ID}. Therefore, the API URL to access the IBM Watson Content Hub API is constructed as follows: {API URL} = https://{DomainName}/{path}.

  2. By calling the IBM Watson Content Hub login service

    The following cURL example shows how to retrieve the Domain name and the Content hub ID by calling the login service.

    curl -v -u blueidUser@domain.com:password https://my.digitalexperience.ibm.com/api/login/v1/basicauth

    The call returns the header x-ibm-dx-tenant-base-url, which contains the API URL.

For example, you would get {DomainName} = my12.digitalexperience.ibm.com and {path} = api/12345678-9abc-def0-1234-56789abcdef0. In the following API description, replace the {DomainName} and {path} place-holders with your specific data.

Obtaining the authentication token with HTTP Basic authentication

Log in with the API URL and retrieve the authentication token. For example, login and retrieve the authentication token with the following cURL command:

curl -v -c cookie.txt -u blueidUser@domain.com:password https://{DomainName}/{path}/login/v1/basicauth

This command stores the authentication token in the file cookie.txt.

Using the obtained information to call an API

For example, the request https://{DomainName}/{path}/authoring/v1/assets converts to the following command:

curl -b cookie.txt https://my12.digitalexperience.ibm.com/api/12345678-9abc-def0-1234-56789abcdef0/authoring/v1/assets

You can find a link in the resources section that provides more examples of authenticated calls to IBM Watson Content Hub.

User roles

Each API service operation has a set of user roles that are allowed for the operation. You can call only the service operations that are allowed for the specific role a user has.

The roles are organized in a hierarchy, that means each role in the list below has more rights than the roles following this role. For example, the Editor role has more rights than the Viewer and Anonymous role but less rights than Administrator and Manager.

The roles are

  • Administrator - can access all functionality including tenant administration tasks such as adding/removing users.
  • Manager - can create and manage content model, content, and assets.
  • Editor - can create and manage content and assets.
  • Viewer - can retrieve content and assets via the authoring APIs, but does not have access to the authoring UI.
  • Anonymous - cannot access any authoring functionality.

Preview mode

If, instead of using the standard host of IBM Watson Content Hub, the host is suffixed with -preview for APIs, IBM Watson Content Hub is operated in preview mode. In preview mode, besides accessing published data, IBM Watson Content Hub can also return draft data. Accessing IBM Watson Content Hub in preview mode requires at least Editor role privileges.

Throughput limits for tenants

IBM Watson Content Hub is used simultaneously by multiple customers through their tenants. To process resources for all customers, IBM Watson Content Hub limits the load that is imposed by each tenant. The throughput limit for trial and paying customers can be different. If the number of requests that are received by IBM Watson Content Hub is below the tenants throughput limit, the requests are processed without delay.

IBM Watson Content Hub limits the number of requests per second per tenant, if the number of incoming requests is above the throughput limit. The processing of the requests that are above the limit are delayed for a certain time until they can be processed. If the delay time for processing the requests is excessive, any additional requests are returned with the HTTP status code "429 Too Many Requests". When you write client applications by using the IBM Watson Content Hub, you must be aware of the following scenarios:

  • Requests from the client application can be returned with an HTTP status code 429. In such cases, the best approach would be to retry the request after some time.
  • If a client program issues a high number of requests to IBM Watson Content Hub API, limit the number of outstanding requests. Limiting the number of outstanding requests reduces the risk that requests are replied with HTTP status code 429. In case the client would issue too many requests per second, the request delay algorithm of IBM Watson Content Hub would limit the throughput.

HTTPS settings

IBM Watson Content Hub is configured for HTTPS usage. All HTTP requests are redirected to HTTPS. The enabled protocol is TLS 1.2 (strict). Ensure that you connect to IBM Watson Content Hub only with clients that support TLS 1.2. Clients that do not support the protocol cannot establish connection.

Note: Some clients that support TLS 1.2 have older protocols that are enabled by default, in this case change the configuration of your client to include TLS 1.2.

CORS support for API access from client-side JS

Cross-Origin Resource Sharing (CORS) can be used to enable secure cross-domain data transfers in client-side JavaScript. If you are calling IBM Watson Content Hub services from client-side JavaScript that is hosted on a different domain, you need to enable CORS for that domain. You must add only domains that require access to the content and assets stored in your content hub, such as your web servers or your development environment.

The domain format must be protocol://server:port. Here, the protocol is either http or https, the server is either your server name or its IP address, and the port is the port number of your server, for example, http://my.domain.org:80. You can also use the * wildcard to enable CORS for any domain.

To control the CORS enablement for IBM Watson Content Hub, from the menu bar in the IBM Watson Content Hub user interface, open Hub Setup and select General Settings and then open the Security tab.

API keys and authentication

IBM Watson Content Hub does not make use of the following two keys and header fields: X-IBM-Client-Id and X-IBM-Client-Secret.

Instead, for further information about authenticating to IBM Watson Content Hub, please refer to the IBM Watson Content Hub documentation.

Security

Keys

Pick a key to use with this API. Make sure you are logged in with your IBM id for your keys to be populated in the dropdown below. By selecting a key, it will be pre-filled for each endpoint in the Documentation section that can be used with the built-in testing. If you want to change which key to use for a particular endpoint, you can do so at the endpoint in the Documentation section.
You can manage your API keys in the <MyAPIs> section. API keys authenticate you to your subscription, so make sure to keep them secret. Do not share the X-IBM-Client-Secret portion of any API key in publicly accessible places such as GitHub, or client-side code.



Manage your keys
 

Documentation

IBM Watson Content Hub:

Authoring assets

Use the Watson Content Hub 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 Watson Content Hub UI. Additionally, these assets are able to have their workflow status managed.
Create a draft of existing asset.
Use this endpoint to create draft of existing asset and return the draft if successful.
User roles: admin, manager, editor

POST   /authoring/v1/assets/{id}/create-draft

			https://{DomainName}/{path}/authoring/v1/assets/{id}/create-draft
		
Keys
Header parameters

X-IBM-Client-Id

STRING , required

Client ID for the API

Path and Query parameters

fields

ARRAY , optional

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.

id

URL , required

Provide the ID of the asset item that you need to create draft of.

include

ARRAY , optional

Additional asset fields that are specified here are returned. Fields that can be included are links and metadata. Fields are to be provided as a comma-separated list.

Request code
								
HttpResponse<String> response = Unirest.post("https://{DomainName}/{path}/authoring/v1/assets/{id}/create-draft?include=undefined&fields=undefined") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .asString();
Response model

201

Successfully created a new asset draft of given asset.

Body

id

STRING , required

The id of the asset.

rev

STRING , required

The revision of the asset.

name

STRING , required

Name of the asset.

classification

STRING , required

The classification of the asset is always "asset".

assetType

STRING , required

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

description

STRING , required

Description of the asset.

creatorId

STRING , required

The ID of the user that created the asset.

created

STRING , required

The date and time the asset was created.

lastModifierId

STRING , required

The ID of the user that last modified the asset.

lastModified

STRING , required

The date and time the asset was last modified.

fileName

STRING , required

The file name of the asset's resource.

fileSize

INTEGER , required

The size of the asset's resource in bytes.

mediaType

STRING , required

Media type of the asset's resource.

keywords

ARRAY , optional

Keywords of an asset of document type, produced by cognitive analysis. Will be automatically set when watson analysis upon completion. Only populated for PDF, doc, html and plain text files.

tags

object , optional

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.

resource

STRING , required

The ID of the uploaded resource this asset contains.

digest

STRING , required

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

path

STRING , required

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.

categoryIds

ARRAY , optional

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

renditions

ARRAY , optional

The renditions for the asset. Mandatory for an image asset. Does not appear for a video or file asset.

status

STRING , required

The workflow status of the asset.

valid

BOOLEAN , optional

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

draftStatus

STRING , optional

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

links

object , optional

usageRights

object , optional

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.

review

object , optional

Information and/or state about the review.

metadata

object , optional

Information extracted from an image asset's metadata.

cognitive

object , optional

Information extracted from the asset produced by cognitive analysis

values

ARRAY , optional

Tags can be set here. Tags suggested by cognitive analysis should be copied into this array if you wish to accept them.

declined

ARRAY , optional

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.

suggested

ARRAY , optional

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.

analysis

STRING , optional

This field indicates the progress of watson analysis.

analysisStarted

INTEGER , optional

This field exists when analysis is launched but not complete. The value is the epoch time of when the analysis began.

id

STRING , required

The ID of the rendition.

source

STRING , required

The link to the rendition binary.

self

object , optional

Relative link to the asset

media

object , optional

The link to the resource binary.

thumbnail

object , optional

The link to a thumbnail of the image. Only avaliable for certain assets of type image.

href

STRING , required

Relative url

href

STRING , required

href

STRING , required

categories

ARRAY , optional

expiration

STRING , optional

The user will have up until this ISO 8601 specified date-time value before they no longer have permission to use the asset.

id

STRING , optional

The ID of the usage rights category associated to the asset.

path

STRING , optional

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.

id

STRING , required

ID of the review.

name

STRING , required

Name of the review.

started

STRING , required

The ISO 8601 date-time that the review started.

ends

STRING , optional

The ISO 8601 date-time that the review is to be completed by.

ended

STRING , optional

The ISO 8601 date-time that the review actually finished on.

ownerId

STRING , required

width

INTEGER , optional

Width of the image.

height

INTEGER , optional

Height of the image.

camera

object , optional

Digital camera information extracted from the image asset's metadata.

coverage

STRING , optional

Scope of the image. Possible uses include a location or a time period.

creator

STRING , optional

Creator of the image.

Date

STRING , optional

Creation date and time of the image.

description

STRING , optional

Description of the image.

publisher

STRING , optional

Publisher of the image.

rights

STRING , optional

Rights information of the image.

source

STRING , optional

Source information of the image.

subject

ARRAY , optional

Topic(s) of the image.

title

STRING , optional

Title of the image

headline

STRING , optional

Headline of the image

make

STRING , optional

The manufacturer of the camera used to take the photo.

model

STRING , optional

The model of the camera used to take the photo.

focalLength

INTEGER , optional

The focal length of the lens used to take the photo.

shutterSpeed

STRING , optional

The shutter speed setting of the camera used to take the photo.

iso

INTEGER , optional

The ISO setting of the camera used to take the photo.

aperture

INTEGER , optional

The aperture of the lens used to take the photo.

classifications

ARRAY , optional

The classification suggested by cognitive analysis

faces

ARRAY , optional

Person's details. Image asset only

colors

object , optional

Prominent colors from an image. Image asset only

concepts

ARRAY , optional

Perform concept extraction operations from documents

entities

STRING , optional

Perform entity extraction operations from documents

keywords

ARRAY , optional

Perform keyword extraction operations from documents

status

STRING , optional

This field indicates the progress of watson analysis

name

STRING , optional

Name of person

gender

STRING , optional

Gender of person

age

object , optional

Age range of person

minimum

INTEGER , optional

Minimum age of person

maximum

INTEGER , optional

Maximum age of person

vibrant

STRING , optional

muted

STRING , optional

darkVibrant

STRING , optional

darkMuted

STRING , optional

lightVibrant

STRING , optional

lightMuted

STRING , optional

400

The draft creation on provided asset is not supported.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

404

The asset item with ID {id} was not found.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , required

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

Additional properties reflecting the dynamic parts of the error condition.

cause

object , optional

This property can be used to transport causing error message records produced by a down stream service calls.

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

default

Unexpected error.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

Response example

201

Successfully created a new asset draft of given asset.

								{
  "id" : "0a800487f06d71eaf4cffdfde1ab28bc",
  "rev" : "2-c839bbb8844549c2e298275c4b2adcb8",
  "name" : string,
  "classification" : [asset],
  "assetType" : [image, video, file],
  "description" : "This is an image of a person.",
  "creatorId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
  "created" : string,
  "lastModifierId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
  "lastModified" : string,
  "fileName" : "hub.png",
  "fileSize" : 123125,
  "mediaType" : "image/png",
  "keywords" : [string],
  "tags" : {
    "values" : [string],
    "declined" : [string],
    "suggested" : [string],
    "analysis" : [complete, failed, none, pending],
    "analysisStarted" : integer
  },
  "resource" : "67c621ed48921b7338b84b4f415cba6b",
  "digest" : "9jwWuI3TN+PhGfHcrSJHcQ==",
  "path" : "/sales/images/hub.png",
  "categoryIds" : [string],
  "renditions" : [{
    "id" : string,
    "source" : string
  }],
  "status" : [ready, draft, retired],
  "valid" : boolean,
  "draftStatus" : [in-review, in-progress],
  "links" : {
    "self" : {
    "href" : "/a/b/c/1234"
  },
    "media" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b"
  },
    "thumbnail" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b?fit=around|220:145&crop=220:145;*,*"
  }
  },
  "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",
    "ownerId" : string
  },
  "metadata" : {
    "width" : 1000,
    "height" : 1000,
    "camera" : {
    "make" : "NIKON CORPORATION",
    "model" : "NIKON D90",
    "focalLength" : 35,
    "shutterSpeed" : "1/200",
    "iso" : 100,
    "aperture" : 8
  },
    "coverage" : "1972-",
    "creator" : "IBM",
    "Date" : "2017-10-23T01:23:57Z",
    "description" : "The IBM logo since 1972.",
    "publisher" : "IBM",
    "rights" : "IBM",
    "source" : "IBM",
    "subject" : [string],
    "title" : "IBM Logo",
    "headline" : "The IBM logo since 1972."
  },
  "cognitive" : {
    "classifications" : [string],
    "faces" : [{
    "name" : "Brad Pitt",
    "gender" : "Male",
    "age" : {
    "minimum" : 35,
    "maximum" : 44
  }
  }],
    "colors" : {
    "vibrant" : "#c78061",
    "muted" : "#ae7157",
    "darkVibrant" : "#4c2c1c",
    "darkMuted" : "#50453f",
    "lightVibrant" : "#d4a185",
    "lightMuted" : "#d4bcac"
  },
    "concepts" : [string],
    "entities" : "people",
    "keywords" : [string],
    "status" : [complete, failed, none, pending]
  }
}
							

400

The draft creation on provided asset is not supported.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

404

The asset item with ID {id} was not found.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

default

Unexpected error.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							
Create an asset.
Use this endpoint to create an asset. Note:- If Watson tag analysis is enabled, it starts in the background. Watson analyzes and provides tag recommendations for the asset that is created.
User roles: admin, manager, editor

POST   /authoring/v1/assets

			https://{DomainName}/{path}/authoring/v1/assets
		
Keys
Header parameters

X-IBM-Client-Id

STRING , required

Client ID for the API

Path and Query parameters

analyze

BOOLEAN , optional

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

autocurate

BOOLEAN , optional

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

fields

ARRAY , optional

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.

include

ARRAY , optional

Additional asset fields that are specified here are returned. Fields that can be included are links and metadata. Fields are to be provided as a comma-separated list.

Request code
								
HttpResponse<String> response = Unirest.post("https://{DomainName}/{path}/authoring/v1/assets?fields=undefined&include=undefined&analyze=true&autocurate=true") .header("accept", "application/json") .header("content-type", "application/json") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .body("{\"categoryIds\":[null],\"description\":\"string\",\"id\":\"string\",\"name\":\"string\",\"path\":\"string\",\"resource\":\"string\",\"status\":\"string\",\"tags\":{\"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\":[null]},\"type\":\"object\"}}") .asString();
Request model

resource

STRING , required

The id of the resource this asset is for

name

STRING , optional

Name of the asset

path

STRING , optional

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.

description

STRING , optional

Description of the asset

tags

OBJECT , optional

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.

id

STRING , optional

The id of the asset to create

categoryIds

ARRAY , optional

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

status

STRING , optional

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

values

ARRAY , optional

ARRAY , optional

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

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

201

Successfully created a new asset.

Body

id

STRING , required

The id of the asset.

rev

STRING , required

The revision of the asset.

name

STRING , required

Name of the asset.

classification

STRING , required

The classification of the asset is always "asset".

assetType

STRING , required

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

description

STRING , required

Description of the asset.

creatorId

STRING , required

The ID of the user that created the asset.

created

STRING , required

The date and time the asset was created.

lastModifierId

STRING , required

The ID of the user that last modified the asset.

lastModified

STRING , required

The date and time the asset was last modified.

fileName

STRING , required

The file name of the asset's resource.

fileSize

INTEGER , required

The size of the asset's resource in bytes.

mediaType

STRING , required

Media type of the asset's resource.

keywords

ARRAY , optional

Keywords of an asset of document type, produced by cognitive analysis. Will be automatically set when watson analysis upon completion. Only populated for PDF, doc, html and plain text files.

tags

object , optional

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.

resource

STRING , required

The ID of the uploaded resource this asset contains.

digest

STRING , required

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

path

STRING , required

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.

categoryIds

ARRAY , optional

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

renditions

ARRAY , optional

The renditions for the asset. Mandatory for an image asset. Does not appear for a video or file asset.

status

STRING , required

The workflow status of the asset.

valid

BOOLEAN , optional

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

draftStatus

STRING , optional

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

links

object , optional

usageRights

object , optional

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.

review

object , optional

Information and/or state about the review.

metadata

object , optional

Information extracted from an image asset's metadata.

cognitive

object , optional

Information extracted from the asset produced by cognitive analysis

values

ARRAY , optional

Tags can be set here. Tags suggested by cognitive analysis should be copied into this array if you wish to accept them.

declined

ARRAY , optional

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.

suggested

ARRAY , optional

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.

analysis

STRING , optional

This field indicates the progress of watson analysis.

analysisStarted

INTEGER , optional

This field exists when analysis is launched but not complete. The value is the epoch time of when the analysis began.

id

STRING , required

The ID of the rendition.

source

STRING , required

The link to the rendition binary.

self

object , optional

Relative link to the asset

media

object , optional

The link to the resource binary.

thumbnail

object , optional

The link to a thumbnail of the image. Only avaliable for certain assets of type image.

href

STRING , required

Relative url

href

STRING , required

href

STRING , required

categories

ARRAY , optional

expiration

STRING , optional

The user will have up until this ISO 8601 specified date-time value before they no longer have permission to use the asset.

id

STRING , optional

The ID of the usage rights category associated to the asset.

path

STRING , optional

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.

id

STRING , required

ID of the review.

name

STRING , required

Name of the review.

started

STRING , required

The ISO 8601 date-time that the review started.

ends

STRING , optional

The ISO 8601 date-time that the review is to be completed by.

ended

STRING , optional

The ISO 8601 date-time that the review actually finished on.

ownerId

STRING , required

width

INTEGER , optional

Width of the image.

height

INTEGER , optional

Height of the image.

camera

object , optional

Digital camera information extracted from the image asset's metadata.

coverage

STRING , optional

Scope of the image. Possible uses include a location or a time period.

creator

STRING , optional

Creator of the image.

Date

STRING , optional

Creation date and time of the image.

description

STRING , optional

Description of the image.

publisher

STRING , optional

Publisher of the image.

rights

STRING , optional

Rights information of the image.

source

STRING , optional

Source information of the image.

subject

ARRAY , optional

Topic(s) of the image.

title

STRING , optional

Title of the image

headline

STRING , optional

Headline of the image

make

STRING , optional

The manufacturer of the camera used to take the photo.

model

STRING , optional

The model of the camera used to take the photo.

focalLength

INTEGER , optional

The focal length of the lens used to take the photo.

shutterSpeed

STRING , optional

The shutter speed setting of the camera used to take the photo.

iso

INTEGER , optional

The ISO setting of the camera used to take the photo.

aperture

INTEGER , optional

The aperture of the lens used to take the photo.

classifications

ARRAY , optional

The classification suggested by cognitive analysis

faces

ARRAY , optional

Person's details. Image asset only

colors

object , optional

Prominent colors from an image. Image asset only

concepts

ARRAY , optional

Perform concept extraction operations from documents

entities

STRING , optional

Perform entity extraction operations from documents

keywords

ARRAY , optional

Perform keyword extraction operations from documents

status

STRING , optional

This field indicates the progress of watson analysis

name

STRING , optional

Name of person

gender

STRING , optional

Gender of person

age

object , optional

Age range of person

minimum

INTEGER , optional

Minimum age of person

maximum

INTEGER , optional

Maximum age of person

vibrant

STRING , optional

muted

STRING , optional

darkVibrant

STRING , optional

darkMuted

STRING , optional

lightVibrant

STRING , optional

lightMuted

STRING , optional

400

The required parameters are missing or invalid, or the number of allowed assets have been reached. Please read the error message and alter the request accordingly.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

409

An asset already exists with the given ID.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , required

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

Additional properties reflecting the dynamic parts of the error condition.

cause

object , optional

This property can be used to transport causing error message records produced by a down stream service calls.

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

503

Connection failed to data store.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

default

Unexpected error.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

Response example

201

Successfully created a new asset.

								{
  "id" : "0a800487f06d71eaf4cffdfde1ab28bc",
  "rev" : "2-c839bbb8844549c2e298275c4b2adcb8",
  "name" : string,
  "classification" : [asset],
  "assetType" : [image, video, file],
  "description" : "This is an image of a person.",
  "creatorId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
  "created" : string,
  "lastModifierId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
  "lastModified" : string,
  "fileName" : "hub.png",
  "fileSize" : 123125,
  "mediaType" : "image/png",
  "keywords" : [string],
  "tags" : {
    "values" : [string],
    "declined" : [string],
    "suggested" : [string],
    "analysis" : [complete, failed, none, pending],
    "analysisStarted" : integer
  },
  "resource" : "67c621ed48921b7338b84b4f415cba6b",
  "digest" : "9jwWuI3TN+PhGfHcrSJHcQ==",
  "path" : "/sales/images/hub.png",
  "categoryIds" : [string],
  "renditions" : [{
    "id" : string,
    "source" : string
  }],
  "status" : [ready, draft, retired],
  "valid" : boolean,
  "draftStatus" : [in-review, in-progress],
  "links" : {
    "self" : {
    "href" : "/a/b/c/1234"
  },
    "media" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b"
  },
    "thumbnail" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b?fit=around|220:145&crop=220:145;*,*"
  }
  },
  "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",
    "ownerId" : string
  },
  "metadata" : {
    "width" : 1000,
    "height" : 1000,
    "camera" : {
    "make" : "NIKON CORPORATION",
    "model" : "NIKON D90",
    "focalLength" : 35,
    "shutterSpeed" : "1/200",
    "iso" : 100,
    "aperture" : 8
  },
    "coverage" : "1972-",
    "creator" : "IBM",
    "Date" : "2017-10-23T01:23:57Z",
    "description" : "The IBM logo since 1972.",
    "publisher" : "IBM",
    "rights" : "IBM",
    "source" : "IBM",
    "subject" : [string],
    "title" : "IBM Logo",
    "headline" : "The IBM logo since 1972."
  },
  "cognitive" : {
    "classifications" : [string],
    "faces" : [{
    "name" : "Brad Pitt",
    "gender" : "Male",
    "age" : {
    "minimum" : 35,
    "maximum" : 44
  }
  }],
    "colors" : {
    "vibrant" : "#c78061",
    "muted" : "#ae7157",
    "darkVibrant" : "#4c2c1c",
    "darkMuted" : "#50453f",
    "lightVibrant" : "#d4a185",
    "lightMuted" : "#d4bcac"
  },
    "concepts" : [string],
    "entities" : "people",
    "keywords" : [string],
    "status" : [complete, failed, none, pending]
  }
}
							

400

The required parameters are missing or invalid, or the number of allowed assets have been reached. Please read the error message and alter the request accordingly.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

409

An asset already exists with the given ID.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

503

Connection failed to data store.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

default

Unexpected error.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							
Delete an existing asset.
Use this endpoint to delete an existing asset from the database.
User roles: admin, manager, editor

DELETE   /authoring/v1/assets/{id}

			https://{DomainName}/{path}/authoring/v1/assets/{id}
		
Keys
Header parameters

If-Match

STRING , optional

Provide an Etag value from a previous request to check when an asset was last updated. If the Etag value that you provide is old, the call returns a 412 with the latest version of the asset.

X-IBM-Client-Id

STRING , required

Client ID for the API

Path and Query parameters

id

URL , required

Provide the ID of the asset that you want to delete.

Request code
								
HttpResponse<String> response = Unirest.delete("https://{DomainName}/{path}/authoring/v1/assets/{id}") .header("if-match", "string") .header("accept", "application/json") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .asString();
Response model

204

Successfully deleted the asset that matches the ID that you provided.

404

The asset with the provided id was not found.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

409

The Etag provided in the If-Match header does not correspond to the latest version.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , required

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

Additional properties reflecting the dynamic parts of the error condition.

cause

object , optional

This property can be used to transport causing error message records produced by a down stream service calls.

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

503

Connection failed to data store.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

default

Unexpected error.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

Response example

204

Successfully deleted the asset that matches the ID that you provided.

404

The asset with the provided id was not found.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

409

The Etag provided in the If-Match header does not correspond to the latest version.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

503

Connection failed to data store.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

default

Unexpected error.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							
Retrieve all assets.
Use this endpoint to retrieve all assets from the database.
User roles: admin, manager, editor, viewer

GET   /authoring/v1/assets

			https://{DomainName}/{path}/authoring/v1/assets
		
Keys
Header parameters

X-IBM-Client-Id

STRING , required

Client ID for the API

Path and Query parameters

fields

ARRAY , optional

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.

include

ARRAY , optional

Additional asset fields that are specified here are returned. Fields that can be included are links and metadata. Fields are to be provided as a comma-separated list.

limit

INTEGER , optional

Set the limit for the maximum number of assets to return in a single result. Set to 50 by default.

offset

INTEGER , optional

Use the offset parameter to specify the number of assets to skip from the beginning of the list and return the rest.

Request code
								
HttpResponse<String> response = Unirest.get("https://{DomainName}/{path}/authoring/v1/assets?limit=50&offset=0&fields=undefined&include=undefined") .header("accept", "application/json") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .asString();
Response model

200

Successfully lists a paged result view of all the asset in the database.

Body

limit

INTEGER , required

The page size. Set to 50 by default.

offset

INTEGER , required

The number of items to skip from the beginning of the list.

href

STRING , required

A link to the current page.

next

STRING , optional

A link to the next page. Only shown if a next page exists.

previous

STRING , optional

A link to the previous page. Only shown if a previous page exists.

items

ARRAY , optional

id

STRING , required

The id of the asset.

rev

STRING , required

The revision of the asset.

name

STRING , required

Name of the asset.

classification

STRING , required

The classification of the asset is always "asset".

assetType

STRING , required

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

description

STRING , required

Description of the asset.

creatorId

STRING , required

The ID of the user that created the asset.

created

STRING , required

The date and time the asset was created.

lastModifierId

STRING , required

The ID of the user that last modified the asset.

lastModified

STRING , required

The date and time the asset was last modified.

fileName

STRING , required

The file name of the asset's resource.

fileSize

INTEGER , required

The size of the asset's resource in bytes.

mediaType

STRING , required

Media type of the asset's resource.

keywords

ARRAY , optional

Keywords of an asset of document type, produced by cognitive analysis. Will be automatically set when watson analysis upon completion. Only populated for PDF, doc, html and plain text files.

tags

object , optional

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.

resource

STRING , required

The ID of the uploaded resource this asset contains.

digest

STRING , required

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

path

STRING , required

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.

categoryIds

ARRAY , optional

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

renditions

ARRAY , optional

The renditions for the asset. Mandatory for an image asset. Does not appear for a video or file asset.

status

STRING , required

The workflow status of the asset.

valid

BOOLEAN , optional

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

draftStatus

STRING , optional

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

links

object , optional

usageRights

object , optional

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.

review

object , optional

Information and/or state about the review.

metadata

object , optional

Information extracted from an image asset's metadata.

cognitive

object , optional

Information extracted from the asset produced by cognitive analysis

values

ARRAY , optional

Tags can be set here. Tags suggested by cognitive analysis should be copied into this array if you wish to accept them.

declined

ARRAY , optional

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.

suggested

ARRAY , optional

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.

analysis

STRING , optional

This field indicates the progress of watson analysis.

analysisStarted

INTEGER , optional

This field exists when analysis is launched but not complete. The value is the epoch time of when the analysis began.

id

STRING , required

The ID of the rendition.

source

STRING , required

The link to the rendition binary.

self

object , optional

Relative link to the asset

media

object , optional

The link to the resource binary.

thumbnail

object , optional

The link to a thumbnail of the image. Only avaliable for certain assets of type image.

href

STRING , required

Relative url

href

STRING , required

href

STRING , required

categories

ARRAY , optional

expiration

STRING , optional

The user will have up until this ISO 8601 specified date-time value before they no longer have permission to use the asset.

id

STRING , optional

The ID of the usage rights category associated to the asset.

path

STRING , optional

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.

id

STRING , required

ID of the review.

name

STRING , required

Name of the review.

started

STRING , required

The ISO 8601 date-time that the review started.

ends

STRING , optional

The ISO 8601 date-time that the review is to be completed by.

ended

STRING , optional

The ISO 8601 date-time that the review actually finished on.

ownerId

STRING , required

width

INTEGER , optional

Width of the image.

height

INTEGER , optional

Height of the image.

camera

object , optional

Digital camera information extracted from the image asset's metadata.

coverage

STRING , optional

Scope of the image. Possible uses include a location or a time period.

creator

STRING , optional

Creator of the image.

Date

STRING , optional

Creation date and time of the image.

description

STRING , optional

Description of the image.

publisher

STRING , optional

Publisher of the image.

rights

STRING , optional

Rights information of the image.

source

STRING , optional

Source information of the image.

subject

ARRAY , optional

Topic(s) of the image.

title

STRING , optional

Title of the image

headline

STRING , optional

Headline of the image

make

STRING , optional

The manufacturer of the camera used to take the photo.

model

STRING , optional

The model of the camera used to take the photo.

focalLength

INTEGER , optional

The focal length of the lens used to take the photo.

shutterSpeed

STRING , optional

The shutter speed setting of the camera used to take the photo.

iso

INTEGER , optional

The ISO setting of the camera used to take the photo.

aperture

INTEGER , optional

The aperture of the lens used to take the photo.

classifications

ARRAY , optional

The classification suggested by cognitive analysis

faces

ARRAY , optional

Person's details. Image asset only

colors

object , optional

Prominent colors from an image. Image asset only

concepts

ARRAY , optional

Perform concept extraction operations from documents

entities

STRING , optional

Perform entity extraction operations from documents

keywords

ARRAY , optional

Perform keyword extraction operations from documents

status

STRING , optional

This field indicates the progress of watson analysis

name

STRING , optional

Name of person

gender

STRING , optional

Gender of person

age

object , optional

Age range of person

minimum

INTEGER , optional

Minimum age of person

maximum

INTEGER , optional

Maximum age of person

vibrant

STRING , optional

muted

STRING , optional

darkVibrant

STRING , optional

darkMuted

STRING , optional

lightVibrant

STRING , optional

lightMuted

STRING , optional

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , required

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

Additional properties reflecting the dynamic parts of the error condition.

cause

object , optional

This property can be used to transport causing error message records produced by a down stream service calls.

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

503

Connection failed to data store.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

default

Unexpected error.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

Response example

200

Successfully lists a paged result view of all the asset in the database.

								{
  "limit" : 50,
  "offset" : 0,
  "href" : "/asset?offset=50&limit=50",
  "next" : "/asset?offset=100&limit=50",
  "previous" : "/asset?offset=0&limit=50",
  "items" : [{
    "id" : "0a800487f06d71eaf4cffdfde1ab28bc",
    "rev" : "2-c839bbb8844549c2e298275c4b2adcb8",
    "name" : string,
    "classification" : [asset],
    "assetType" : [image, video, file],
    "description" : "This is an image of a person.",
    "creatorId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
    "created" : string,
    "lastModifierId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
    "lastModified" : string,
    "fileName" : "hub.png",
    "fileSize" : 123125,
    "mediaType" : "image/png",
    "keywords" : [string],
    "tags" : {
    "values" : [string],
    "declined" : [string],
    "suggested" : [string],
    "analysis" : [complete, failed, none, pending],
    "analysisStarted" : integer
  },
    "resource" : "67c621ed48921b7338b84b4f415cba6b",
    "digest" : "9jwWuI3TN+PhGfHcrSJHcQ==",
    "path" : "/sales/images/hub.png",
    "categoryIds" : [string],
    "renditions" : [{
    "id" : string,
    "source" : string
  }],
    "status" : [ready, draft, retired],
    "valid" : boolean,
    "draftStatus" : [in-review, in-progress],
    "links" : {
    "self" : {
    "href" : "/a/b/c/1234"
  },
    "media" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b"
  },
    "thumbnail" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b?fit=around|220:145&crop=220:145;*,*"
  }
  },
    "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",
    "ownerId" : string
  },
    "metadata" : {
    "width" : 1000,
    "height" : 1000,
    "camera" : {
    "make" : "NIKON CORPORATION",
    "model" : "NIKON D90",
    "focalLength" : 35,
    "shutterSpeed" : "1/200",
    "iso" : 100,
    "aperture" : 8
  },
    "coverage" : "1972-",
    "creator" : "IBM",
    "Date" : "2017-10-23T01:23:57Z",
    "description" : "The IBM logo since 1972.",
    "publisher" : "IBM",
    "rights" : "IBM",
    "source" : "IBM",
    "subject" : [string],
    "title" : "IBM Logo",
    "headline" : "The IBM logo since 1972."
  },
    "cognitive" : {
    "classifications" : [string],
    "faces" : [{
    "name" : "Brad Pitt",
    "gender" : "Male",
    "age" : {
    "minimum" : 35,
    "maximum" : 44
  }
  }],
    "colors" : {
    "vibrant" : "#c78061",
    "muted" : "#ae7157",
    "darkVibrant" : "#4c2c1c",
    "darkMuted" : "#50453f",
    "lightVibrant" : "#d4a185",
    "lightMuted" : "#d4bcac"
  },
    "concepts" : [string],
    "entities" : "people",
    "keywords" : [string],
    "status" : [complete, failed, none, pending]
  }
  }]
}
							

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

503

Connection failed to data store.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

default

Unexpected error.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							
Retrieve all assets modified within the specified date
Use the /assets/views/by-modified endpoint to retrieve all assets that was modified within the date range specified.
User roles: admin, manager, editor, viewer

GET   /authoring/v1/assets/views/by-modified

			https://{DomainName}/{path}/authoring/v1/assets/views/by-modified
		
Keys
Header parameters

X-IBM-Client-Id

STRING , required

Client ID for the API

Path and Query parameters

end

STRING , optional

Provide the date and time of when the last modifications were made to the asset that you want returned. The assets that were modified on or before this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ.

fields

ARRAY , optional

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.

include

ARRAY , optional

Additional asset fields that are specified here are returned. Fields that can be included are links and metadata. Fields are to be provided as a comma-separated list.

limit

INTEGER , optional

Set the limit for the maximum number of assets to return in a single result.

offset

INTEGER , optional

Use the offset parameter to specify the number of assets to skip from the beginning of the list and return the rest.

order

STRING , optional

Specify whether you want the assets to be returned in ascending or descending order. Assets are returned in descending order by default.

start

STRING , optional

Provide the date and time of when the last modifications were made to the asset that you want returned. The assets that were modified on or after this date and time are returned. The date value must be in the ISO 8601 format YYYY-MM-DD T hh:mm:ss:sssZ.

Request code
								
HttpResponse<String> response = Unirest.get("https://{DomainName}/{path}/authoring/v1/assets/views/by-modified?start=string&end=string&offset=0&limit=50&order=descending&fields=undefined&include=undefined") .header("accept", "application/json") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .asString();
Response model

200

Successfully lists a paged result view of all assets that was modified within the date range specified.

Body

limit

INTEGER , required

The page size. Set to 50 by default.

offset

INTEGER , required

The number of items to skip from the beginning of the list.

href

STRING , required

A link to the current page.

next

STRING , optional

A link to the next page. Only shown if a next page exists.

previous

STRING , optional

A link to the previous page. Only shown if a previous page exists.

items

ARRAY , optional

id

STRING , required

The id of the asset.

rev

STRING , required

The revision of the asset.

name

STRING , required

Name of the asset.

classification

STRING , required

The classification of the asset is always "asset".

assetType

STRING , required

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

description

STRING , required

Description of the asset.

creatorId

STRING , required

The ID of the user that created the asset.

created

STRING , required

The date and time the asset was created.

lastModifierId

STRING , required

The ID of the user that last modified the asset.

lastModified

STRING , required

The date and time the asset was last modified.

fileName

STRING , required

The file name of the asset's resource.

fileSize

INTEGER , required

The size of the asset's resource in bytes.

mediaType

STRING , required

Media type of the asset's resource.

keywords

ARRAY , optional

Keywords of an asset of document type, produced by cognitive analysis. Will be automatically set when watson analysis upon completion. Only populated for PDF, doc, html and plain text files.

tags

object , optional

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.

resource

STRING , required

The ID of the uploaded resource this asset contains.

digest

STRING , required

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

path

STRING , required

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.

categoryIds

ARRAY , optional

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

renditions

ARRAY , optional

The renditions for the asset. Mandatory for an image asset. Does not appear for a video or file asset.

status

STRING , required

The workflow status of the asset.

valid

BOOLEAN , optional

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

draftStatus

STRING , optional

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

links

object , optional

usageRights

object , optional

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.

review

object , optional

Information and/or state about the review.

metadata

object , optional

Information extracted from an image asset's metadata.

cognitive

object , optional

Information extracted from the asset produced by cognitive analysis

values

ARRAY , optional

Tags can be set here. Tags suggested by cognitive analysis should be copied into this array if you wish to accept them.

declined

ARRAY , optional

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.

suggested

ARRAY , optional

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.

analysis

STRING , optional

This field indicates the progress of watson analysis.

analysisStarted

INTEGER , optional

This field exists when analysis is launched but not complete. The value is the epoch time of when the analysis began.

id

STRING , required

The ID of the rendition.

source

STRING , required

The link to the rendition binary.

self

object , optional

Relative link to the asset

media

object , optional

The link to the resource binary.

thumbnail

object , optional

The link to a thumbnail of the image. Only avaliable for certain assets of type image.

href

STRING , required

Relative url

href

STRING , required

href

STRING , required

categories

ARRAY , optional

expiration

STRING , optional

The user will have up until this ISO 8601 specified date-time value before they no longer have permission to use the asset.

id

STRING , optional

The ID of the usage rights category associated to the asset.

path

STRING , optional

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.

id

STRING , required

ID of the review.

name

STRING , required

Name of the review.

started

STRING , required

The ISO 8601 date-time that the review started.

ends

STRING , optional

The ISO 8601 date-time that the review is to be completed by.

ended

STRING , optional

The ISO 8601 date-time that the review actually finished on.

ownerId

STRING , required

width

INTEGER , optional

Width of the image.

height

INTEGER , optional

Height of the image.

camera

object , optional

Digital camera information extracted from the image asset's metadata.

coverage

STRING , optional

Scope of the image. Possible uses include a location or a time period.

creator

STRING , optional

Creator of the image.

Date

STRING , optional

Creation date and time of the image.

description

STRING , optional

Description of the image.

publisher

STRING , optional

Publisher of the image.

rights

STRING , optional

Rights information of the image.

source

STRING , optional

Source information of the image.

subject

ARRAY , optional

Topic(s) of the image.

title

STRING , optional

Title of the image

headline

STRING , optional

Headline of the image

make

STRING , optional

The manufacturer of the camera used to take the photo.

model

STRING , optional

The model of the camera used to take the photo.

focalLength

INTEGER , optional

The focal length of the lens used to take the photo.

shutterSpeed

STRING , optional

The shutter speed setting of the camera used to take the photo.

iso

INTEGER , optional

The ISO setting of the camera used to take the photo.

aperture

INTEGER , optional

The aperture of the lens used to take the photo.

classifications

ARRAY , optional

The classification suggested by cognitive analysis

faces

ARRAY , optional

Person's details. Image asset only

colors

object , optional

Prominent colors from an image. Image asset only

concepts

ARRAY , optional

Perform concept extraction operations from documents

entities

STRING , optional

Perform entity extraction operations from documents

keywords

ARRAY , optional

Perform keyword extraction operations from documents

status

STRING , optional

This field indicates the progress of watson analysis

name

STRING , optional

Name of person

gender

STRING , optional

Gender of person

age

object , optional

Age range of person

minimum

INTEGER , optional

Minimum age of person

maximum

INTEGER , optional

Maximum age of person

vibrant

STRING , optional

muted

STRING , optional

darkVibrant

STRING , optional

darkMuted

STRING , optional

lightVibrant

STRING , optional

lightMuted

STRING , optional

400

The provided parameters are invalid. Please read the error message and alter the request accordingly.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , required

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

Additional properties reflecting the dynamic parts of the error condition.

cause

object , optional

This property can be used to transport causing error message records produced by a down stream service calls.

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

503

Connection failed to data store.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

default

Unexpected error.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

Response example

200

Successfully lists a paged result view of all assets that was modified within the date range specified.

								{
  "limit" : 50,
  "offset" : 0,
  "href" : "/asset?offset=50&limit=50",
  "next" : "/asset?offset=100&limit=50",
  "previous" : "/asset?offset=0&limit=50",
  "items" : [{
    "id" : "0a800487f06d71eaf4cffdfde1ab28bc",
    "rev" : "2-c839bbb8844549c2e298275c4b2adcb8",
    "name" : string,
    "classification" : [asset],
    "assetType" : [image, video, file],
    "description" : "This is an image of a person.",
    "creatorId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
    "created" : string,
    "lastModifierId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
    "lastModified" : string,
    "fileName" : "hub.png",
    "fileSize" : 123125,
    "mediaType" : "image/png",
    "keywords" : [string],
    "tags" : {
    "values" : [string],
    "declined" : [string],
    "suggested" : [string],
    "analysis" : [complete, failed, none, pending],
    "analysisStarted" : integer
  },
    "resource" : "67c621ed48921b7338b84b4f415cba6b",
    "digest" : "9jwWuI3TN+PhGfHcrSJHcQ==",
    "path" : "/sales/images/hub.png",
    "categoryIds" : [string],
    "renditions" : [{
    "id" : string,
    "source" : string
  }],
    "status" : [ready, draft, retired],
    "valid" : boolean,
    "draftStatus" : [in-review, in-progress],
    "links" : {
    "self" : {
    "href" : "/a/b/c/1234"
  },
    "media" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b"
  },
    "thumbnail" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b?fit=around|220:145&crop=220:145;*,*"
  }
  },
    "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",
    "ownerId" : string
  },
    "metadata" : {
    "width" : 1000,
    "height" : 1000,
    "camera" : {
    "make" : "NIKON CORPORATION",
    "model" : "NIKON D90",
    "focalLength" : 35,
    "shutterSpeed" : "1/200",
    "iso" : 100,
    "aperture" : 8
  },
    "coverage" : "1972-",
    "creator" : "IBM",
    "Date" : "2017-10-23T01:23:57Z",
    "description" : "The IBM logo since 1972.",
    "publisher" : "IBM",
    "rights" : "IBM",
    "source" : "IBM",
    "subject" : [string],
    "title" : "IBM Logo",
    "headline" : "The IBM logo since 1972."
  },
    "cognitive" : {
    "classifications" : [string],
    "faces" : [{
    "name" : "Brad Pitt",
    "gender" : "Male",
    "age" : {
    "minimum" : 35,
    "maximum" : 44
  }
  }],
    "colors" : {
    "vibrant" : "#c78061",
    "muted" : "#ae7157",
    "darkVibrant" : "#4c2c1c",
    "darkMuted" : "#50453f",
    "lightVibrant" : "#d4a185",
    "lightMuted" : "#d4bcac"
  },
    "concepts" : [string],
    "entities" : "people",
    "keywords" : [string],
    "status" : [complete, failed, none, pending]
  }
  }]
}
							

400

The provided parameters are invalid. Please read the error message and alter the request accordingly.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

503

Connection failed to data store.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

default

Unexpected error.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							
Retrieve an existing asset.
Use this endpoint to retrieve an existing asset that matches the ID that is specified from the database. A conditional request is supported.
User roles: admin, manager, editor, viewer

GET   /authoring/v1/assets/{id}

			https://{DomainName}/{path}/authoring/v1/assets/{id}
		
Keys
Header parameters

If-None-Match

STRING , optional

Provide the double quoted revision of the asset. If this value matches the newest version, a 304 Not Modified response will be returned.

X-IBM-Client-Id

STRING , required

Client ID for the API

Path and Query parameters

fields

ARRAY , optional

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.

id

URL , required

Provide the ID of the asset that you want to retrieve.

include

ARRAY , optional

Additional asset fields that are specified here are returned. Fields that can be included are links and metadata. Fields are to be provided as a comma-separated list.

Request code
								
HttpResponse<String> response = Unirest.get("https://{DomainName}/{path}/authoring/v1/assets/{id}?fields=undefined&include=undefined") .header("if-none-match", "string") .header("accept", "application/json") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .asString();
Response model

200

Successfully retrieved an existing asset that matches the ID that you provided.

Body

id

STRING , required

The id of the asset.

rev

STRING , required

The revision of the asset.

name

STRING , required

Name of the asset.

classification

STRING , required

The classification of the asset is always "asset".

assetType

STRING , required

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

description

STRING , required

Description of the asset.

creatorId

STRING , required

The ID of the user that created the asset.

created

STRING , required

The date and time the asset was created.

lastModifierId

STRING , required

The ID of the user that last modified the asset.

lastModified

STRING , required

The date and time the asset was last modified.

fileName

STRING , required

The file name of the asset's resource.

fileSize

INTEGER , required

The size of the asset's resource in bytes.

mediaType

STRING , required

Media type of the asset's resource.

keywords

ARRAY , optional

Keywords of an asset of document type, produced by cognitive analysis. Will be automatically set when watson analysis upon completion. Only populated for PDF, doc, html and plain text files.

tags

object , optional

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.

resource

STRING , required

The ID of the uploaded resource this asset contains.

digest

STRING , required

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

path

STRING , required

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.

categoryIds

ARRAY , optional

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

renditions

ARRAY , optional

The renditions for the asset. Mandatory for an image asset. Does not appear for a video or file asset.

status

STRING , required

The workflow status of the asset.

valid

BOOLEAN , optional

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

draftStatus

STRING , optional

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

links

object , optional

usageRights

object , optional

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.

review

object , optional

Information and/or state about the review.

metadata

object , optional

Information extracted from an image asset's metadata.

cognitive

object , optional

Information extracted from the asset produced by cognitive analysis

values

ARRAY , optional

Tags can be set here. Tags suggested by cognitive analysis should be copied into this array if you wish to accept them.

declined

ARRAY , optional

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.

suggested

ARRAY , optional

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.

analysis

STRING , optional

This field indicates the progress of watson analysis.

analysisStarted

INTEGER , optional

This field exists when analysis is launched but not complete. The value is the epoch time of when the analysis began.

id

STRING , required

The ID of the rendition.

source

STRING , required

The link to the rendition binary.

self

object , optional

Relative link to the asset

media

object , optional

The link to the resource binary.

thumbnail

object , optional

The link to a thumbnail of the image. Only avaliable for certain assets of type image.

href

STRING , required

Relative url

href

STRING , required

href

STRING , required

categories

ARRAY , optional

expiration

STRING , optional

The user will have up until this ISO 8601 specified date-time value before they no longer have permission to use the asset.

id

STRING , optional

The ID of the usage rights category associated to the asset.

path

STRING , optional

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.

id

STRING , required

ID of the review.

name

STRING , required

Name of the review.

started

STRING , required

The ISO 8601 date-time that the review started.

ends

STRING , optional

The ISO 8601 date-time that the review is to be completed by.

ended

STRING , optional

The ISO 8601 date-time that the review actually finished on.

ownerId

STRING , required

width

INTEGER , optional

Width of the image.

height

INTEGER , optional

Height of the image.

camera

object , optional

Digital camera information extracted from the image asset's metadata.

coverage

STRING , optional

Scope of the image. Possible uses include a location or a time period.

creator

STRING , optional

Creator of the image.

Date

STRING , optional

Creation date and time of the image.

description

STRING , optional

Description of the image.

publisher

STRING , optional

Publisher of the image.

rights

STRING , optional

Rights information of the image.

source

STRING , optional

Source information of the image.

subject

ARRAY , optional

Topic(s) of the image.

title

STRING , optional

Title of the image

headline

STRING , optional

Headline of the image

make

STRING , optional

The manufacturer of the camera used to take the photo.

model

STRING , optional

The model of the camera used to take the photo.

focalLength

INTEGER , optional

The focal length of the lens used to take the photo.

shutterSpeed

STRING , optional

The shutter speed setting of the camera used to take the photo.

iso

INTEGER , optional

The ISO setting of the camera used to take the photo.

aperture

INTEGER , optional

The aperture of the lens used to take the photo.

classifications

ARRAY , optional

The classification suggested by cognitive analysis

faces

ARRAY , optional

Person's details. Image asset only

colors

object , optional

Prominent colors from an image. Image asset only

concepts

ARRAY , optional

Perform concept extraction operations from documents

entities

STRING , optional

Perform entity extraction operations from documents

keywords

ARRAY , optional

Perform keyword extraction operations from documents

status

STRING , optional

This field indicates the progress of watson analysis

name

STRING , optional

Name of person

gender

STRING , optional

Gender of person

age

object , optional

Age range of person

minimum

INTEGER , optional

Minimum age of person

maximum

INTEGER , optional

Maximum age of person

vibrant

STRING , optional

muted

STRING , optional

darkVibrant

STRING , optional

darkMuted

STRING , optional

lightVibrant

STRING , optional

lightMuted

STRING , optional

304

The Etag provided in the If-None-Match header corresponds to the latest version.

404

The asset with the provided id was not found.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

412

The Etag provided in the If-None-Match header does not correspond to the latest version.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , required

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

Additional properties reflecting the dynamic parts of the error condition.

cause

object , optional

This property can be used to transport causing error message records produced by a down stream service calls.

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

503

Connection failed to data store.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

default

Unexpected error.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

Response example

200

Successfully retrieved an existing asset that matches the ID that you provided.

								{
  "id" : "0a800487f06d71eaf4cffdfde1ab28bc",
  "rev" : "2-c839bbb8844549c2e298275c4b2adcb8",
  "name" : string,
  "classification" : [asset],
  "assetType" : [image, video, file],
  "description" : "This is an image of a person.",
  "creatorId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
  "created" : string,
  "lastModifierId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
  "lastModified" : string,
  "fileName" : "hub.png",
  "fileSize" : 123125,
  "mediaType" : "image/png",
  "keywords" : [string],
  "tags" : {
    "values" : [string],
    "declined" : [string],
    "suggested" : [string],
    "analysis" : [complete, failed, none, pending],
    "analysisStarted" : integer
  },
  "resource" : "67c621ed48921b7338b84b4f415cba6b",
  "digest" : "9jwWuI3TN+PhGfHcrSJHcQ==",
  "path" : "/sales/images/hub.png",
  "categoryIds" : [string],
  "renditions" : [{
    "id" : string,
    "source" : string
  }],
  "status" : [ready, draft, retired],
  "valid" : boolean,
  "draftStatus" : [in-review, in-progress],
  "links" : {
    "self" : {
    "href" : "/a/b/c/1234"
  },
    "media" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b"
  },
    "thumbnail" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b?fit=around|220:145&crop=220:145;*,*"
  }
  },
  "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",
    "ownerId" : string
  },
  "metadata" : {
    "width" : 1000,
    "height" : 1000,
    "camera" : {
    "make" : "NIKON CORPORATION",
    "model" : "NIKON D90",
    "focalLength" : 35,
    "shutterSpeed" : "1/200",
    "iso" : 100,
    "aperture" : 8
  },
    "coverage" : "1972-",
    "creator" : "IBM",
    "Date" : "2017-10-23T01:23:57Z",
    "description" : "The IBM logo since 1972.",
    "publisher" : "IBM",
    "rights" : "IBM",
    "source" : "IBM",
    "subject" : [string],
    "title" : "IBM Logo",
    "headline" : "The IBM logo since 1972."
  },
  "cognitive" : {
    "classifications" : [string],
    "faces" : [{
    "name" : "Brad Pitt",
    "gender" : "Male",
    "age" : {
    "minimum" : 35,
    "maximum" : 44
  }
  }],
    "colors" : {
    "vibrant" : "#c78061",
    "muted" : "#ae7157",
    "darkVibrant" : "#4c2c1c",
    "darkMuted" : "#50453f",
    "lightVibrant" : "#d4a185",
    "lightMuted" : "#d4bcac"
  },
    "concepts" : [string],
    "entities" : "people",
    "keywords" : [string],
    "status" : [complete, failed, none, pending]
  }
}
							

304

The Etag provided in the If-None-Match header corresponds to the latest version.

404

The asset with the provided id was not found.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

412

The Etag provided in the If-None-Match header does not correspond to the latest version.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

503

Connection failed to data store.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

default

Unexpected error.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							
Retrieve an existing asset by path.
Use this endpoint to retrieve an existing asset that matches the path that has been set. A conditional request is supported.
User roles: admin, manager, editor, viewer

GET   /authoring/v1/assets/record

			https://{DomainName}/{path}/authoring/v1/assets/record
		
Keys
Header parameters

If-None-Match

STRING , optional

Provide the double quoted revision of the asset. If this value matches the newest version, a 304 Not Modified response will be returned.

X-IBM-Client-Id

STRING , required

Client ID for the API

Path and Query parameters

fields

ARRAY , optional

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.

include

ARRAY , optional

Additional asset fields that are specified here are returned. Fields that can be included are links and metadata. Fields are to be provided as a comma-separated list.

path

STRING , required

Provide the path of the asset that you want to retrieve.

Request code
								
HttpResponse<String> response = Unirest.get("https://{DomainName}/{path}/authoring/v1/assets/record?path=string&fields=undefined&include=undefined") .header("if-none-match", "string") .header("accept", "application/json") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .asString();
Response model

200

Successfully retrieved an existing asset that matches the path that you provided.

Body

id

STRING , required

The id of the asset.

rev

STRING , required

The revision of the asset.

name

STRING , required

Name of the asset.

classification

STRING , required

The classification of the asset is always "asset".

assetType

STRING , required

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

description

STRING , required

Description of the asset.

creatorId

STRING , required

The ID of the user that created the asset.

created

STRING , required

The date and time the asset was created.

lastModifierId

STRING , required

The ID of the user that last modified the asset.

lastModified

STRING , required

The date and time the asset was last modified.

fileName

STRING , required

The file name of the asset's resource.

fileSize

INTEGER , required

The size of the asset's resource in bytes.

mediaType

STRING , required

Media type of the asset's resource.

keywords

ARRAY , optional

Keywords of an asset of document type, produced by cognitive analysis. Will be automatically set when watson analysis upon completion. Only populated for PDF, doc, html and plain text files.

tags

object , optional

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.

resource

STRING , required

The ID of the uploaded resource this asset contains.

digest

STRING , required

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

path

STRING , required

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.

categoryIds

ARRAY , optional

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

renditions

ARRAY , optional

The renditions for the asset. Mandatory for an image asset. Does not appear for a video or file asset.

status

STRING , required

The workflow status of the asset.

valid

BOOLEAN , optional

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

draftStatus

STRING , optional

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

links

object , optional

usageRights

object , optional

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.

review

object , optional

Information and/or state about the review.

metadata

object , optional

Information extracted from an image asset's metadata.

cognitive

object , optional

Information extracted from the asset produced by cognitive analysis

values

ARRAY , optional

Tags can be set here. Tags suggested by cognitive analysis should be copied into this array if you wish to accept them.

declined

ARRAY , optional

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.

suggested

ARRAY , optional

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.

analysis

STRING , optional

This field indicates the progress of watson analysis.

analysisStarted

INTEGER , optional

This field exists when analysis is launched but not complete. The value is the epoch time of when the analysis began.

id

STRING , required

The ID of the rendition.

source

STRING , required

The link to the rendition binary.

self

object , optional

Relative link to the asset

media

object , optional

The link to the resource binary.

thumbnail

object , optional

The link to a thumbnail of the image. Only avaliable for certain assets of type image.

href

STRING , required

Relative url

href

STRING , required

href

STRING , required

categories

ARRAY , optional

expiration

STRING , optional

The user will have up until this ISO 8601 specified date-time value before they no longer have permission to use the asset.

id

STRING , optional

The ID of the usage rights category associated to the asset.

path

STRING , optional

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.

id

STRING , required

ID of the review.

name

STRING , required

Name of the review.

started

STRING , required

The ISO 8601 date-time that the review started.

ends

STRING , optional

The ISO 8601 date-time that the review is to be completed by.

ended

STRING , optional

The ISO 8601 date-time that the review actually finished on.

ownerId

STRING , required

width

INTEGER , optional

Width of the image.

height

INTEGER , optional

Height of the image.

camera

object , optional

Digital camera information extracted from the image asset's metadata.

coverage

STRING , optional

Scope of the image. Possible uses include a location or a time period.

creator

STRING , optional

Creator of the image.

Date

STRING , optional

Creation date and time of the image.

description

STRING , optional

Description of the image.

publisher

STRING , optional

Publisher of the image.

rights

STRING , optional

Rights information of the image.

source

STRING , optional

Source information of the image.

subject

ARRAY , optional

Topic(s) of the image.

title

STRING , optional

Title of the image

headline

STRING , optional

Headline of the image

make

STRING , optional

The manufacturer of the camera used to take the photo.

model

STRING , optional

The model of the camera used to take the photo.

focalLength

INTEGER , optional

The focal length of the lens used to take the photo.

shutterSpeed

STRING , optional

The shutter speed setting of the camera used to take the photo.

iso

INTEGER , optional

The ISO setting of the camera used to take the photo.

aperture

INTEGER , optional

The aperture of the lens used to take the photo.

classifications

ARRAY , optional

The classification suggested by cognitive analysis

faces

ARRAY , optional

Person's details. Image asset only

colors

object , optional

Prominent colors from an image. Image asset only

concepts

ARRAY , optional

Perform concept extraction operations from documents

entities

STRING , optional

Perform entity extraction operations from documents

keywords

ARRAY , optional

Perform keyword extraction operations from documents

status

STRING , optional

This field indicates the progress of watson analysis

name

STRING , optional

Name of person

gender

STRING , optional

Gender of person

age

object , optional

Age range of person

minimum

INTEGER , optional

Minimum age of person

maximum

INTEGER , optional

Maximum age of person

vibrant

STRING , optional

muted

STRING , optional

darkVibrant

STRING , optional

darkMuted

STRING , optional

lightVibrant

STRING , optional

lightMuted

STRING , optional

304

The Etag provided in the If-None-Match header corresponds to the latest version.

400

The path provided was not valid.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

404

The asset with the provided path was not found.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

412

The Etag provided in the If-None-Match header does not correspond to the latest version.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , required

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

Additional properties reflecting the dynamic parts of the error condition.

cause

object , optional

This property can be used to transport causing error message records produced by a down stream service calls.

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

503

Connection failed to data store.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

default

Unexpected error.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

Response example

200

Successfully retrieved an existing asset that matches the path that you provided.

								{
  "id" : "0a800487f06d71eaf4cffdfde1ab28bc",
  "rev" : "2-c839bbb8844549c2e298275c4b2adcb8",
  "name" : string,
  "classification" : [asset],
  "assetType" : [image, video, file],
  "description" : "This is an image of a person.",
  "creatorId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
  "created" : string,
  "lastModifierId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
  "lastModified" : string,
  "fileName" : "hub.png",
  "fileSize" : 123125,
  "mediaType" : "image/png",
  "keywords" : [string],
  "tags" : {
    "values" : [string],
    "declined" : [string],
    "suggested" : [string],
    "analysis" : [complete, failed, none, pending],
    "analysisStarted" : integer
  },
  "resource" : "67c621ed48921b7338b84b4f415cba6b",
  "digest" : "9jwWuI3TN+PhGfHcrSJHcQ==",
  "path" : "/sales/images/hub.png",
  "categoryIds" : [string],
  "renditions" : [{
    "id" : string,
    "source" : string
  }],
  "status" : [ready, draft, retired],
  "valid" : boolean,
  "draftStatus" : [in-review, in-progress],
  "links" : {
    "self" : {
    "href" : "/a/b/c/1234"
  },
    "media" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b"
  },
    "thumbnail" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b?fit=around|220:145&crop=220:145;*,*"
  }
  },
  "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",
    "ownerId" : string
  },
  "metadata" : {
    "width" : 1000,
    "height" : 1000,
    "camera" : {
    "make" : "NIKON CORPORATION",
    "model" : "NIKON D90",
    "focalLength" : 35,
    "shutterSpeed" : "1/200",
    "iso" : 100,
    "aperture" : 8
  },
    "coverage" : "1972-",
    "creator" : "IBM",
    "Date" : "2017-10-23T01:23:57Z",
    "description" : "The IBM logo since 1972.",
    "publisher" : "IBM",
    "rights" : "IBM",
    "source" : "IBM",
    "subject" : [string],
    "title" : "IBM Logo",
    "headline" : "The IBM logo since 1972."
  },
  "cognitive" : {
    "classifications" : [string],
    "faces" : [{
    "name" : "Brad Pitt",
    "gender" : "Male",
    "age" : {
    "minimum" : 35,
    "maximum" : 44
  }
  }],
    "colors" : {
    "vibrant" : "#c78061",
    "muted" : "#ae7157",
    "darkVibrant" : "#4c2c1c",
    "darkMuted" : "#50453f",
    "lightVibrant" : "#d4a185",
    "lightMuted" : "#d4bcac"
  },
    "concepts" : [string],
    "entities" : "people",
    "keywords" : [string],
    "status" : [complete, failed, none, pending]
  }
}
							

304

The Etag provided in the If-None-Match header corresponds to the latest version.

400

The path provided was not valid.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

404

The asset with the provided path was not found.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

412

The Etag provided in the If-None-Match header does not correspond to the latest version.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

503

Connection failed to data store.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

default

Unexpected error.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							
Update an existing asset.
Use this end-point to update an existing asset that matches the ID that is specified. A conditional request is supported. Note:- If Watson tag analysis is enabled, it starts in the background. Watson analyzes and provides tag recommendations for the asset that is created.
User roles: admin, manager, editor

PUT   /authoring/v1/assets/{id}

			https://{DomainName}/{path}/authoring/v1/assets/{id}
		
Keys
Header parameters

If-Match

STRING , optional

Provide an Etag value from a previous request to check if the asset is the latest. If the value that you provided is old, a 412 Precondition Failed response will be returned.

X-IBM-Client-Id

STRING , required

Client ID for the API

Path and Query parameters

fields

ARRAY , optional

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.

forceOverride

BOOLEAN , optional

Specifies whether revision checking should be disabled.

id

URL , required

Provide the ID of the asset that you want to update.

include

ARRAY , optional

Additional asset fields that are specified here are returned. Fields that can be included are links and metadata. Fields are to be provided as a comma-separated list.

Request code
								
HttpResponse<String> response = Unirest.put("https://{DomainName}/{path}/authoring/v1/assets/{id}?fields=undefined&include=undefined&forceOverride=true") .header("if-match", "string") .header("accept", "application/json") .header("content-type", "application/json") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .body("{\"categoryIds\":[null],\"description\":\"string\",\"name\":\"string\",\"path\":\"string\",\"resource\":\"string\",\"tags\":[null]}") .asString();
Request model

resource

STRING , required

name

STRING , optional

path

STRING , optional

description

STRING , optional

tags

ARRAY , optional

categoryIds

ARRAY , optional

ARRAY , optional

ARRAY , optional

Request example
{"resource":"8d21025d21e7b3595cbf630fb9d7212b","path":"/Screen Shot 2016-05-11 at 6.52.22 PM","description":"Screenshot","tags":{"values":["screenshot"]}}
Response model

200

Successfully updated the asset that matches the ID that you provided.

Body

id

STRING , required

The id of the asset.

rev

STRING , required

The revision of the asset.

name

STRING , required

Name of the asset.

classification

STRING , required

The classification of the asset is always "asset".

assetType

STRING , required

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

description

STRING , required

Description of the asset.

creatorId

STRING , required

The ID of the user that created the asset.

created

STRING , required

The date and time the asset was created.

lastModifierId

STRING , required

The ID of the user that last modified the asset.

lastModified

STRING , required

The date and time the asset was last modified.

fileName

STRING , required

The file name of the asset's resource.

fileSize

INTEGER , required

The size of the asset's resource in bytes.

mediaType

STRING , required

Media type of the asset's resource.

keywords

ARRAY , optional

Keywords of an asset of document type, produced by cognitive analysis. Will be automatically set when watson analysis upon completion. Only populated for PDF, doc, html and plain text files.

tags

object , optional

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.

resource

STRING , required

The ID of the uploaded resource this asset contains.

digest

STRING , required

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

path

STRING , required

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.

categoryIds

ARRAY , optional

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

renditions

ARRAY , optional

The renditions for the asset. Mandatory for an image asset. Does not appear for a video or file asset.

status

STRING , required

The workflow status of the asset.

valid

BOOLEAN , optional

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

draftStatus

STRING , optional

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

links

object , optional

usageRights

object , optional

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.

review

object , optional

Information and/or state about the review.

metadata

object , optional

Information extracted from an image asset's metadata.

cognitive

object , optional

Information extracted from the asset produced by cognitive analysis

values

ARRAY , optional

Tags can be set here. Tags suggested by cognitive analysis should be copied into this array if you wish to accept them.

declined

ARRAY , optional

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.

suggested

ARRAY , optional

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.

analysis

STRING , optional

This field indicates the progress of watson analysis.

analysisStarted

INTEGER , optional

This field exists when analysis is launched but not complete. The value is the epoch time of when the analysis began.

id

STRING , required

The ID of the rendition.

source

STRING , required

The link to the rendition binary.

self

object , optional

Relative link to the asset

media

object , optional

The link to the resource binary.

thumbnail

object , optional

The link to a thumbnail of the image. Only avaliable for certain assets of type image.

href

STRING , required

Relative url

href

STRING , required

href

STRING , required

categories

ARRAY , optional

expiration

STRING , optional

The user will have up until this ISO 8601 specified date-time value before they no longer have permission to use the asset.

id

STRING , optional

The ID of the usage rights category associated to the asset.

path

STRING , optional

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.

id

STRING , required

ID of the review.

name

STRING , required

Name of the review.

started

STRING , required

The ISO 8601 date-time that the review started.

ends

STRING , optional

The ISO 8601 date-time that the review is to be completed by.

ended

STRING , optional

The ISO 8601 date-time that the review actually finished on.

ownerId

STRING , required

width

INTEGER , optional

Width of the image.

height

INTEGER , optional

Height of the image.

camera

object , optional

Digital camera information extracted from the image asset's metadata.

coverage

STRING , optional

Scope of the image. Possible uses include a location or a time period.

creator

STRING , optional

Creator of the image.

Date

STRING , optional

Creation date and time of the image.

description

STRING , optional

Description of the image.

publisher

STRING , optional

Publisher of the image.

rights

STRING , optional

Rights information of the image.

source

STRING , optional

Source information of the image.

subject

ARRAY , optional

Topic(s) of the image.

title

STRING , optional

Title of the image

headline

STRING , optional

Headline of the image

make

STRING , optional

The manufacturer of the camera used to take the photo.

model

STRING , optional

The model of the camera used to take the photo.

focalLength

INTEGER , optional

The focal length of the lens used to take the photo.

shutterSpeed

STRING , optional

The shutter speed setting of the camera used to take the photo.

iso

INTEGER , optional

The ISO setting of the camera used to take the photo.

aperture

INTEGER , optional

The aperture of the lens used to take the photo.

classifications

ARRAY , optional

The classification suggested by cognitive analysis

faces

ARRAY , optional

Person's details. Image asset only

colors

object , optional

Prominent colors from an image. Image asset only

concepts

ARRAY , optional

Perform concept extraction operations from documents

entities

STRING , optional

Perform entity extraction operations from documents

keywords

ARRAY , optional

Perform keyword extraction operations from documents

status

STRING , optional

This field indicates the progress of watson analysis

name

STRING , optional

Name of person

gender

STRING , optional

Gender of person

age

object , optional

Age range of person

minimum

INTEGER , optional

Minimum age of person

maximum

INTEGER , optional

Maximum age of person

vibrant

STRING , optional

muted

STRING , optional

darkVibrant

STRING , optional

darkMuted

STRING , optional

lightVibrant

STRING , optional

lightMuted

STRING , optional

400

The required parameters are missing or invalid, or the number of allowed assets have been reached. Please read the error message and alter the request accordingly.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

409

The asset was updated by another user whilst you tried to update it. Please review the latest version before retrying.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

412

The Etag provided in the If-Match header does not correspond to the latest version.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , required

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

Additional properties reflecting the dynamic parts of the error condition.

cause

object , optional

This property can be used to transport causing error message records produced by a down stream service calls.

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

503

Connection failed to data store.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

default

Unexpected error.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

Response example

200

Successfully updated the asset that matches the ID that you provided.

								{
  "id" : "0a800487f06d71eaf4cffdfde1ab28bc",
  "rev" : "2-c839bbb8844549c2e298275c4b2adcb8",
  "name" : string,
  "classification" : [asset],
  "assetType" : [image, video, file],
  "description" : "This is an image of a person.",
  "creatorId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
  "created" : string,
  "lastModifierId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
  "lastModified" : string,
  "fileName" : "hub.png",
  "fileSize" : 123125,
  "mediaType" : "image/png",
  "keywords" : [string],
  "tags" : {
    "values" : [string],
    "declined" : [string],
    "suggested" : [string],
    "analysis" : [complete, failed, none, pending],
    "analysisStarted" : integer
  },
  "resource" : "67c621ed48921b7338b84b4f415cba6b",
  "digest" : "9jwWuI3TN+PhGfHcrSJHcQ==",
  "path" : "/sales/images/hub.png",
  "categoryIds" : [string],
  "renditions" : [{
    "id" : string,
    "source" : string
  }],
  "status" : [ready, draft, retired],
  "valid" : boolean,
  "draftStatus" : [in-review, in-progress],
  "links" : {
    "self" : {
    "href" : "/a/b/c/1234"
  },
    "media" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b"
  },
    "thumbnail" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b?fit=around|220:145&crop=220:145;*,*"
  }
  },
  "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",
    "ownerId" : string
  },
  "metadata" : {
    "width" : 1000,
    "height" : 1000,
    "camera" : {
    "make" : "NIKON CORPORATION",
    "model" : "NIKON D90",
    "focalLength" : 35,
    "shutterSpeed" : "1/200",
    "iso" : 100,
    "aperture" : 8
  },
    "coverage" : "1972-",
    "creator" : "IBM",
    "Date" : "2017-10-23T01:23:57Z",
    "description" : "The IBM logo since 1972.",
    "publisher" : "IBM",
    "rights" : "IBM",
    "source" : "IBM",
    "subject" : [string],
    "title" : "IBM Logo",
    "headline" : "The IBM logo since 1972."
  },
  "cognitive" : {
    "classifications" : [string],
    "faces" : [{
    "name" : "Brad Pitt",
    "gender" : "Male",
    "age" : {
    "minimum" : 35,
    "maximum" : 44
  }
  }],
    "colors" : {
    "vibrant" : "#c78061",
    "muted" : "#ae7157",
    "darkVibrant" : "#4c2c1c",
    "darkMuted" : "#50453f",
    "lightVibrant" : "#d4a185",
    "lightMuted" : "#d4bcac"
  },
    "concepts" : [string],
    "entities" : "people",
    "keywords" : [string],
    "status" : [complete, failed, none, pending]
  }
}
							

400

The required parameters are missing or invalid, or the number of allowed assets have been reached. Please read the error message and alter the request accordingly.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

409

The asset was updated by another user whilst you tried to update it. Please review the latest version before retrying.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

412

The Etag provided in the If-Match header does not correspond to the latest version.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

503

Connection failed to data store.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

default

Unexpected error.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							
Watson analyzes the asset. The analysis results are stored on the asset itself.
Use the /assets/{id}/analyze endpoint to perform Watson analysis on asset if supported.
User roles: admin, manager, editor

POST   /authoring/v1/assets/{id}/analyze

			https://{DomainName}/{path}/authoring/v1/assets/{id}/analyze
		
Keys
Header parameters

X-IBM-Client-Id

STRING , required

Client ID for the API

Path and Query parameters

autocurate

BOOLEAN , optional

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

id

URL , required

Provide the ID of the asset item that you need to perform Watson analytics.

Request code
								
HttpResponse<String> response = Unirest.post("https://{DomainName}/{path}/authoring/v1/assets/{id}/analyze?autocurate=true") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .asString();
Response model

200

The asset after getting updated with watson analysis results.

Body

id

STRING , required

The id of the asset.

rev

STRING , required

The revision of the asset.

name

STRING , required

Name of the asset.

classification

STRING , required

The classification of the asset is always "asset".

assetType

STRING , required

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

description

STRING , required

Description of the asset.

creatorId

STRING , required

The ID of the user that created the asset.

created

STRING , required

The date and time the asset was created.

lastModifierId

STRING , required

The ID of the user that last modified the asset.

lastModified

STRING , required

The date and time the asset was last modified.

fileName

STRING , required

The file name of the asset's resource.

fileSize

INTEGER , required

The size of the asset's resource in bytes.

mediaType

STRING , required

Media type of the asset's resource.

keywords

ARRAY , optional

Keywords of an asset of document type, produced by cognitive analysis. Will be automatically set when watson analysis upon completion. Only populated for PDF, doc, html and plain text files.

tags

object , optional

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.

resource

STRING , required

The ID of the uploaded resource this asset contains.

digest

STRING , required

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

path

STRING , required

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.

categoryIds

ARRAY , optional

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

renditions

ARRAY , optional

The renditions for the asset. Mandatory for an image asset. Does not appear for a video or file asset.

status

STRING , required

The workflow status of the asset.

valid

BOOLEAN , optional

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

draftStatus

STRING , optional

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

links

object , optional

usageRights

object , optional

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.

review

object , optional

Information and/or state about the review.

metadata

object , optional

Information extracted from an image asset's metadata.

cognitive

object , optional

Information extracted from the asset produced by cognitive analysis

values

ARRAY , optional

Tags can be set here. Tags suggested by cognitive analysis should be copied into this array if you wish to accept them.

declined

ARRAY , optional

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.

suggested

ARRAY , optional

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.

analysis

STRING , optional

This field indicates the progress of watson analysis.

analysisStarted

INTEGER , optional

This field exists when analysis is launched but not complete. The value is the epoch time of when the analysis began.

id

STRING , required

The ID of the rendition.

source

STRING , required

The link to the rendition binary.

self

object , optional

Relative link to the asset

media

object , optional

The link to the resource binary.

thumbnail

object , optional

The link to a thumbnail of the image. Only avaliable for certain assets of type image.

href

STRING , required

Relative url

href

STRING , required

href

STRING , required

categories

ARRAY , optional

expiration

STRING , optional

The user will have up until this ISO 8601 specified date-time value before they no longer have permission to use the asset.

id

STRING , optional

The ID of the usage rights category associated to the asset.

path

STRING , optional

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.

id

STRING , required

ID of the review.

name

STRING , required

Name of the review.

started

STRING , required

The ISO 8601 date-time that the review started.

ends

STRING , optional

The ISO 8601 date-time that the review is to be completed by.

ended

STRING , optional

The ISO 8601 date-time that the review actually finished on.

ownerId

STRING , required

width

INTEGER , optional

Width of the image.

height

INTEGER , optional

Height of the image.

camera

object , optional

Digital camera information extracted from the image asset's metadata.

coverage

STRING , optional

Scope of the image. Possible uses include a location or a time period.

creator

STRING , optional

Creator of the image.

Date

STRING , optional

Creation date and time of the image.

description

STRING , optional

Description of the image.

publisher

STRING , optional

Publisher of the image.

rights

STRING , optional

Rights information of the image.

source

STRING , optional

Source information of the image.

subject

ARRAY , optional

Topic(s) of the image.

title

STRING , optional

Title of the image

headline

STRING , optional

Headline of the image

make

STRING , optional

The manufacturer of the camera used to take the photo.

model

STRING , optional

The model of the camera used to take the photo.

focalLength

INTEGER , optional

The focal length of the lens used to take the photo.

shutterSpeed

STRING , optional

The shutter speed setting of the camera used to take the photo.

iso

INTEGER , optional

The ISO setting of the camera used to take the photo.

aperture

INTEGER , optional

The aperture of the lens used to take the photo.

classifications

ARRAY , optional

The classification suggested by cognitive analysis

faces

ARRAY , optional

Person's details. Image asset only

colors

object , optional

Prominent colors from an image. Image asset only

concepts

ARRAY , optional

Perform concept extraction operations from documents

entities

STRING , optional

Perform entity extraction operations from documents

keywords

ARRAY , optional

Perform keyword extraction operations from documents

status

STRING , optional

This field indicates the progress of watson analysis

name

STRING , optional

Name of person

gender

STRING , optional

Gender of person

age

object , optional

Age range of person

minimum

INTEGER , optional

Minimum age of person

maximum

INTEGER , optional

Maximum age of person

vibrant

STRING , optional

muted

STRING , optional

darkVibrant

STRING , optional

darkMuted

STRING , optional

lightVibrant

STRING , optional

lightMuted

STRING , optional

400

The analysis of this asset is not supported.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

404

The asset item with ID {id} was not found.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , required

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

Additional properties reflecting the dynamic parts of the error condition.

cause

object , optional

This property can be used to transport causing error message records produced by a down stream service calls.

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

default

Unexpected error.

Body

requestId

STRING , required

The current request ID

service

STRING , required

The name of the service that produced the error

requestMethod

STRING , required

The Http method type of the current request

requestUri

STRING , required

The request uri

errors

ARRAY , optional

code

INTEGER , required

The message code

key

STRING , required

The message key

message

STRING , required

The error message

description

STRING , required

Optional detailed error message

category

STRING , required

The message category whereby only user messages are designed to be shown to an end user

level

STRING , required

Indicates the message level

parameters

object , optional

The message parameters of this message.

locale

STRING , required

The current locale used to produce the error message.

Response example

200

The asset after getting updated with watson analysis results.

								{
  "id" : "0a800487f06d71eaf4cffdfde1ab28bc",
  "rev" : "2-c839bbb8844549c2e298275c4b2adcb8",
  "name" : string,
  "classification" : [asset],
  "assetType" : [image, video, file],
  "description" : "This is an image of a person.",
  "creatorId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
  "created" : string,
  "lastModifierId" : "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e",
  "lastModified" : string,
  "fileName" : "hub.png",
  "fileSize" : 123125,
  "mediaType" : "image/png",
  "keywords" : [string],
  "tags" : {
    "values" : [string],
    "declined" : [string],
    "suggested" : [string],
    "analysis" : [complete, failed, none, pending],
    "analysisStarted" : integer
  },
  "resource" : "67c621ed48921b7338b84b4f415cba6b",
  "digest" : "9jwWuI3TN+PhGfHcrSJHcQ==",
  "path" : "/sales/images/hub.png",
  "categoryIds" : [string],
  "renditions" : [{
    "id" : string,
    "source" : string
  }],
  "status" : [ready, draft, retired],
  "valid" : boolean,
  "draftStatus" : [in-review, in-progress],
  "links" : {
    "self" : {
    "href" : "/a/b/c/1234"
  },
    "media" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b"
  },
    "thumbnail" : {
    "href" : "/authoring/v1/resource/67c621ed48921b7338b84b4f415cba6b?fit=around|220:145&crop=220:145;*,*"
  }
  },
  "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",
    "ownerId" : string
  },
  "metadata" : {
    "width" : 1000,
    "height" : 1000,
    "camera" : {
    "make" : "NIKON CORPORATION",
    "model" : "NIKON D90",
    "focalLength" : 35,
    "shutterSpeed" : "1/200",
    "iso" : 100,
    "aperture" : 8
  },
    "coverage" : "1972-",
    "creator" : "IBM",
    "Date" : "2017-10-23T01:23:57Z",
    "description" : "The IBM logo since 1972.",
    "publisher" : "IBM",
    "rights" : "IBM",
    "source" : "IBM",
    "subject" : [string],
    "title" : "IBM Logo",
    "headline" : "The IBM logo since 1972."
  },
  "cognitive" : {
    "classifications" : [string],
    "faces" : [{
    "name" : "Brad Pitt",
    "gender" : "Male",
    "age" : {
    "minimum" : 35,
    "maximum" : 44
  }
  }],
    "colors" : {
    "vibrant" : "#c78061",
    "muted" : "#ae7157",
    "darkVibrant" : "#4c2c1c",
    "darkMuted" : "#50453f",
    "lightVibrant" : "#d4a185",
    "lightMuted" : "#d4bcac"
  },
    "concepts" : [string],
    "entities" : "people",
    "keywords" : [string],
    "status" : [complete, failed, none, pending]
  }
}
							

400

The analysis of this asset is not supported.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

404

The asset item with ID {id} was not found.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

default

Unexpected error.

								{
  "requestId" : "d64dc285-0b62-aaa3-841f-de3588b64d34",
  "service" : "authoring-resource",
  "requestMethod" : "GET",
  "requestUri" : "/authoring/v1/assets",
  "errors" : [{
    "code" : integer,
    "key" : "error.asset.1",
    "message" : "The id requested does not exist.",
    "description" : "Please check the ID you provided is correct before retrying the request.",
    "category" : [API, USER],
    "level" : [INFO, WARNING, ERROR],
    "parameters" : object,
    "locale" : "en"
  }]
}
							

Loading content...