---
updatedAt: 2026-04-08T10:20:20.000Z
agentTools:
projectIndex: https://developer.goacoustic.com/acoustic-content/llms.txt
---
# 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
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"version": "1.0.142",
"x-ibm-name": "ibm-watson-content-hub-api",
"title": "Acoustic Content API",
"description": "Copyright © Acoustic, L.P. 2019"
},
"tags": [
{
"name": "Authoring assets",
"description": "\n## General\nUse the Content Asset service Rest APIs to work with assets. Assets are file types that are uploaded or created such as an image file, video file, or text that are used in content items. You can create, retrieve, update, and delete assets in a database. Managed assets are those located in the root dxdam directory as specified by its path and are visible on the Content UI.\n## Content workflow (status)\nThe status of a content item can be determined by the **suffix** of the ID:\n- An ID like xxxx:**draft** indicates that the item is a draft. This is the initial status of a new content item until it is published. A draft of a published content item will also have this suffix.\n- An ID like xxxx:***[publishing_job_id]*** - indicates that the content item has been scheduled for publish in the given publishing job.\n- An ID like xxxx with no suffix indicates that the content is **published** or **retired**.\nA draft can be created from published. When such a draft is published, it will override the previously published content.\n\n**Key notes:**\n- The base ID (xxxx) does not change. Only the suffix changes according to the workflow status of the item.\n- Where content and assets are referenced from within a content item, the 'raw' ID form, without a suffix, is always used. For example, when a draft content item is referenced by another draft content item, the reference appears as a raw ID, and thus does not change when the items are published.\n- API clients should not depend on the ID format and should not attempt to parse it. Instead, the ***linkedDocId*** and ***links*** properties should be used.\n- Draft item have a property ***linkedDocId***. This is the Id that the draft item will have when it is published.\n- Draft items that have a published version will have a ***linkedDoc*** property within the ***links*** property. This property will not appear for drafts that do not have a published version."
}
],
"paths": {
"/authoring/v1/assets/record": {
"get": {
"tags": [
"Authoring assets"
],
"summary": "Retrieve an existing asset by path.",
"description": "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",
"parameters": [
{
"name": "path",
"in": "query",
"description": "Provide the path of the asset that you want to retrieve.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "If-None-Match",
"in": "header",
"description": "Provide the double quoted revision of the asset. If this value matches the newest version, a 304 Not Modified response will be returned.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "fields",
"in": "query",
"description": "Only the asset fields that are specified here are returned for each result. Any asset field is a valid value and these can be specified in a comma-separated list. For example, to list the asset fields name and ID, provide the value ID, and name. All asset fields are returned by default.",
"required": false,
"allowEmptyValue": true,
"style": "form",
"explode": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"name": "include",
"in": "query",
"description": "Optional: Parameters used to include additional fields inside each returned asset. Use \"links\" to include the links section, which contains URLs for actions that can be performed on the asset. Use \"metadata\" to include additional fields for each of the items referenced by the asset You can specify multiple fields as a comma-separated value. For example, \"include=links,metadata\".",
"required": false,
"style": "form",
"explode": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Successfully retrieved an existing asset that matches the path that you provided.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The id of the asset.",
"readOnly": true,
"example": "0a800487f06d71eaf4cffdfde1ab28bc",
"maxLength": 100,
"pattern": "^[a-zA-Z0-9*.\\-_:]*$"
},
"rev": {
"type": "string",
"description": "The revision of the asset.",
"readOnly": true,
"pattern": "^[0-9]+-.*$",
"example": "2-c839bbb8844549c2e298275c4b2adcb8"
},
"name": {
"type": "string",
"description": "Name of the asset."
},
"classification": {
"type": "string",
"readOnly": true,
"enum": [
"asset"
],
"description": "The classification of the asset is always \"asset\"."
},
"assetType": {
"type": "string",
"readOnly": true,
"description": "The type of asset. Determined by the media type of the resource.",
"enum": [
"image",
"video",
"file"
]
},
"description": {
"type": "string",
"description": "Description of the asset.",
"example": "This is an image of a person.",
"maxLength": 500
},
"creatorId": {
"type": "string",
"readOnly": true,
"description": "The ID of the user that created the asset.",
"example": "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e"
},
"created": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "The date and time the asset was created."
},
"creator": {
"type": "string",
"readOnly": true,
"description": "The name of the user who originally created the asset."
},
"lastModifierId": {
"type": "string",
"readOnly": true,
"description": "The ID of the user that last modified the asset.",
"example": "e98c185a-cafb-4c32-ad94-dd4ffaa28a7e"
},
"lastModified": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "The date and time the asset was last modified."
},
"lastModifier": {
"type": "string",
"readOnly": true,
"description": "The name of the user who last modified the item."
},
"systemModified": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "The date and time the asset was last modified by the system."
},
"fileName": {
"type": "string",
"readOnly": true,
"description": "The file name of the asset's resource.",
"example": "hub.png"
},
"fileSize": {
"type": "integer",
"readOnly": true,
"description": "The size of the asset's resource in bytes.",
"example": 123125
},
"mediaType": {
"type": "string",
"readOnly": true,
"description": "Media type of the asset's resource.",
"example": "image/png"
},
"keywords": {
"type": "array",
"readOnly": true,
"items": {
"type": "string"
},
"description": "When AI analysis is complete, the document type assets will be automatically updated with keywords generated by the analysis. Keywords are updated only for PDF, doc, html, and plain text files."
},
"tags": {
"title": "Tags",
"type": "object",
"description": "The \"values\" array defines the user selected tags. The other two properties \"declined\" and \"suggested\" relate directly to the interaction with the cognitive analysis feature.",
"properties": {
"values": {
"type": "array",
"description": "Tags can be set here. Tags suggested by cognitive analysis should be copied into this array if you wish to accept them.",
"items": {
"type": "string"
},
"example": [
"faces:Lebron James",
"sports",
"basketball"
]
},
"declined": {
"type": "array",
"description": "This editable field is given for the store values from cogntivie analysis that the user has dismissed/rejected. This essentially. It is up to the API client to update this field. This field is not indexed for search.",
"items": {
"type": "string"
}
},
"suggested": {
"readOnly": true,
"description": "Suggested field is a read only field that is populated if cognitive analysis is done on this asset. Once reviewed the suggestions can be cleared with a query parameter see update endpoint. The tags come in the form of \"prefix:tag\" e.g. \"classification:sky\" This field is not indexed for search.",
"type": "array",
"items": {
"type": "string"
}
},
"analysis": {
"description": "This field indicates the progress of AI analysis.",
"readOnly": true,
"type": "string",
"enum": [
"complete",
"failed",
"none",
"pending"
]
},
"analysisStarted": {
"description": "This field exists when analysis is launched but not complete. The value is the epoch time of when the analysis began.",
"type": "integer",
"readOnly": true
}
},
"required": [
"values",
"declined"
]
},
"resource": {
"type": "string",
"description": "The ID of the uploaded resource this asset contains.",
"example": "67c621ed48921b7338b84b4f415cba6b"
},
"digest": {
"type": "string",
"description": "The Base64 encoded MD5 digest of the resouce the asset contains.",
"example": "9jwWuI3TN+PhGfHcrSJHcQ==",
"readOnly": true
},
"path": {
"type": "string",
"pattern": "^/[\\s\\S]+[^/]$",
"maxLength": 650,
"description": "The path to this asset, must begin with a leading slash. A unique constraint is placed on this path so that no other asset can have the same path. When updating path a collision results in error. Paths begining with \"/dxdam/\" are managed assets.",
"example": "/sales/images/hub.png"
},
"categoryIds": {
"type": "array",
"description": "The IDs of the categories that define how this asset is categorized.",
"items": {
"type": "string"
},
"example": []
},
"profiles": {
"type": "array",
"description": "The IDs of image profiles to add to use on this asset.",
"items": {
"type": "string"
},
"example": [
"8b4698e3-6283-4bc5-9e1e-fff69c2b48be"
]
},
"profileRenditions": {
"type": "array",
"description": "The transform instructions for each of the renditions in the \"profiles\" array. If a rendition for one of those image profiles is not defined, a rendition with the best fit will automatically be generated.",
"items": {
"title": "Profile Rendition",
"type": "object",
"properties": {
"profileId": {
"type": "string",
"description": "The ID of the image profile this rendition belongs to. This ID must also be specified in the \"profiles\" array."
},
"profileName": {
"type": "string",
"readOnly": true,
"description": "The name of the image profile this rendition belongs to. This field will only be included when metadata is provided as a value of the include query parameter."
},
"key": {
"type": "string",
"description": "The key to this rendition."
},
"label": {
"type": "string",
"readOnly": true,
"description": "The label to this rendition. This field will only be included when metadata is provided as a value of the include query parameter."
},
"uri": {
"type": "string",
"readOnly": true,
"description": "The URI to the resource in this rendition's dimensions."
},
"width": {
"type": "number",
"readOnly": true,
"description": "The width defined for this rendition."
},
"height": {
"type": "number",
"readOnly": true,
"description": "The height defined for this rendition."
},
"transform": {
"title": "Transform",
"type": "object",
"description": "The transform instructions to achieve this rendition's dimensions. If not specified, a best fit transformation will automatically be generated.",
"properties": {
"scale": {
"type": "number",
"description": "The scale to perform on the original resource. The value must be between 0 (exclusive) and 1 (inclusive)."
},
"crop": {
"title": "Crop",
"type": "object",
"description": "The crop to apply on the resource after any scaling has been done.",
"properties": {
"x": {
"type": "number",
"description": "The X coordinate to start the crop from"
},
"y": {
"type": "number",
"description": "The Y coordinate to start the crop from"
},
"width": {
"type": "number",
"description": "The width to crop out"
},
"height": {
"type": "number",
"description": "The height to crop out"
}
}
}
}
}
}
},
"example": [
{
"profileId": "a35f02ce-9f31-4832-8ed5-2b6d9c8b8d86",
"profileName": "Profile E",
"key": "renditionF",
"label": "Rendition F",
"transform": {
"scale": 0.0862,
"crop": {
"x": 0,
"y": 0,
"width": 10,
"height": 10
}
},
"uri": "/authoring/v1/resources/e17b2c51-a74e-4332-80df-0f6d9340426c?resize=10px:10px&crop=10:10;0,0",
"width": 10,
"height": 10
},
{
"profileId": "a35f02ce-9f31-4832-8ed5-2b6d9c8b8d86",
"profileName": "Profile E",
"key": "renditionG",
"label": "Rendition G",
"transform": {
"scale": 0.17241,
"crop": {
"x": 0,
"y": 0,
"width": 20,
"height": 20
}
},
"uri": "/authoring/v1/resources/e17b2c51-a74e-4332-80df-0f6d9340426c?resize=20px:20px&crop=20:20;0,0",
"width": 20,
"height": 20
}
]
},
"renditions": {
"title": "Renditions Metadata",
"type": "object",
"description": "The renditions for the asset. Mandatory for an image asset. Does not appear for a video or file asset.",
"properties": {
"default": {
"type": "object",
"properties": {
"id": {
"type": "string",
"readOnly": true,
"description": "The ID of the rendition."
},
"source": {
"type": "string",
"readOnly": true,
"description": "The link to the rendition binary."
}
}
}
}
},
"status": {
"type": "string",
"readOnly": true,
"description": "The workflow status of the asset.",
"enum": [
"ready",
"draft",
"retired"
]
},
"valid": {
"type": "boolean",
"readOnly": true,
"description": "Boolean that indicates if an asset can be transitioned from draft to ready. Only available on draft assets."
},
"draftStatus": {
"type": "string",
"description": "This property shows the status of the draft and is only valid for draft items. By default, it is in-progress.",
"default": "in-progress",
"enum": [
"in-review",
"in-progress",
"approved"
]
},
"links": {
"type": "object",
"title": "Asset Links",
"readOnly": true,
"properties": {
"self": {
"type": "object",
"description": "Relative link to the asset itself.",
"readOnly": true,
"properties": {
"href": {
"type": "string",
"readOnly": true,
"example": "/authoring/v1/assets/1e5fecbb-04aa-4ed2-a014-8e544ad97597:draft"
}
}
},
"media": {
"type": "object",
"description": "The link to the resource binary.",
"readOnly": true,
"properties": {
"href": {
"type": "string",
"readOnly": true,
"example": "/authoring/v1/resource/myResource.jpeg"
}
}
},
"thumbnail": {
"type": "object",
"description": "The link to a thumbnail of the image. Only avaliable for certain assets of type image.",
"readOnly": true,
"properties": {
"href": {
"type": "string",
"readOnly": true,
"example": "/authoring/v1/resource/myResource.jpeg?fit=around|220:145&crop=220:145;*,*"
}
}
},
"ready": {
"type": "object",
"description": "This link will appear for items that can be transitioned to the ready state.",
"properties": {
"href": {
"type": "string"
}
},
"example": {
"href": "/authoring/v1/changes/asset/1e5fecbb-04aa-4ed2-a014-8e544ad97597:draft/status/ready"
}
},
"retire": {
"type": "object",
"description": "This link will appear for items that can be transitioned to the retired state.",
"properties": {
"href": {
"type": "string"
}
},
"example": {
"href": "/authoring/v1/changes/asset/1e5fecbb-04aa-4ed2-a014-8e544ad97597:draft/status/retire"
}
},
"linkedDoc": {
"type": "object",
"description": "This link will appear if this item is a draft of an existing item. The link points to the primary item.",
"properties": {
"href": {
"type": "string"
}
},
"example": {
"href": "/authoring/v1/assets/1e5fecbb-04aa-4ed2-a014-8e544ad97597"
}
}
}
},
"usageRights": {
"title": "Usage Rights",
"type": "object",
"description": "Usage rights are assigned to assets to help composers understand where and when an asset can be used. For example, an asset might be used only in print, only for an advertising campaign, and only for a limited time.",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the usage rights category associated to the asset.",
"example": "00000000-0000-0000-0000-021000c8e20"
},
"path": {
"type": "string",
"description": "Name path of the usage rights category associated to the asset. This field will only be included when metadata is provided as a value of the include query parameter.",
"example": "Usage rights/Rights managed/Usage realm/Advertising"
}
}
}
},
"expiration": {
"type": "string",
"format": "date-time",
"description": "The user will have up until this ISO 8601 specified date-time value before they no longer have permission to use the asset.",
"example": "2017-08-28T14:00:00Z"
}
}
},
"review": {
"type": "object",
"description": "Information and/or state about the review.",
"properties": {
"id": {
"type": "string",
"description": "ID of the review.",
"example": "3356c048-96d0-4d8d-9afe-5e7ae47b127a"
},
"name": {
"type": "string",
"description": "Name of the review.",
"example": "my review"
},
"started": {
"type": "string",
"format": "date-time",
"description": "The ISO 8601 date-time that the review started.",
"example": "2017-07-10T03:20:10Z"
},
"ends": {
"type": "string",
"format": "date-time",
"description": "The ISO 8601 date-time that the review is to be completed by.",
"example": "2017-07-10T03:20:10Z"
},
"ended": {
"type": "string",
"format": "date-time",
"description": "The ISO 8601 date-time that the review actually finished on.",
"example": "2017-07-12T19:40:10Z"
},
"ownerId": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"name",
"started",
"ownerId"
]
},
"metadata": {
"type": "object",
"description": "Information extracted from an image asset's metadata.",
"properties": {
"width": {
"type": "integer",
"description": "Width of the image.",
"readOnly": true,
"example": 1000
},
"height": {
"type": "integer",
"description": "Height of the image.",
"readOnly": true,
"example": 1000
},
"camera": {
"type": "object",
"description": "Digital camera information extracted from the image asset's metadata.",
"properties": {
"make": {
"type": "string",
"description": "The manufacturer of the camera used to take the photo.",
"readOnly": true,
"example": "NIKON CORPORATION"
},
"model": {
"type": "string",
"description": "The model of the camera used to take the photo.",
"readOnly": true,
"example": "NIKON D90"
},
"focalLength": {
"type": "integer",
"description": "The focal length of the lens used to take the photo.",
"readOnly": true,
"example": 35
},
"shutterSpeed": {
"type": "string",
"description": "The shutter speed setting of the camera used to take the photo.",
"readOnly": true,
"example": "1/200"
},
"iso": {
"type": "integer",
"description": "The ISO setting of the camera used to take the photo.",
"readOnly": true,
"example": 100
},
"aperture": {
"type": "integer",
"description": "The aperture of the lens used to take the photo.",
"readOnly": true,
"example": 8
}
}
},
"coverage": {
"type": "string",
"description": "Scope of the image. Possible uses include a location or a time period.",
"readOnly": true,
"example": "1972-"
},
"creator": {
"type": "string",
"description": "Creator of the image.",
"readOnly": true,
"example": "Acoustic"
},
"Date": {
"type": "string",
"description": "Creation date and time of the image.",
"readOnly": true,
"example": "2017-10-23T01:23:57Z"
},
"description": {
"type": "string",
"description": "Description of the image.",
"readOnly": true,
"example": "The Acoustic logo."
},
"publisher": {
"type": "string",
"description": "Publisher of the image.",
"readOnly": true,
"example": "Acoustic"
},
"rights": {
"type": "string",
"description": "Rights information of the image.",
"readOnly": true,
"example": "Acoustic"
},
"source": {
"type": "string",
"description": "Source information of the image.",
"readOnly": true,
"example": "Acoustic"
},
"subject": {
"type": "array",
"description": "Topic(s) of the image.",
"readOnly": true,
"items": {
"type": "string",
"example": [
"Acoustic",
"logo"
]
}
},
"title": {
"type": "string",
"description": "Title of the image",
"readOnly": true,
"example": "Acoustic Logo"
},
"headline": {
"type": "string",
"description": "Headline of the image",
"readOnly": true,
"example": "The Acoustic logo."
}
}
},
"cognitive": {
"type": "object",
"description": "Information extracted from the asset produced by cognitive analysis",
"readOnly": true,
"properties": {
"classifications": {
"type": "array",
"description": "The classification suggested by cognitive analysis",
"readOnly": true,
"items": {
"type": "string",
"example": [
"people",
"person",
"adult person"
]
}
},
"faces": {
"type": "array",
"description": "Person's details. Image asset only",
"readOnly": true,
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of person",
"readOnly": true,
"example": "Brad Pitt"
},
"gender": {
"type": "string",
"description": "Gender of person",
"readOnly": true,
"example": "Male"
},
"age": {
"type": "object",
"description": "Age range of person",
"readOnly": true,
"properties": {
"minimum": {
"type": "integer",
"description": "Minimum age of person",
"readOnly": true,
"example": 35
},
"maximum": {
"type": "integer",
"description": "Maximum age of person",
"readOnly": true,
"example": 44
}
}
}
}
}
},
"colors": {
"type": "object",
"description": "Prominent colors from an image. Image asset only",
"readOnly": true,
"properties": {
"vibrant": {
"type": "string",
"example": "#c78061",
"readOnly": true
},
"muted": {
"type": "string",
"readOnly": true,
"example": "#ae7157"
},
"darkVibrant": {
"type": "string",
"readOnly": true,
"example": "#4c2c1c"
},
"darkMuted": {
"type": "string",
"readOnly": true,
"example": "#50453f"
},
"lightVibrant": {
"type": "string",
"readOnly": true,
"example": "#d4a185"
},
"lightMuted": {
"type": "string",
"readOnly": true,
"example": "#d4bcac"
}
}
},
"concepts": {
"type": "array",
"description": "Perform concept extraction operations from documents",
"readOnly": true,
"items": {
"type": "string",
"example": [
"Want",
"Need",
"2006 albums"
]
}
},
"entities": {
"type": "string",
"description": "Perform entity extraction operations from documents",
"readOnly": true,
"example": "people"
},
"keywords": {
"type": "array",
"description": "Perform keyword extraction operations from documents",
"readOnly": true,
"items": {
"type": "string",
"example": [
"new theme",
"document",
"video",
"cover page"
]
}
},
"status": {
"type": "string",
"description": "This field indicates the progress of AI analysis",
"readOnly": true,
"enum": [
"complete",
"failed",
"none",
"pending"
]
}
}
},
"isManaged": {
"type": "boolean",
"readOnly": true,
"description": "This field indicates whether the asset is managed or not. An asset is considered managed only if its asset path starts with \"dxdam\"."
},
"altText": {
"type": "string",
"description": "A text description of the asset, used when the asset itself is not available or not displayed.",
"example": "This is an image of the Acoustic logo."
},
"caption": {
"type": "string",
"description": "A caption of the asset image.",
"example": "Acoustic"
},
"linkedDocId": {
"type": "string",
"readOnly": true,
"description": "Provided on drafts of existing items. This is the ID of the primary item.",
"example": "b289c02e-2c61-4643-aba6-e6b4e94c76e3"
},
"categories": {
"type": "array",
"items": {
"type": "string",
"description": "The taxonomy categories that the user has associated the asset to.",
"example": "banner"
}
},
"isSystem": {
"type": "boolean",
"description": "Indicates whether this item is a 'system item' or not. 'System item' means that this is an item managed internally by Acoustic.",
"default": false
},
"libraryId": {
"type": "string",
"description": "If this property is set it points to library id that the item is assigned to."
}
},
"required": [
"resource"
]
}
}
}
},
"304": {
"description": "The Etag provided in the If-None-Match header corresponds to the latest version."
},
"400": {
"description": "The path provided was not valid.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "an error response.",
"properties": {
"requestId": {
"type": "string",
"description": "The current request ID",
"example": "d64dc285-0b62-aaa3-841f-de3588b64d34"
},
"service": {
"type": "string",
"description": "The name of the service that produced the error",
"example": "authoring-resource"
},
"requestMethod": {
"type": "string",
"description": "The Http method type of the current request",
"example": "GET"
},
"requestUri": {
"type": "string",
"description": "The request uri",
"example": "/authoring/v1/assets"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"description": "an individual error, info or warning message.",
"properties": {
"code": {
"type": "integer",
"description": "The message code"
},
"key": {
"type": "string",
"description": "The message key",
"example": "error.asset.1"
},
"message": {
"type": "string",
"description": "The error message",
"example": "The id requested does not exist."
},
"description": {
"type": "string",
"description": "Optional detailed error message",
"example": "Please check the ID you provided is correct before retrying the request."
},
"category": {
"type": "string",
"description": "The message category whereby only user messages are designed to be shown to an end user",
"enum": [
"API",
"USER"
]
},
"level": {
"type": "string",
"description": "Indicates the message level",
"enum": [
"INFO",
"WARNING",
"ERROR"
]
},
"parameters": {
"type": "object",
"description": "The message parameters of this message."
},
"locale": {
"type": "string",
"description": "The current locale used to produce the error message.",
"example": "en"
}
},
"required": [
"code",
"key",
"message",
"description",
"category",
"level",
"parameters",
"locale"
]
}
}
},
"required": [
"requestId",
"service",
"requestMethod",
"requestUri",
"errors"
]
}
}
}
},
"404": {
"description": "The asset with the provided path was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "an error response.",
"properties": {
"requestId": {
"type": "string",
"description": "The current request ID",
"example": "d64dc285-0b62-aaa3-841f-de3588b64d34"
},
"service": {
"type": "string",
"description": "The name of the service that produced the error",
"example": "authoring-resource"
},
"requestMethod": {
"type": "string",
"description": "The Http method type of the current request",
"example": "GET"
},
"requestUri": {
"type": "string",
"description": "The request uri",
"example": "/authoring/v1/assets"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"description": "an individual error, info or warning message.",
"properties": {
"code": {
"type": "integer",
"description": "The message code"
},
"key": {
"type": "string",
"description": "The message key",
"example": "error.asset.1"
},
"message": {
"type": "string",
"description": "The error message",
"example": "The id requested does not exist."
},
"description": {
"type": "string",
"description": "Optional detailed error message",
"example": "Please check the ID you provided is correct before retrying the request."
},
"category": {
"type": "string",
"description": "The message category whereby only user messages are designed to be shown to an end user",
"enum": [
"API",
"USER"
]
},
"level": {
"type": "string",
"description": "Indicates the message level",
"enum": [
"INFO",
"WARNING",
"ERROR"
]
},
"parameters": {
"type": "object",
"description": "The message parameters of this message."
},
"locale": {
"type": "string",
"description": "The current locale used to produce the error message.",
"example": "en"
}
},
"required": [
"code",
"key",
"message",
"description",
"category",
"level",
"parameters",
"locale"
]
}
}
},
"required": [
"requestId",
"service",
"requestMethod",
"requestUri",
"errors"
]
}
}
}
},
"412": {
"description": "The Etag provided in the If-None-Match header does not correspond to the latest version.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "an error response.",
"properties": {
"requestId": {
"type": "string",
"description": "The current request ID",
"example": "d64dc285-0b62-aaa3-841f-de3588b64d34"
},
"service": {
"type": "string",
"description": "The name of the service that produced the error",
"example": "authoring-resource"
},
"requestMethod": {
"type": "string",
"description": "The Http method type of the current request",
"example": "GET"
},
"requestUri": {
"type": "string",
"description": "The request uri",
"example": "/authoring/v1/assets"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"description": "an individual error, info or warning message.",
"properties": {
"code": {
"type": "integer",
"description": "The message code"
},
"key": {
"type": "string",
"description": "The message key",
"example": "error.asset.1"
},
"message": {
"type": "string",
"description": "The error message",
"example": "The id requested does not exist."
},
"description": {
"type": "string",
"description": "Optional detailed error message",
"example": "Please check the ID you provided is correct before retrying the request."
},
"category": {
"type": "string",
"description": "The message category whereby only user messages are designed to be shown to an end user",
"enum": [
"API",
"USER"
]
},
"level": {
"type": "string",
"description": "Indicates the message level",
"enum": [
"INFO",
"WARNING",
"ERROR"
]
},
"parameters": {
"type": "object",
"description": "The message parameters of this message."
},
"locale": {
"type": "string",
"description": "The current locale used to produce the error message.",
"example": "en"
}
},
"required": [
"code",
"key",
"message",
"description",
"category",
"level",
"parameters",
"locale"
]
}
}
},
"required": [
"requestId",
"service",
"requestMethod",
"requestUri",
"errors"
]
}
}
}
},
"429": {
"description": "Too Many Requests, the server has reached a limit, the request must be sent again at a later time.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "Connection failed to data store.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "an error response.",
"properties": {
"requestId": {
"type": "string",
"description": "The current request ID",
"example": "d64dc285-0b62-aaa3-841f-de3588b64d34"
},
"service": {
"type": "string",
"description": "The name of the service that produced the error",
"example": "authoring-resource"
},
"requestMethod": {
"type": "string",
"description": "The Http method type of the current request",
"example": "GET"
},
"requestUri": {
"type": "string",
"description": "The request uri",
"example": "/authoring/v1/assets"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"description": "an individual error, info or warning message.",
"properties": {
"code": {
"type": "integer",
"description": "The message code"
},
"key": {
"type": "string",
"description": "The message key",
"example": "error.asset.1"
},
"message": {
"type": "string",
"description": "The error message",
"example": "The id requested does not exist."
},
"description": {
"type": "string",
"description": "Optional detailed error message",
"example": "Please check the ID you provided is correct before retrying the request."
},
"category": {
"type": "string",
"description": "The message category whereby only user messages are designed to be shown to an end user",
"enum": [
"API",
"USER"
]
},
"level": {
"type": "string",
"description": "Indicates the message level",
"enum": [
"INFO",
"WARNING",
"ERROR"
]
},
"parameters": {
"type": "object",
"description": "The message parameters of this message."
},
"locale": {
"type": "string",
"description": "The current locale used to produce the error message.",
"example": "en"
}
},
"required": [
"code",
"key",
"message",
"description",
"category",
"level",
"parameters",
"locale"
]
}
}
},
"required": [
"requestId",
"service",
"requestMethod",
"requestUri",
"errors"
]
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "an error response.",
"properties": {
"requestId": {
"type": "string",
"description": "The current request ID",
"example": "d64dc285-0b62-aaa3-841f-de3588b64d34"
},
"service": {
"type": "string",
"description": "The name of the service that produced the error",
"example": "authoring-resource"
},
"requestMethod": {
"type": "string",
"description": "The Http method type of the current request",
"example": "GET"
},
"requestUri": {
"type": "string",
"description": "The request uri",
"example": "/authoring/v1/assets"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"description": "an individual error, info or warning message.",
"properties": {
"code": {
"type": "integer",
"description": "The message code"
},
"key": {
"type": "string",
"description": "The message key",
"example": "error.asset.1"
},
"message": {
"type": "string",
"description": "The error message",
"example": "The id requested does not exist."
},
"description": {
"type": "string",
"description": "Optional detailed error message",
"example": "Please check the ID you provided is correct before retrying the request."
},
"category": {
"type": "string",
"description": "The message category whereby only user messages are designed to be shown to an end user",
"enum": [
"API",
"USER"
]
},
"level": {
"type": "string",
"description": "Indicates the message level",
"enum": [
"INFO",
"WARNING",
"ERROR"
]
},
"parameters": {
"type": "object",
"description": "The message parameters of this message."
},
"locale": {
"type": "string",
"description": "The current locale used to produce the error message.",
"example": "en"
}
},
"required": [
"code",
"key",
"message",
"description",
"category",
"level",
"parameters",
"locale"
]
}
}
},
"required": [
"requestId",
"service",
"requestMethod",
"requestUri",
"errors"
]
}
}
}
}
},
"x-ibm-dx-security-user-roles": [
"admin",
"manager",
"editor",
"viewer"
]
}
}
},
"components": {
"schemas": {
"ErrorResponse": {
"description": "This JSON record represents an error condition.",
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"description": "This JSON record represents an individual error or warning contained in an error message.",
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "An error code"
},
"message": {
"type": "string",
"description": "A message describing what went wrong."
},
"description": {
"type": "string",
"description": "Further explanation of the error condition and potential next steps to resolve the problem."
},
"more_info": {
"type": "string",
"description": "A URL pointing to a web site that provides more information on the given error condition."
},
"level": {
"type": "string",
"enum": [
"ERROR",
"WARNING"
],
"description": "The severity level of the message. Default is error."
},
"parameters": {
"type": "object",
"description": "Additional properties reflecting the dynamic parts of the error condition."
},
"cause": {
"type": "object",
"description": "This property can be used to transport causing error message records produced by a down stream service calls."
},
"locale": {
"type": "string",
"description": "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."
}
},
"required": [
"code",
"message"
]
}
},
"requestId": {
"type": "string",
"description": "The ID of the failing request."
},
"service": {
"type": "string",
"description": "The name of the service serving the error message."
}
},
"required": [
"errors",
"requestId"
]
}
}
},
"x-readme": {
"explorer-enabled": true,
"proxy-enabled": true
}
}
```