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

Response Object

Sample Request:

POST 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:

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

Response Object

Sample Request:

POST 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:

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

Sample Request:

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

Sample Response

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

Sample Request

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

Sample Response

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

Response Object

Sample Request:

POST 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:

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

Response Object

Sample Request:

POST 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:

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

Response Object

Sample Request:

POST 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:

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

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

Response Object

Sample Request:

POST 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:

{
    "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:

Application specific error codes:

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