Skip to main content

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