Use the REST API to Create a Dynamic Analysis of an API

You can use the Dynamic Analysis API to create an analysis of a REST API. You specify the ID of an API specification that you uploaded on the API Specification Management tab in the Veracode Platform. You cannot upload a specification with the API.

To complete this task:

1. Enter values for the scan_config_request and schedule properties in your JSON payload. If you are using Internal Scanning Management (ISM), also enter values for the internal_scan_configuration property.

2. Send the following request:

   http --auth-type=veracode_hmac POST "https://api.veracode.com/was/configservice/v1/analyses?scan_type=API_SCAN" < input.json

   The following example payload specifies to:

   • Use HTTP header authentication, as specified for the authtype property, to access the endpoints in the API specification.
   • Scan the endpoints in the API specification specified for the spec_id property.
   • Start scanning immediately, as specified for the schedule property, and run for two days.

   {
     "name": "Scan-API-with-Header-Authentication",
     "scans": [
       {
         "action_type": "ADD",
         "request_id": "0",
         "scan_config_request": {
           "target_url": {
             "url": "https://www.example.com"
           },
           "auth_configuration": {
             "authentications": {
               "HEADER": {
                 "authtype": "HEADER",
                 "headers": [
                   {
                     "key": "Authorization",
                     "value": "Token {your_token}",
                     "url": ""
                   }
                 ]
               }
             }
           },
           "api_scan_setting": {
             "spec_id": "{ID_of_your_API_specification}"
           }
         },
         "internal_scan_configuration": {
           "enabled": false,
           "endpoint_id": "",
           "gateway_id": ""
         }
       }
     ],
     "visibility": {
       "setup_type": "SEC_LEADS_ONLY",
       "team_identifiers": []
     },
     "schedule": {
       "start_date": "2023-04-21T09:46:19-04:00",
       "now": true,
       "duration": {
         "length": 2,
         "unit": "DAY"
       },
       "schedule_status": "ACTIVE"
     }
   }

Get API Specification Details

After you upload an API specification in the Veracode Platform, Veracode assigns it a unique ID that you can retrieve with the REST API. For example, you use the ID when sending a request to create or update a Dynamic Analysis scan of an API, and to get detailed information about your uploaded specifications. You can also search for specifications by name.

To get a detailed list of all API specifications for your organization, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/was/configservice/v1/api_specifications"

In the response, spec_id is the ID of the specification and spec_name is the name you entered when you uploaded the specification.

"_embedded": {
        "api_specs": [
            {
                "org": "72529",
                "spec_id": "5b7c8bb009fb37934f34721459903759",
                "spec_name": "My API Specification",
                "file_name": "my_api_spec.yaml",
                "spec_type": "OPEN_API_V2",
                "endpoint_count": 54,
                "servers": [
                    {
                        "url": "https://api.veracode.com/was/configservice/v1"
                    }
                ],
                "uploaded_date_time": "2023-05-19T13:00:46Z[UTC]",
                "uploaded_by_user": "user",
                "modified_date_time": "2023-05-19T13:00:46Z[UTC]",
                "modified_by_user": "user",
                "visibility": {
                    "setup_type": "SEC_LEADS_ONLY",
                    "team_identifiers": []
                },
                "capabilities": [
                    "delete_api_specification",
                    "update_api_specification",
                    "update_team_visibility"
                ]
            },

To retrieve an API specification by spec_id, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/was/configservice/v1/api_specifications/{spec_id}"

To retrieve an API specification by spec_name, send the following request:

http --auth-type=veracode_hmac GET "https://api.veracode.com/was/configservice/v1/api_specifications?spec_name={spec_name}"