Support API

Introduction

Overview

Cisco Automated Software Distribution service provides software information and download URLs to assist you in upgrading your device/application to the latest version.

Features

The Cisco Automated Software Distribution API provides the following features:

  • Delivery of composite RESTful API

  • Returns software information based on unique device identifier and software attributes

  • Returns download URLs based on unique device identifier and software attributes

API Reference

Notes:

  • The Swagger YAML for the Cisco Automated Software Distribution API v4.0 is available for download from the Cisco API Console.

  • For information on error codes returned by these methods, see Error Codes.

Software Release by PID and Release

Returns information on the software release for the device specified by its PID and Release.

URI

POST https://apix.cisco.com/software/v4.0/metadata/pidrelease

Request Object

Parameter Required Type Length Description
PID Yes string 256 PID for which to return software release information.
Only one PID is allowed at once.
For example : ACS-1800-RM-19=VID:V01
currentReleaseVersion Yes string 256 Current release on which to filter a release.
One value is permitted at once.
For example: 6.2(1)E3
OutputReleaseVersion Yes string 256 Output Releasee version on which to filter a release.
  • Latest
  • Above
  • (A specific release, ex: 1.2(a) )
pageIndex No int 5 Index number of the page to return. A maximum of 25 records per page are returned.
perpage No int 2 Number of records per page max (25 records)
Number of records per page max (25 records)

Response Object

Parameter Type Length Description
catalogMessage string 256 Message specified in the catalog file for the release.
deferralNotice string 256 URL of the deferral notice attached to the software image.
deletedDate date 21 Deleted date of the image/release in format yyyy-mm-dd
encryptionSoftwareIndicator string 1 Indicates if the image is crypto software.
featureSetDescription string 256 Feature set of the software.
Note: This field is present for IOS software only.
fieldNoticeUrl string 256 URL of the field notice attached to the release.
imageDescription string 256 Description of the software.
Note: This field is present for non-IOS software only.
isDeleted string 1 Indicates if the image/release is deleted
imageDocName string 100 Name of the document attached to the software image.
imageDocType string 20 Software image document type; for example, Readme.
imageDocUrl string 256 URL of the document attached to the software image.
imageGuid string 40 Globally unquie identifier (GUID) for the software image.
imageName string 256 Name of the software image.
imageSize int 14 Total size (in bytes) of the software image.
isSuggested string 1 Indicates whether the release is a suggested release.
md5 string 32 MD5checksum value of the software image.
mdfConceptName string 256 Name of the device from the Cisco MDF.
mdfId int 20 Numeric ID of the device from the Cisco MDF.
metadataTransId string 20 Unique metadata transaction ID generated for the request (expires in 60 minutes).
minDram string 40 RAM required for the software version to be downloaded onto the appliance.
minFlash string 40 Memory required for downloading the software. The memory is displayed in the unit along with the value.
operatingPlatform string 20 Operating platform of the release; for example, Windows, Linux, etc.
releaseDocName string 100 Name of the document attached to the release.
releaseDocType string 20 Release document type; for example: Release Document
releaseDocUrl string 256 URL of the document attached to the release.
fcsDate Date 21 Release date of the software in the following format: yyyy-mm-dd
lifecycle string 20 Release lifecycle of the software.
message string 256 Release message associated to the release.
releaseVersion string 20 Release version of the software.
isReleated string 1 Indicates if this software image is related to another image.
securityAdvisory string 256 URL of the security advisory attached to the release.
sha512 string 256 SHA-512 checksum value of the software image.
softwareAdvisory string 256 URL of the software advisory attached to the software image.
softwareTypeId int 20 Numeric ID for the software type name.
softwareTypeName string 100 Type of a software for given product; for example: IOS Software
pid string 256 PID of the product for which software release was returned
psirtIndicator string 10 Indicate if PSIRT attached to this image (Y or N)
additionalEntitlement string 100 Indicates if entitlement required to download software (Y or N)

Sample Request:

json
CopyPOST https://apix.cisco.com/software/v4.0/metadata/pidrelease

Content-Type: application/json

{
    "pid":"ASR10012XOC3POS-RF",
    "currentReleaseVersion": "5.4.3",
    "outputReleaseVersion": "latest",
    "pageIndex":"1",
    "perPage":"1"
}

Sample Response:

