Create a Dynamic Analysis of an API with the REST API

You can use the Dynamic Analysis API to create an analysis of a REST API. You can also use it to upload an API specification to Veracode and get details about the uploaded file. The API specification must be either OpenAPI or HAR format, or a Postman Collection.

Upload an API specification

You can upload an API specification file in the Veracode Platform or with the REST API. The file must be valid JSON or YAML.

After you upload a specification, Veracode assigns it a unique ID. You specify the ID when you send a request to create or update a Dynamic Analysis scan of an API, or to get detailed information about your uploaded specifications.

To upload an API specification, send the following request:

http --form --auth-type=veracode_hmac POST "https://api.veracode.com/was/configservice/v1/api_specifications?spec_name={spec_name}" file@{API_specification_file.json}

spec_name is optional. You can include it to specify a custom name, such as My Specification. If you do not include it, the request applies the filename of your specification file. You can also upload a file with a tool such as Postman.

In the following request body example, file_name specifies the specification file to upload and spec_name specifies the name to apply to the specification file during the upload.

HTTP/1.1 200 OK
Access-Control-Expose-Headers: X-Internal-User, location
CF-Cache-Status: DYNAMIC
CF-RAY: 7ef81ee30b33351c-SMF
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
Date: Mon, 31 Jul 2023 19:06:49 GMT
Expires: 0
Pragma: no-cache
Server: cloudflare
Set-Cookie: path=/; domain=.veracode.com; HttpOnly; Secure; SameSite=None
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Transfer-Encoding: chunked
X-CONVERSATION-ID: "00000000-0000-0000-0000-000000000004"
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

{
"capabilities": [],
"endpoint_count": 43,
"file_name": "API_specification_file.json",
"modified_by_user": "username",
"modified_date_time": "2023-07-31T19:06:49.132Z[UTC]",
"org": "90999",
"spec_id": "ID_of_My_Spec",
"spec_name": "My_API_Spec.json",
"spec_type": "OPEN_API_V3",
"uploaded_by_user": "username",
"uploaded_date_time": "2023-07-31T19:06:49.071Z[UTC]",
"visibility": {
"setup_type": "SEC_LEADS_ONLY",
"team_identifiers": []
}
}

Get API specification details

You can retrieve detailed information about your uploaded API specification files. You can also search for uploaded files 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 uploaded specification file and spec_name is the name you entered when you uploaded the file.

"_embedded": {
        "api_specs": [
            {
                "org": "72529",
                "spec_id": "ID_of_my_spec",
                "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}"

Create a Dynamic Analysis

To identify vulnerabilities in your APIs, the Dynamic Analysis scans the endpoints in an uploaded OpenAPI or HAR specification or the requests in an uploaded Postman Collection.

Before you begin:

Ensure you have the ID of the API specification you want to use for the scan. If you have not uploaded the specification to Veracode, you can upload it on the API Specification Management tab in the Veracode Platform or with the REST API.

To complete this task:

Enter values for the scan_config_request and schedule properties in your JSON payload. If you are using Internal Scanning Management (ISM), enter values for the internal_scan_configuration property. See the example payloads for an OpenAPI or HAR file or a Postman Collection.

To create the analysis, send the following request:

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

Example: OpenAPI specification payload

The following example payload for an OpenAPI specification defines the following properties:

"action_type": "ADD": add a new scan.
"target_url": use the URL specified for url as the target API server.
"api_scan_setting": scan the endpoints in the API specification with the ID specified for spec_id. To obtain the ID for a specification, see Get API specification details.
"authentications": to access the endpoints, use HTTP header authentication.
"schedule": start scanning immediately and run the scan 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"
   }
}      

Example: Postman Collection payload

The following example payload for a Postman Collection defines the following properties:

"action_type": "ADD": add a new scan.
"target_url": use the URL specified for url as the target API server. For a Postman Collection, the scan requires the custom base URL.
"blacklist_configuration": exclude the first request in the Postman Collection from the scan. The value of request_index is a numeral that indicates where the request appears in the list of requests in the Postman Collection. For example, 0 is the first, or top, request in the list, 1 is the second request, and so on. The list of requests is inside an item property in the Postman Collection. Add a request_index property with the request number value for each request you want to exclude from the scan. These values override the request_index properties specified for ignore_list.
"ignorelist_configuration": send the second request in the Postman Collection, but exclude it from the scan. The value of request_index is a numeral that indicates where the request appears in the list of requests in the Postman Collection. For example, 0 is the first, or top, request in the list, 1 is the second request, and so on. The list of requests is inside an item property in the Postman Collection. Add a request_index property with the request number value for each request you want to ignore during the scan.
"api_scan_setting": scan the endpoints in the Postman Collection with the ID specified for spec_id and send the requests to the API server specified for "custom_base_url". The custom base URL defines the target API server and is required for Postman Collections. To obtain the ID for a specification, see Get API specification details.
"schedule": start scanning on the specified date and time, and run the scan for two days.

{
   "name": "Scan-postman-collection",
   "scans": [
      {
       "action_type": "ADD",
       "request_id": "0",
       "scan_config_request": {
          "target_url": {
             "url": "https://www.example.com"
          },
         "scan_setting": {
            "blacklist_configuration": {
               "blackList": [
                  {
                     "request_index": 0
                  }
               ]
            },
            "ignorelist_configuration": {
               "ignore_list": [
                  {
                     "request_index": 1
                  }
               ]
            },
            "api_scan_setting": {
               "spec_id": "<ID_of_your_Postman_Collection>>",
               "custom_base_url": "https://www.example.com"
            }
         },
         "internal_scan_configuration": {
            "enabled": false,
            "endpoint_id": "",
            "gateway_id": ""
         }
      }
      ],
      "visibility": {
         "setup_type": "SEC_LEADS_ONLY",
         "team_identifiers": []
      },
      "schedule": {
         "start_date": "2024-07-11T13:55:16-04:00",
         "now": false,
         "duration": {
            "length": 2,
            "unit": "DAY"
         },
         "schedule_status": "ACTIVE"
      }
}

Upload an API specification​

Get API specification details​

Create a Dynamic Analysis​

Example: OpenAPI specification payload​

Example: Postman Collection payload​

Did you find this helpful?

Upload an API specification

Get API specification details

Create a Dynamic Analysis

Example: OpenAPI specification payload

Example: Postman Collection payload