json
Copy{
    "pagination": {
        "pageIndex": 1,
        "lastIndex": 5,
        "totalRecords": 5,
        "pageRecords": 1
    },
    "selfLink": "https://api-stage.cisco.com/software/v4.0/metadata/pidrelease",
    "title": "Get Metadata by PID and Current / Output Release",
    "metadataTransId": "45264903312820837",
    "metadata": [
        {
            "pid": "ASR10012XOC3POS-RF",
            "products": [
                {
                    "mdfId": "277873116",
                    "mdfConceptName": "1700/2600/3600/3700 Series 1-Port Analog Modem WAN Interface Card",
                    "softwareTypes": [
                        {
                            "softwareTypeId": "283724313",
                            "softwareTypeName": "Analog Firmware Loader",
                            "operatingSystems": [
                                {
                                    "name": "Windows XP",
                                    "releases": [
                                        {
                                            "version": "JuLy_TeSt(1.5E)",
                                            "fcsDate": "2020-07-10",
                                            "message": "",
                                            "lifeCycle": "MD",
                                            "fieldNotice": "https://www.cisco.com/c/en/us/support/interfaces-modules/wan-interface-cards/products-field-notices-list.html",
                                            "securityAdvisory": "",
                                            "docs": [],
                                            "isSuggested": "N",
                                            "catalogMessage": "",
                                            "images": [
                                                {
                                                    "imageGuid": "85EC8B09474A0B89DED0345E9EBDB27181B6F2CF",
                                                    "softwareAdvisory": "",
                                                    "deferralNotice": "",
                                                    "isRelated": "N",
                                                    "name": "testfile1.exe",
                                                    "size": "1048197",
                                                    "imageDescription": "Ypub Parameter test",
                                                    "featureSetDescription": "",
                                                    "minDram": "",
                                                    "minFlash": "",
                                                    "encryptionSoftwareIndicator": "N",
                                                    "md5": "5bd7b0afa53c83a08c2991467e0d93a0",
                                                    "sha512": "f67e19460c48bb5c5af0eaac48320e4283616d2fdf130f898d1f0edc94e9d74370776d3d39a8e948689986fb3ee1f195384f6ae484f3cac8264f89ed45aedaba",
                                                    "docs": [],
                                                    "isDeleted": "N",
                                                    "deletedDate": "",
                                                    "releaseDate": "2020-07-10",
                                                    "exception": [
                                                        {
                                                            "code": "IAC_ERROR",
                                                            "message": "You do not have access to download contract registered software. Go to <a title=\"ART\" href=\"https://edsart.cloudapps.cisco.com/createRequest\" target=\"_blank\">ART</a> to request a new account for Software Download. Request access by navigating the following path: Cisco Service > Connected Experience (CX) > Delivery & Tools Support > Software Download and Special File Publishing Access > Software Download Access"
                                                        }
                                                    ],
                                                    "migrationReleaseVersion": "",
                                                    "migrationTargetRetirementDate": "",
                                                    "migrationReleaseLifeCycle": "",
                                                    "additionalEntitlement": "Y",
                                                    "psirtIndicator": "N"
                                                }
                                            ]
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Software Release by PID and Image

Returns information on the software release for the device specified by its PID and Image Names.

URI

POST https://apix.cisco.com/software/v4.0/metadata/pidimage

Request Object

Parameter Required Type Length Description
PID Yes string 256 PID for which to return software release information.
For example: ACS-1800-RM-19=VID:V01
Only one PID is allowed at once
imageNames Yes string 5 Name of the software images for which to return software release information.
For example: c2960-lanlitek9-mz.150-2.SE5.bin
One value is required; up to 5 values are permitted.
Image names need to be passed in a comma separated array.
pageIndex No int 5 Index number of the page to return. A maximum of 25 records per page are returned.
perpage No int 2 Number of records per page max (25 records).

Response Object

Parameter Type Length Description
catalogMessage string 256 Message specified in the catalog file for the release.
deferralNotice string 256 URL of the deferral notice attached to the software image.
deletedDate date 21 Deleted date of the image/release in format: yyyy-mm-dd
encryptionSoftwareIndicator string 1 Indicates if the image is crypto software.
featureSetDescription string 256 Feature set of the software.
Note: This field is present for IOS software only.
fieldNoticeUrl string 256 URL of the field notice attached to the release.
imageDescription string 256 Description of the software.
Note: This field is present for non-IOS software only.
sDeleted string 1 Indicates if the image/release is deleted
imageDocName string 100 Name of the document attached to the software image.
imageDocType string 20 Software image document type; for example, Readme.
imageDocUrl string 256 URL of the document attached to the software image.
imageGuid string 40 Globally unquie identifier (GUID) for the software image.
imageName string 256 Name of the software image.
imageSize int 14 Total size (in bytes) of the software image.
isSuggested string 1 Indicates whether the release is a suggested release.
md5 string 32 MD5checksum value of the software image.
mdfConceptName string 256 Name of the device from the Cisco MDF.
mdfId int 20 Numeric ID of the device from the Cisco MDF.
metadataTransId string 20 Unique metadata transaction ID generated for the request (expires in 60 minutes).
minDram string 40 RAM required for the software version to be downloaded onto the appliance.
minFlash string 40 Memory required for downloading the software. The memory is displayed in the unit along with the value.
operatingPlatform string 20 Operating platform of the release; for example, Windows, Linux, etc.
releaseDocName string 100 Name of the document attached to the release.
releaseDocType string 20 Release document type; for example: Release Document
releaseDocUrl string 256 URL of the document attached to the release.
fcsDate Date 21 Release date of the software in the following format: yyyy-mm-dd
lifecycle string 20 Release lifecycle of the software.
message string 256 Release message associated to the release.
releaseVersion string 20 Release version of the software.
isRelated string 1 Indicates if this software image is related to another image.
securityAdvisory string 256 URL of the security advisory attached to the release.
sha512 string 256 SHA-512 checksum value of the software image.
softwareAdvisory string 256 URL of the software advisory attached to the software image.
softwareTypeId int 20 Numeric ID for the software type name.
softwareTypeName string 100 Type of a software for given product; for example: IOS Software
pid string 256 PID of the product for which software release was returned
psirtIndicator string 10 Y/N to indicate if PSIRT attached to this image.
additionalEntitlement string 100 Y/N to indicate if entitlement required to download software.

Sample Request:

json
CopyPOST https://apix.cisco.com/software/v4.0/metadata/pidimage

Content-Type: application/json

{
    "pid": "ASR10012XOC3POS-RF",
    "imageNames": [
        "testfile1.exe",
        "testVPN_3.bin"
    ],
    "pageIndex": "1",
    "perPage": "1"
}

Sample Response:

json
Copy{
    "pagination": {
        "pageIndex": 1,
        "lastIndex": 4,
        "totalRecords": 4,
        "pageRecords": 1
    },
    "selfLink": "https://api-stage.cisco.com/software/v4.0/metadata/pidimage",
    "title": "Get Metadata by PID, Image names",
    "metadataTransId": "640518163705325115",
    "invalidImages": [
        "testfile1.exe"
    ],
    "metadata": [
        {
            "pid": "ASR10012XOC3POS-RF",
            "products": [
                {
                    "mdfId": "277873116",
                    "mdfConceptName": "1700/2600/3600/3700 Series 1-Port Analog Modem WAN Interface Card",
                    "softwareTypes": [
                        {
                            "softwareTypeId": "283724313",
                            "softwareTypeName": "Analog Firmware Loader",
                            "operatingSystems": [
                                {
                                    "name": "Windows 2000",
                                    "releases": [
                                        {
                                            "version": "02mar2020",
                                            "fcsDate": "2020-05-04",
                                            "message": "",
                                            "lifeCycle": "",
                                            "fieldNotice": "https://www.cisco.com/c/en/us/support/interfaces-modules/wan-interface-cards/products-field-notices-list.html",
                                            "securityAdvisory": "",
                                            "docs": [],
                                            "isSuggested": "N",
                                            "catalogMessage": "",
                                            "images": [
                                                {
                                                    "imageGuid": "5733CA9E09F64B058DA991CBFB90C5C857C44CF1",
                                                    "softwareAdvisory": "",
                                                    "deferralNotice": "",
                                                    "isRelated": "Y",
                                                    "name": "testVPN_3.bin",
                                                    "size": "11",
                                                    "imageDescription": "test",
                                                    "featureSetDescription": "",
                                                    "minDram": "",
                                                    "minFlash": "",
                                                    "encryptionSoftwareIndicator": "Y",
                                                    "md5": "eb9c74609d23b98c2b59a1b6ea0f2d3d",
                                                    "sha512": "7ed2c7105915575ecbbaa46f993aba1a3636b9accb1815805cf7dd7670cb6bd2aa9a16127fb7e5c87d8f4c474bc08fcbaad60eff6a83f6286b486e214870d15d",
                                                    "docs": [],
                                                    "isDeleted": "N",
                                                    "deletedDate": "",
                                                    "releaseDate": "2020-05-04",
                                                    "exception": [
                                                        {
                                                            "code": "IAC_ERROR",
                                                            "message": "You do not have access to download contract registered software. Go to <a title=\"ART\" href=\"https://edsart.cloudapps.cisco.com/createRequest\" title=\"ART\" target=\"_blank\" >ART</a> to request a new account for Software Download. Request access by navigating the following path: Cisco Service > Connected Experience (CX) > Delivery & Tools Support > Software Download and Special File Publishing Access > Software Download Access"
                                                        }
                                                    ],
                                                    "migrationReleaseVersion": "",
                                                    "migrationTargetRetirementDate": "",
                                                    "migrationReleaseLifeCycle": "",
                                                    "additionalEntitlement": "Y",
                                                    "psirtIndicator": "N"
                                                }
                                            ]
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

GET K9 Agreement

Returns the user's K9 agreement and can also be used for pre-registration of legal form during product setup.

URI

GET https://apix.cisco.com/software/v4.0/compliance/k9

Request Parameters

(None)

Response Object

Parameter Type Length Description
webForm string 256 URL of the web form to accept K9.
k9Content string 256 Form fields and values

Sample Request:

Code Snippet
CopyGET https://apix.cisco.com/software/v4.0/compliance/k9

Sample Response

json
Copy{
    "statusCode": "0",
    "statusMessage": "success",
    "subAppVersion": "9",
    "k9Content": {
        "k9Form": "<HTML></HTML>",
        "businessDivisionLabel": "Business division's function",
        "commercialCivilianLabel": "Commercial/Civilian entity",
        "CommercialCivilianValue": "COMM_OR_CIVIL",
        "govMilitaryLabel": "Government entity, a Military entity or Defense Contractor.",
    
        "govMilitaryText": "If Government entity, a Military entity or Defense Contractor,   Are you in <br>  <br>Austria, Australia, Belgium, Canada, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Japan, Latvia, Lithuania, Luxembourg, Malta, Netherlands, New Zealand, Norway, Poland, Portugal, Slovakia, Slovenia, Spain, Sweden, Switzerland, United Kingdom or the United States.",
    
        "govMilitaryValue": "GOV_OR_MIL",
        "govMilitaryYesLabel": "Yes",
        "govMilitaryYesValue": "GOV_OR_MIL_COUNTRIES_YES",
        "govMilitaryNoLabel": "No",
        "govMilitaryNoValue": "GOV_OR_MIL_COUNTRIES_NO",
        "confirmantionLabel": "Confirmation",
        "confirmationValue": "CONFIRM_CHECKED",
        "confirmationText": "By checking this field, I hereby certify that I, as a duly authorized representative of the organization, understand and agree to abide by the conditions set forth above regarding the usage of Cisco Systems, Inc. hardware and/or software.",
        "acceptLabel": "Accept",
        "acceptValue": "Accepted",
        "declineLabel": "Decline",
        "declineValue": "Declined"
    },
    "userDetails": {
        "userId": "emily-culp",
        "firstname": "Emily",
        "fullname": "Emily Stewart",
        "lastname": "Stewart",
        "userEmail": "emily.stewart@123.com"
    },
    "webForm": "https://software.cisco.com/download/k9"
}

GET EULA Agreement

Returns the user's EULA agreement and can also be used for pre-registration of legal form during product setup.

URI

GET https://apix.cisco.com/software/v4.0/compliance/eula

Request Parameters |

(None)

Response Object

Parameter Type Length Description
webForm string 256 URL of the web form to accept EULA.
eulaContent string 256 EULA content that needs to be displayed
subAppVersion string NA Version of EULA

Sample Request

Code Snippet
CopyGET https://apix.cisco.com/software/v4.0/compliance/eula

Sample Response

json
Copy{
    "statusCode": "0",
    "statusMessage": "success",
    "subAppVersion": "19",
    "eulaContent": {
        "appId": "SWC_MAIN",
        "label": "Cisco End User License Agreement",
        "content": "In order to download software, Please confirm that you have read \nand agree to be bound by the terms of the &nbsp;\n<a href=\"https://www.cisco.com/c/en/us/about/legal/cloud-and-software/end_user_license_agreement.html\" target=\"_blank\">Cisco End User License Agreement</a> and any\n<a href=\"http://www.cisco.com/c/en/us/about/legal/cloud-and-software/software-terms.html\" target=\"_blank\">Supplemental Terms,</a> if applicable.\n",
        "acceptButtonLabel": "Accept License Agreement",
        "acceptButtonValue": "Accepted",
        "declineButtonLabel": "Decline",
        "declineButtonValue": "Declined"
    },
    "webForm": "https://software.cisco.com/download/eula"
}

POST K9 Agreement

Updates the user's K9 agreement for the specified download session ID and software attributes.

URI

POST https://apix.cisco.com/software/v4.0/compliance/k9

Request Object

Parameter Required Type Length Description
busfunction Yes string 20 Business division function; only this value is permitted: COMM_OR_CIVIL.
confirm Yes string 5 User confirmation; only this value is permitted: Confirm_Checked.
declineComments No int 10 mandatory when status is Declined
govMilCountries No string 20 Government entity, military entity, or defense contractor; only this value is permitted: GOV_OR_MIL
fileNames No string 256 Name of the software image.
For example: c2960c405-universalk9-mz.150-2.SE5.bin
Only one value is permitted.
status Yes string 20 User response to the K9 agreement; one of the following values:
  • Accepted
  • Declined

Response Object

Parameter Type Length Description
statusMessage string 40 Status message.
statusCode string 20 Status of the request; one of the following values:
  • 0 (If all request values are correct.)
  • INVALID_INPUT (If any request value is invalid)

Sample Request:

json
CopyPOST https://apix.cisco.com/software/v4.0/compliance/k9

Content-Type: application/json

{
    "status": "Accepted",
    "declineComments": "(mandatory when status is Declined)",
    "fileNames": "anyconnect-linux64-4.8.03052-predeploy-k9.tar.gz",
    "confirm": "CONFIRM_CHECKED",
    "busFunction": "COMM_OR_CIVIL",
    "govMilCountries": "GOV_OR_MIL_COUNTRIES_NO",
}

Sample Response:

json
Copy{
    "statusCode": "0",
    "statusMessage": "success",
}

POST EULA Agreement

Updates the user's EULA agreement for the specified download session ID and software attributes

URI

POST https://apix.cisco.com/software/v4.0/compliance/eula

Request Object

Parameter Required Type Length Description
declineComments Yes, if status is declined int 10 ID for the download session; this value is obtained from the Get Software Download URLs methods. For example: 3654559.Only one value is permitted
status Yes string 20 User’s response to the K9 agreement; one of the following values:
  • Accepted
  • Declined
fileNames No string 20 Filenames in CSV format

Response Object

Parameter Type Length Description
statusMessage string 40 Status message
statusCode int 5 Status number.

Sample Request:

json
CopyPOST https://apix.cisco.com/software/v4.0/compliance/eula

Content-Type: application/json

{
    "status": "Accepted",
    "declineComments": "(mandatory when status is Declined)",
    "fileNames": "anyconnect.tar.gz"
}

Sample Response:

json
Copy{
    "statusCode": "0",
    "statusMessage": "success",
}

Download Variant

Providing download URLs for the software based on PID and Image GUIDs. Download URLs, and associated provided tokens, are to download the software from servers for provided GUIDs. There can be maximum of 5 Image GUIDs and minimum of 1 GUID provided by request object.

URI

POST https://apix.cisco.com/software/v4.0/download/pidimage

Request Object

Parameter Required Type Length Description
mdfId Yes string 256 MDF ID for which to return software release information.
For example: 280812254
Only one mdfId is allowed at once
pid Yes string 256 PID of the device
imageGuids Yes string 40 Globally unique identifier (GUID) for the software.
Maximum 5 Image GUIDs allowed; Minimum 1 Image GUID required
metadataTransId Yes String 40 Unique metadata transaction ID generated for the request (expiry in 60 minutes). This trans id generated by Release / Image variant

Response Object

Parameter Type Length Description
url string 256 Sessionalized download URL of the image (expires in 60 minutes).
The URL can be a cloud based URL (if the image is present in cloud) or default download URL.
Use the token field to determine if the image is in cloud (field will have a value) or not (will be empty for default download URL).
In order to download, client must append &access_token={access_token} to this URL (access_token is the Authorization token obtained to call this api.)
For cloud download, see Downloading Images From the Cloud
token string 40 Token for cloud download URL
sessionId string 256 Unique identifier for the particular download request.
k9Content string 256 Form fields and values
webForm string 256 URL of the web form to accept K9 / EULA.
eulaContent string 256 EULA content that needs to be displayed
subAppVersion string NA Version of EULA
exception.code string 256 Exception code for the error
exception.message string 256 Exception message for the error
imageGuid string 40 Globally unquie identifier (GUID) for the software image.
imageName string 256 Name of the software image.

Sample Request:

json
CopyPOST https://apix.cisco.com/software/v4.0/download/pidimage

Content-Type: application/json

{
    "pid": "ACS-1800-RM-19=",
    "mdfId": "286305578",
    "metadataTransId": "617462102359722937",
    "imageGuids": [
        "25856C5890AE73F8EDBEEDA441EC901F8FC8362E"
    ]
}

Sample Response:

json
Copy{
    "pagination": {
        "pageIndex": 1,
        "lastIndex": 1,
        "totalRecords": 1,
        "pageRecords": 1
    },
    "selfLink": "https://api-stage.cisco.com/software/v4.0/download/pidimage",
    "title": "GET Software Download URLs by PID",
    "sessionId": "205785277984030082",
    "acceptanceForm": {},
    "downloads": [
        {
            "url": "https://dl-stage.cisco.com/pcgi-bin/swdld/download.cgi?dwnld_code=xhMnkw8Z-oFbMAJlFOUxULJ8wssGI_2Jn4qAlNCtHlmOHj9kXYFDRO7i5JmYIBhXNlpbxhKQ-tlpqAdsWFLlDOPvJGQKWw16QJKwQWL2rPnBSTFyvnco2hAmVGyAWPFYySfz7PeIhzGhsXtK5J5Gtd0Hwp5RfWBbelKl1-tY6t7LR87ih45dsIOq9aN78GtJ7McTOWrzGZU",
            "token": "",
            "imageGuid": "25856C5890AE73F8EDBEEDA441EC901F8FC8362E",
            "imageName": "n9000-epld.7.0.3.I7.9.img",
            "exception": []
        }
    ]
}

Downloading Images From the cloud

With the url and token values from the response (see sample above), applications can securely download software images from the Cisco cloud.

Note: one or more HTTP 302 Found redirects may be returned until the final URL is resolved.

HTTP Parameters

  • Method: POST
  • Content-Type: application/x-www-form-urlencoded
  • Body (form url encoded): X-Authentication-Control=token-value

Sample CURL Command

bash
Copycurl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded' -i 'https://download-ssc.cisco.com/files/swc/sec/4_SDSP27/1/anyconnect-linux64-4.10predeploy-k9.tar.gz?ip=10.42.4.150&dtrTag=4_SDSP_1aa613a&userid=someone&ak-org=2w_ue&SEC=Y&tenant-id=asd&client=NA&__gda__=16264d82483745c7cb5c3e01f447cc1f' --data 'X-Authentication-Control=4-asdfasdfasdf%252Fpo7iQchQEy2ZDcaAOc3RIlTfE'

Sample Java Client

A sample Java 8+ app for downloading image files is available here: Sample Java Client

Software Status Variant

Returns software status for given software image names.

URI

POST https://apix.cisco.com/software/v4.0/metadata/images

Request Object

Parameter Required Type Length Description
imageNames Yes string 40 Globally unique identifier (GUID) for the software
Maximum 5 Image GUIDs allowed, Minimum 1 Image GUID required

Response Object

Parameter Type Length Description
encryptionSoftwareIndicator string 1 Indicates if the image is crypto software.
exception.code string 256 Exception code for the error
exception.message string 256 Exception message for the error
imageDescription string 256 Description of the software.
Note: This field is present for non-IOS software only.
isDeleted string 1 Indicates if the image/release is deleted
imageDocs.Name string 100 Name of the document attached to the software image.
imageDocs.Type string 20 Software image document type; for example, Readme.
imageDocs.Url string 256 URL of the document attached to the software image.
imageName string 256 Name of the software image.
releaseFcsDate Date 21 Release date of the software in the following format: yyyy-mm-dd
imageSize int 14 Total size (in bytes) of the software image.
Md5 string 32 MD5checksum value of the software image.
minDram string 40 RAM required for the software version to be downloaded onto the appliance.
minFlash string 40 Memory required for downloading the software. The memory is displayed in the unit along with the value.
sha512 string 256 SHA-512 checksum value of the software image.
softwareTypeId int 20 Numeric ID for the software type name.
softwareTypeName string 100 Type of a software for given product; for example: IOS Software
deletedDate date 21 Deleted date of the image/release in format: yyyy-mm-dd
featureSetDescription string 256 Feature set of the software.
Note: This field is present for IOS software only.
imageDescription string 256 Description of the software.
Note: This field is present for Non-IOS software only

Sample Request:

json
CopyPOST https://apix.cisco.com/software/v4.0/metadata/images

Content-Type: application/json

{
    "imageNames": [
        "me360x-universalk9-tar.153-3.S4.tar",
        "c1700-y-mz.124-13a.bin",
        "m9000-epld-3.2.1.img"
    ]
}

Sample Response:

json
Copy{
    "selfLink": "https://api-stage.cisco.com/software/v4.0/metadata/images",
    "title": "GET Software Status by Software Image Names",
    "invalidImages": [],
    "metadata": [
        {
            "imageName": "2506tania3.bin",
            "softwareTypeId": 283724313,
            "softwareTypeName": "Analog Firmware Loader",
            "isDeleted": "N",
            "releaseFcsDate": "2020-01-22",
            "imageDescription": "test",
            "imageSize": 17,
            "md5": "d38bdd94f84ca57ccfd0b7905673a218",
            "sha512": "32ddd5cd43ef29a3a4cd57bf9ae44b6802ea37d76928557190c5c59e3e5c52737f9f51e69d5a2ca2808fe26d2bb9857b34169a8db3d23c473eb70943af44f3c6",
            "encryptionSoftwareIndicator": "N",
            "imageDocs": [
                {
                    "name": "notes label",
                    "url": "https://www-stage.cisco.com/web/software/283724313/148829/notes.txt",
                    "type": "Image Document"
                }
            ],
            "exception": []
        },
        {
            "imageName": "me360x-universalk9-tar.153-3.S4.tar",
            "softwareTypeId": 280805680,
            "softwareTypeName": "IOS Software",
            "isDeleted": "N",
            "releaseFcsDate": "2014-11-18",
            "featureSetDescription": "UNIVERSAL TAR",
            "minDram": "1024",
            "minFlash": "64",
            "imageSize": 28672000,
            "md5": "69ef77cf1797decbf83a049c30fca4ad",
            "sha512": "6e0cf0653286b7a8a34da545a7ac2c39e60fa37ee5d834df8ce69d45eefdf5294b202fff706274648caeddc958cd27c1bd851eafe56ca491b8f75a15dcd143fa",
            "encryptionSoftwareIndicator": "Y",
            "exception": []
        },
        {
            "imageName": "m9000-epld-3.2.1.img",
            "softwareTypeId": 282253564,
            "softwareTypeName": "NX-OS EPLD Updates",
            "isDeleted": "Y",
            "deletedDate": "2010-07-28",
            "releaseFcsDate": "2007-09-17",
            "imageDescription": "EPLD image for Cisco MDS 9000 Family",
            "imageSize": 3211204,
            "md5": "0567135ccacd177518ecef9e09b4a1ca",
            "encryptionSoftwareIndicator": "N",
            "exception": []
        }
    ]
}

Error Codes

This table describes the error codes returned by the Cisco Automated Software Distribution API

Generic HTTP Status codes:

Status Code Message Description
400 Bad Request Request does not conform to HTTP protocol.
403 Not Authorized Token is invalid.
403 Forbidden You do not have permission to access the requested method or object.
403 Not Authorized The API key associated with your request was not recognized, or the signature was incorrect.
403 Account Inactive The API key you are using to access the Mashery API has not been approved or has been disabled.
403 Account Over Queries Per Second Limit The API key you are using has attempted to access the API too many times in one second.
403 Account Over Rate Limit The API key you are using has attempted to access the API too many times in the rate limiting period.
403 Rate Limit Exceeded The service you have requested is over capacity.
403 Unknown Referrer Unknown referrer.
403 Service requires SSL The service requires SSL.
404 API_UNAVAILABLE Service is not configured in JVM.
414 Request URI Too Long The request URI is too long.
415 INVALID_MEDIATYPE Unsupported media type input by the user.
500 API_UNAVAILABLE Database is down or currently unavailable.
500 UNKNOWN_FAILURE Generic error.
500 SYSTEM_ERROR Error while request data transformation to JSON.
500 SYSTEM_ERROR SQL exception while invoking backend procedure.
500 SYSTEM_ERROR Error while writing the data to HTTP response.
500 Internal Server Error An internal server error has occurred (usually from the API).
502 Bad Gateway Bad response from the server was received on the backend.
502 Proxy Error An error from the server was received on the backend
503 API Maintenance/Service Unavailable The service is unavailable due to maintenance.
504 Gateway Timeout The backend service timed out.
596 Service Not Found The service requested does not exist or is unavailable.
Note: Most likey spaces were found in the input parameters. Please check the input values.

Application specific error codes:

HTTP Status Code Token Description
400 UDI_INVALID udi provided in the request is invalid. Please invoke the service with the valid udi.
400 PID_INVALID pid provided in the request is invalid. Please invoke the service with the valid pid.
400 MDFID_INVALID mdfId provided in the request is invalid. Please invoke the service with the valid mdfId.
400 IMG_NM_INVALID imageName provided is invalid. Please provide the valid imageName.
400 SWTID_INVALID softwareTypeId provided is invalid. Please provide a valid softwareTypeId.
400 OP_INVALID operating_platform provided is invalid. Please provide a valid operating_platform.
400 INVALID_INPUT Invalid input or No data found for the input provided.
400 INVALID_MTRANSID Invalid metadata_trans_id.
400 INVALID_DWLDSID Invalid download_session_id.
400 INVALID_DRETRYID Invalid download_retry_id.
400 NO_DATA_FOUND_FOR_PID No Data Found for the PID.
500 SER_UNEXPECT_FAIL Service has encountered an unexpected failure.Please contact the support with the data requested.
400 IMAGE_GUID_INVALID The image_guid provided in the request is invalid. Please provide a valid image_guid.
401 SW_NO_LONGER_AVL Software for this product is no longer available.
400 SWT_NOT_PUBLISHED software_type_id provided is not published to Cisco.com. Please provide a valid software_type_id.
401 PROD_REG_NA The product needs to be registered and approved to call the Service. Please contact the support team swc-it-support@cisco.com to get the product associated with the service.
401 PROD_REG_AV Your client id does not have access to call the service requested. Please register a new client id to call the service. Please contact the support team swc-it-support@cisco.com in case of additional questions.
401 DNAC_REG_REQ App needs to be registered to call the Service. Please contact the support team swc-it-support@cisco.com to get the app associated with the service.
400 UDI_MISSING udi is missing in the request. Please provide the udi of the requested device.
400 PID_MISSING pid is missing in the request. Please provide a valid pid in the request.
400 MDFID_MISSING mdfId is missing in the request. Please provide a valid mdfId in the request.
400 SWTID_MISSING softwareTypeId not provided. Please provide a valid softwareTypeId.
400 CUR_REL_MISSING currentReleaseVersion is missing in the request. Please provide a valid releaseVersion in the request.
400 REL_MISSING release is missing in the request. Please provide a valid release in the request.
400 OUTPUT_REL_INVALID output_release value provided in the request is invalid. Please invoke the service with the valid output_release.
400 OUT_REL_MISSING output_release value provided in the request is invalid. Please invoke the service with the valid output_release.
400 IMG_NM_MISSING imageNames is missing in the request. Please provide atleast one valid imageNames.
400 MTRANSID_MISSING metadata_trans_id is missing in the request. Please provide a valid metadata_trans_id in the request.
400 IMAGE_LIMIT_EXCEEDED The number of image names entered in the request has exceeded the limit.
400 MDFID_LIMIT_EXCEEDED The number of MDF Ids entered in the request has exceeded the limit
400 PID_LIMIT_EXCEEDED The number of PIDs entered in the request has exceeded the limit
400 Maximum_pid_names 5
400 MTRANSID_EXPIRED metadata_trans_id had been previously granted that has expired due to time limit on its validity. Please invoke the metadata service and initiate the download.
404 NO_DATA_FOUND No Data Found.
400 IMAGE_GUID_MISSING image_guid is missing in the request. Please provide a valid image_guid in the request.
200 IMG_CONTRACT_REQD This image is contract registered. A valid Cisco service contract is required to download software. The image information is provided by this service but you would not be able to get the Image Download URL from the download service .You can add the service contracts to your profile using the Profile Manager, or have your service access administrator do this for you.
200 IMG_K9 This image is cryptographic. The image information is provided by this service but you would not be able to get the Image Download URL from the download service your attempt to download the strong encryption software has not been approved or has been temporarily disabled. This is due to one of the following conditions: You stated that you are a Government entity You did not agree to the conditions listed in the Cisco Systems, Inc. Encryption Software Registration Form. You stated you are a Military entity or Defense Contractor and therefore need to complete the following: You stated you are from or in an embargo/restricted country. To discuss why you believe that you should have access to strong crypto software, email tradeopscpr@cisco.com.
200 CONTRACT_NOT_AUTH Cisco service contract information indicates you are not authorized to download software for the following product(s):
200 SW_ADV_IMAGE SA associated with Image
200 DEF_ADV_IMAGE Deferral Advisory associated with Image
200 CONTRACT_LOGIN To Download this software, you must Log In and have a valid service contract associated to your Cisco.com profile. The image information is provided by this service but you would not be able to get the Image Download URL from the download service.If you do not have a service contract you can get one through: Your Cisco Account Team if you have a direct purchase agreement with Cisco Or your Cisco Partner or Reseller. Once you have the service contract you must associate your service contract to your Cisco.com user ID with Profile Manager.
200 CONTRACT_ACCESS You do not have access to download contract registered software. Go to OnRamp to request a new account for Software Download. Request access by navigating the following path: New Account Request > Request For Myself > Cisco Service > Software Download and Special File Publishing Access-> Software Download Access
200 CONTRACT_IMG_REQ A Cisco service contract is required to download this software. The image information is provided by this service but you would not be able to get the Image Download URL from the download service. Your Cisco Account Team if you have a direct purchase agreement with Cisco Your Cisco Partner or Reseller You can add the service contracts to your profile using the Profile Manager have your service access administrator do this for you.
200 CONTRACT_IMG_DWLD A valid Cisco service contract is required to download software.
You can add the service contracts to your profile using the Profile Manager, or have your service access administrator do this for you.
200 DWLD_WARN You are receiving this warning message because our records indicates that you may not be authorized to download for the following product(s)
200 DWLD_WARN1 If you feel this message is in error, please: Associate the relevant service contract to your Cisco user ID, using the Cisco Profile Manager, or consult your service contract administrator. Contact your Cisco representative, Partner or Reseller to ensure product(s) listed above are covered on a service contract or subscription that is associated to your Cisco.com user ID. The Partner Locator link may assist in locating your nearest partner. Email technical support mailto:ent-dl@cisco.com for 24x7 assistance. To expedite your request, please include the following information: User ID (Cisco.com ID used to download software) Contact Name Company Name Contract Number Product ID Desired Software Release or File Name Please include the above message in your email.
200 DWLD_WARN2 Please follow one of the options below to ensure that you are fully covered for service in the future and that your Cisco.com profile is accurate and up-to-date: Contact your Cisco representative, partner or reseller to ensure the products listed above are covered on a service contract that is associated with your Cisco.com profile. The Partner Locator may assist in locating the nearest partner. You can add the service contracts for these products to your profile using the Cisco Profile Manager, or have your service access administrator do this for you. Your prompt attention to take action per this notice is appreciated in order to avoid unnecessary interruptions or delays in the process of downloading software.
200 CONTRACT_REQ_DWLD A valid Cisco service contract is required to download software.
200 IP_CHECK_FAIL We are sorry, but analysis of your your internet protocol (IP) address does not permit us to complete this transaction because it is originating from a territory that is not authorized to receive Cisco products without a government issued license. If you believe this is an error please email tradeopscpr@cisco.com for assistance and include the error code and transaction number listed below. If you are in a non-authorized territory, and need help with export licenses, please contact tradeopscpr@cisco.com. (Non-authorized territories are Cuba, Iran, Iraq, Libya, North Korea, Syria, and Sudan.).
200 K9_REJECTED Your attempt to download software has not been approved or has been temporarily disabled. This is due to one of the following conditions:You stated that you are a Government entity. You did not agree to the conditions listed in the Cisco Systems, Inc. Encryption Software Registration Form. You stated you are a Military entity or Defense Contractor. You stated you are from or in an embargo/restricted country. We are reviewing the information that you provided. Please try downloading after 4 hours. To discuss why you believe that you should have access to this software, email tradeopscpr@cisco.com.
200 CONTRACT_REJECTED Cisco service contract information indicates you are not authorized to download software for the requested image.
200 C3_USERID_NMAP UserId not mapped in C3.
200 K9_IMG_DWLD This image is cryptographic. The image information is provided by this service but you would not be able to get the Image Download URL from the download service until the software encryption agreement is accepted.
200 LOGIN_IMG_DWLD To Download this software, you must Log In with your Cisco.com user ID. The image information is provided by this service but you would not be able to get the Image Download URL from the download service.
200 LOGIN_CONTRACT_REQ To Download this software, you must Log In and have a valid service contract associated to your Cisco.com profile. If you do not have a service contract you can get one through: Your Cisco Account Team if you have a direct purchase agreement with Cisco or your Cisco Partner or Reseller. Once you have the service contract you must associate your service contract to your Cisco.com user ID with Profile Manager.
200 LOGIN_REQD To Download this software, you must Log In with your Cisco.com user ID.
200 CONTRACT_REQD_DWLD To Download this software, you must have a valid service contract associated to your Cisco.com profile. If you do not have a service contract you can get one through: Your Cisco Account Team if you have a direct purchase agreement with Cisco or your Cisco Partner or Reseller. Once you have the service contract you must associate your service contract to your Cisco.com user ID with Profile Manager.
200 K9_FORM_AR K9 form have not been accepted or rejected to continue download.
200 EULA_FORM_AR Eula form have not been accepted or rejected to continue download.
200 K9_FORM_ACC K9 form have not been accepted to continue download.
200 EULA_FORM_ACC EULA form have not been accepted to continue download.
200 K9_EULA_FORM_AR Both Eula and k9 form have not been accepted or rejected to continue download.
500 SER_UNEXPECT_FAIL Service has encountered an unexpected failure.Please contact the support with the data requested.
401 INVALID_OUTPUT_RELEASE Release Version value cannot be empty. Please provide a release version associated to the MDF and Software type
200 CPR_ADDRESS_EXCEPTION_MSG Thank you for registering with Cisco.com. In order to consume software or services we require your full address. Please follow this link to return to profile manager to complete your profile.

Technical Support

To obtain technical support or report issues regarding the Cisco Support APIs, please contact our Smart Service Bureau available from 8 AM to 5 PM local business hours, except holidays.

US and Canada

E-mail support is available 24 x 7 at: ask-smart-services@cisco.com

Phone: 1-877-330-9746

European Countries

E-mail support is available 24 x 7 at: ask-smart-services@cisco.com

Phone:

  • Austria +08 0 000 6206

  • Belgium +08 0 049 913

  • France +08 0 511 9745

  • Germany +08 0 058 91725

  • Italy +80 0 085 681

  • Netherlands +08 0 002 01276

  • Spain +80 0 600 472

  • Switzerland +08 0 084 0011

  • UK + 08 002 795 112*

China

Email: ask-smart-services@cisco.com

Phone: 400-810-9995

Korea

Email: ask-smart-services@cisco.com

Phone: 080-377-0880, option 5

All Other Countries

E-mail support is available 24 x 7 at: ask-smart-services@cisco.com

Phone: Visit the Cisco Worldwide Contacts web page, and choose the appropriate phone numbers for the Customer Interaction Network (CIN).

Next