HostedScan API (V1)

Download OpenAPI specification:Download

Getting Started

Welcome to the HostedScan API documentation.

The best way to get acquainted with HostedScan is to head over to our website and start running scans. Try it out here!

This documentation covers the API and webhook integrations. Use the API to run scans, get results, and manage risks. Use webhook integrations to receive real-time event notifications in your application.

Support

Any questions? Please email us at hello@hostedscan.com

API Overview

HostedScan offers a comprehensive REST API at https://api.hostedscan.com/v1. The API enables you to create Targets, set up Scans for those targets, along with fetching the resulting Risks and Reports. Webhooks are available to notify your application about important events, like the completion of scans, or the discovery of new risks for specific targets.

To import results from your own Nmap, OpenVAS, or ZAP installations, see the Upload Results From Your Own Scanners section.

Authentication

Authenticate by setting the X-HOSTEDSCAN-API-KEY request header as your API key. You can create an API key by visiting the API & Webhooks section of your account settings.

HTTP Responses

Status Code	Details
200	OK - Successful request.
400	Bad Request - Invalid request parameters or missing required parameters.
401	Unauthorized - Missing or invalid API key.
403	Forbidden - The feature is not enabled for your account, for example CSV reports.
404	Not Found - No resource at the requested path, or the id does not belong to your account.
429	Too Many Requests - Rate limit exceeded. Wait for the number of seconds in the `Retry-After` header before retrying.
500	Internal Server Error - Something went wrong on our server.

Error responses carry a JSON body of the form { "error": "<message>" } where possible (see the ErrorResponse schema). Fields in request bodies that are not documented are ignored.

SDKs and Tools

The API is defined using the OpenAPI (Swagger) standard. Download our OpenAPI file at the top of this page to get started.

There are tools to generate clients in most programming languages from OpenAPI definitions. The easiest way to get started is with the online swagger.io editor, which has many built-in client generators or check out this comprehensive list of client generators.

Many API tools, such as Postman, also support importing OpenAPI definitions.

AI Agents

If you are an AI agent or building with one, load the hostedscan-api skill from our agent skills index before writing integration code — it covers authentication, the full scan workflow, an endpoint catalog, and common pitfalls. A machine-readable index of all documentation is published at https://docs.hostedscan.com/llms.txt, and every guide is available as plain markdown at its URL plus .md. See the AI Agents guide for details.

Testing with Postman

You can import our OpenAPI document into Postman to quickly and easily test our API. Download our OpenAPI file at the top of this page to get started.

When importing into Postman, choose "Postman Collection"
Change the import settings by choosing "View Import Settings" and disable the "Enable optional parameters" setting to make all requests immediately usable.
After importing, click on the "HostedScan API" collection, go to the variables tab, and create a variable "apiKey", setting the value to your API key. Don't forget to hit the "Save" button.

Deprecation Policy

Generally, when a field or webhook event is deprecated, the field or webhook event is still preserved in the API to prevent unnecessary customer rework. As such you may see some additional fields in a response or webhook events that are not documented in these API documents. Our recommendation is to ignore these.

Scans

Run scanners such as OpenVas, Nmap, and ZAP against your Targets. Creating a scan starts the scanner for the given target(s). Fetching a Scan object gives the results from the specific scanner.

Scan lifecycle

New Scans are created in the QUEUED state and will transition to RUNNING while they are in progress and then to SUCCEEDED when finished. To check if a Scan is finished, either periodically GET the Scan or integrate with the HostedScan webhooks and listen for the scan updated event.

Scan output

The discovered vulnerabilities and output files are available once a scan has SUCCEEDED. In the HostedScan API, the vulnerabilities are called Risks and there are management features, such as tracking Risks over time and accepting Risks that are false positives or by design.

Risks (vulnerabilities)

On the Scan object, there is a property risks, which breaks the Risks into 3 categories:

new_open: Risks that were detected for the first time on the Target
still_open: Risks that were detected by a previous Scan of the Target and detected again by the current Scan, including Risks that had closed and are now re-opened
closed: Risks that were detected by a previous Scan of the Target and not detected by the current Scan

To get all of the vulnerabilities found by the Scan, combine new_open and still_open. The Risks are given as an array of ids. Use the Risks api to get the full information for each id: GET https://api.hostedscan.com/v1/risks/{risk_id}

Scanner output files

Use the scan result api to download the raw output files generated by the scanner software.

Reports

Use the reports api to programmatically generate the executive style PDF reports that are created in the HostedScan web application at https://hostedscan.com/reports.

Start a new Scan

Run a new vulnerability scan. Choose the Targets to scan by sending either the target values (e.g. https://example.com or 123.123.123.123), the ID of a Target already created in your HostedScan account, or using the tags feature and the Scan will automatically include all Targets with matching tags.

Each targets value must be a public IPv4 address, a Fully Qualified Domain Name, or a URL with an http:// or https:// scheme. Private or reserved IP addresses, IPv6 addresses, and CIDR ranges are rejected with 400. Values that are not already Targets in your account are created as new Targets.

A request with many targets may be split into several Scans, because each scanner has a maximum number of targets per Scan (1 for OWASP_ZAP and OWASP_ZAP_ACTIVE, 10 for SSLYZE and NUCLEI, 100 for the other scan types). The response contains the first Scan only. Use List Scans to see all of them.

When the request would exceed your plan limits, the Scan is still created and returned with a 200 response but its state is OVER_LIMIT and it does not run. NESSUS requires Tenable Nessus to be enabled on your account and OWASP_ZAP_ACTIVE requires a paid plan; otherwise the request fails with 400.

Authorizations:

ApiKey

Request Body schema: application/json
required

type required	string (RunnableScanType) Enum: "NESSUS" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SSLYZE"
targets	Array of strings [ 1 .. 100 ] items [ items <= 2048 characters ] Targets to scan. e.g. `["example.com", "123.123.123.123"]` Exactly one of tags, targets, or target_ids must be specified.
target_ids	Array of strings [ 1 .. 100 ] items Ids of the targets to scan. Ids that do not belong to your account are ignored. Exactly one of tags, targets, or target_ids must be specified.
tags	Array of strings [ 1 .. 100 ] items Tags to scan. e.g. `["prod", "web-server"]` Targets with at least one matching tag are scanned. Exactly one of tags, targets, or target_ids must be specified.
use_authentication	boolean Whether to replay the recorded login for targets that have one attached (see Authenticated Scanning). Only `OWASP_ZAP` and `OWASP_ZAP_ACTIVE` can use the login session, so it defaults to `true` for those scan types and `true` is rejected with 400 for any other scan type. Set to `false` to run a ZAP scan without logging in.

Responses

Response Schema: application/json

required

object (Scan)

The created Scan object

id

required

string

Scan's ID

type

required

string (ScanType)

Enum: "DEPENDABOT" "DOMAIN_TAKEOVER" "NESSUS" "NESSUS_AGENT" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SNYK" "SSLYZE"

The scanner or integration that produced a Scan or Risk. DEPENDABOT, DOMAIN_TAKEOVER, NESSUS_AGENT, and SNYK come from integrations and cannot be started with the API; see RunnableScanType for the scan types you can run.

state

required

string (State)

Enum: "FAILED" "OVER_LIMIT" "QUEUED" "RUNNING" "STOPPING" "STOPPED" "SUCCEEDED"

State of a Scan. OVER_LIMIT means the scan did not run because the account exceeded its plan limits. FAILED means the scan could not be completed after retries, for example because none of the targets could be resolved; contact us if a scan fails unexpectedly.

progress

required

number

From 0 to 100. Starts at 0 and is 100 once the scan has SUCCEEDED. Some scan types do not report intermediate progress and go straight from 0 to 100.

is_authenticated

boolean

Whether the scan was set up to authenticate to its targets. Present only for these scan types:

OWASP_ZAP and OWASP_ZAP_ACTIVE: true when authentication was enabled (the default) and at least one target had a recorded login attached when the scan was created; absent otherwise. The login is replayed before each such target is scanned, and a target whose login fails is skipped with skipped_reason "Authentication Failed" while the rest of the scan continues, so check skipped_targets for login failures.
OPENVAS run by the Internal Scanner: true when credentials were configured for at least one target, false otherwise.
NESSUS_AGENT (Tenable agents): always true, because the agent runs on the host it scans.

object

The Risks for this Scan. HostedScan maps the findings from different scanners into a common Risk structure. Available once the scan has a SUCCEEDED state. Absent for scans that end in any other state.

Array of objects

New Risks that this Scan found

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

Array of objects

Risks that a previous Scan of the Target found and were still found by this Scan, including risks that had been closed and were detected again

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

Array of objects

Risks that a previous Scan of the Target found and were no longer found by this Scan

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

required

Array of objects

The full Result files from the Scan. These are the native outputs from the scanner. The structure may change when scanners are updated major versions and each scanner may only support some of the content types. Empty until the scan has a SUCCEEDED state.

Array

result_id	string
content_type	string Enum: "text/html" "application/pdf" "application/xml" "application/json"

required

Array of objects

Array

target_id	string Target's ID
target	string Target URL, FQDN, IP. Absent when the target has no active address

required

Array of objects

Array

target_id	string Target's ID
resolved_target	string Resolved target URL (after redirects or conversion of raw form e.g. `hostedscan.com` -> `https://hostedscan.com/`)

required

Array of objects

Array

target_id	string Target's ID
skipped_reason	string

created_at

required

string <date-time>

When the Scan was created

scheduled_by

string

Id of the Scheduled Scan that started this Scan. Absent for Scans started directly.

report_id

string <uuid>

Id of the report generated for this Scan, for use with Download a Report. Set shortly after the Scan reaches the SUCCEEDED state; absent before then and for Scans that did not produce results.

Request samples

Payload
cURL
NodeJS
Python
Powershell

Content type

application/json

{"type": "NMAP",
"targets": ["hostedscan.com"
],
"target_ids": ["36361122caac53b5e8c6616987"
],
"tags": ["prod"
],
"use_authentication": true
}

Response samples

200
400

Content type

application/json

{"data": {"id": "123422caac53b5e8c6616123",
"type": "NMAP",
"state": "RUNNING",
"progress": 57,
"is_authenticated": true,
"risks": {"new_open": [{"risk_id": "5432122caac53b5e8c6616123"
}
],
"still_open": [{"risk_id": "13131122caac53b5e8c6616123"
}
],
"closed": [{"risk_id": "232321122caac53b5e8c6616123"
}
]
},
"results": [{"result_id": "14141122caac53b5e8c6616123",
"content_type": "application/json"
}
],
"requested_targets": [{"target_id": "36361122caac53b5e8c6616987",
"target": "hostedscan.com"
}
],
"resolved_targets": [{"target_id": "36361122caac53b5e8c6616987",
"resolved_target": "https://hostedscan.com/"
}
],
"skipped_targets": [{"target_id": "17171122caac53b5e8c6616987",
"skipped_reason": "OWASP ZAP scans websites. Unable to GET a website at the target. By default ZAP checks port 80 and 443. Scan an alternative port by setting it on the target url \"www.example.com:1234\""
}
],
"created_at": "2025-10-27T03:00:00Z",
"scheduled_by": "64fa7e5b3b3c1f27e3d92f50",
"report_id": "a3a10e1a-4555-46dc-8da5-ada055c9fcfd"
}
}

List Scans

Returns all Scans, newest first.

Authorizations:

ApiKey

query Parameters

page_token	string Results are returned one page at a time: 500 objects by default, or `page_size` when set. When more results remain, the response includes `next_page_token`; pass it as `page_token` to fetch the next page.
page_size	integer [ 1 .. 499 ] Example: page_size=100 Number of objects per page. The default and largest page size is 500; pass a value from 1 to 499 to receive smaller pages. Values outside that range use the default.
filters	string Example: filters={"state": ["RUNNING"], "type": ["OPENVAS", "NMAP"]} A JSON object, sent as a single URL-encoded string, of filters where each value is an array to filter on. E.g. `{"state": ["RUNNING"], "type": ["OPENVAS", "NMAP"]}` Allowed keys: `type`, `state`, `scheduled_by` (the id of the Scheduled Scan that started the scan), `requested_targets.target_id`, `requested_targets.target` (the target address), and `requested_targets.label` (the target label). Keys that are not allowed are ignored.

Responses

Response Schema: application/json

required

Array of objects (Scan)

Array

id

required

string

Scan's ID

type

required

string (ScanType)

Enum: "DEPENDABOT" "DOMAIN_TAKEOVER" "NESSUS" "NESSUS_AGENT" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SNYK" "SSLYZE"

The scanner or integration that produced a Scan or Risk. DEPENDABOT, DOMAIN_TAKEOVER, NESSUS_AGENT, and SNYK come from integrations and cannot be started with the API; see RunnableScanType for the scan types you can run.

state

required

string (State)

Enum: "FAILED" "OVER_LIMIT" "QUEUED" "RUNNING" "STOPPING" "STOPPED" "SUCCEEDED"

State of a Scan. OVER_LIMIT means the scan did not run because the account exceeded its plan limits. FAILED means the scan could not be completed after retries, for example because none of the targets could be resolved; contact us if a scan fails unexpectedly.

progress

required

number

From 0 to 100. Starts at 0 and is 100 once the scan has SUCCEEDED. Some scan types do not report intermediate progress and go straight from 0 to 100.

is_authenticated

boolean

Whether the scan was set up to authenticate to its targets. Present only for these scan types:

OWASP_ZAP and OWASP_ZAP_ACTIVE: true when authentication was enabled (the default) and at least one target had a recorded login attached when the scan was created; absent otherwise. The login is replayed before each such target is scanned, and a target whose login fails is skipped with skipped_reason "Authentication Failed" while the rest of the scan continues, so check skipped_targets for login failures.
OPENVAS run by the Internal Scanner: true when credentials were configured for at least one target, false otherwise.
NESSUS_AGENT (Tenable agents): always true, because the agent runs on the host it scans.

object

The Risks for this Scan. HostedScan maps the findings from different scanners into a common Risk structure. Available once the scan has a SUCCEEDED state. Absent for scans that end in any other state.

Array of objects

New Risks that this Scan found

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

Array of objects

Risks that a previous Scan of the Target found and were still found by this Scan, including risks that had been closed and were detected again

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

Array of objects

Risks that a previous Scan of the Target found and were no longer found by this Scan

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

required

Array of objects

The full Result files from the Scan. These are the native outputs from the scanner. The structure may change when scanners are updated major versions and each scanner may only support some of the content types. Empty until the scan has a SUCCEEDED state.

Array

result_id	string
content_type	string Enum: "text/html" "application/pdf" "application/xml" "application/json"

required

Array of objects

Array

target_id	string Target's ID
target	string Target URL, FQDN, IP. Absent when the target has no active address

required

Array of objects

Array

target_id	string Target's ID
resolved_target	string Resolved target URL (after redirects or conversion of raw form e.g. `hostedscan.com` -> `https://hostedscan.com/`)

required

Array of objects

Array

target_id	string Target's ID
skipped_reason	string

created_at

required

string <date-time>

When the Scan was created

scheduled_by

string

Id of the Scheduled Scan that started this Scan. Absent for Scans started directly.

report_id

string <uuid>

Id of the report generated for this Scan, for use with Download a Report. Set shortly after the Scan reaches the SUCCEEDED state; absent before then and for Scans that did not produce results.

next_page_token

string

Token that is present when there are more results than can fit in the response. Use the token to get the page of results.

Request samples

cURL
With filters

curl https://api.hostedscan.com/v1/scans \
  -H 'X-HOSTEDSCAN-API-KEY: YOUR_API_KEY'

Response samples

200

Content type

application/json

{"data": [{"id": "123422caac53b5e8c6616123",
"type": "NMAP",
"state": "RUNNING",
"progress": 57,
"is_authenticated": true,
"risks": {"new_open": [{"risk_id": "5432122caac53b5e8c6616123"
}
],
"still_open": [{"risk_id": "13131122caac53b5e8c6616123"
}
],
"closed": [{"risk_id": "232321122caac53b5e8c6616123"
}
]
},
"results": [{"result_id": "14141122caac53b5e8c6616123",
"content_type": "application/json"
}
],
"requested_targets": [{"target_id": "36361122caac53b5e8c6616987",
"target": "hostedscan.com"
}
],
"resolved_targets": [{"target_id": "36361122caac53b5e8c6616987",
"resolved_target": "https://hostedscan.com/"
}
],
"skipped_targets": [{"target_id": "17171122caac53b5e8c6616987",
"skipped_reason": "OWASP ZAP scans websites. Unable to GET a website at the target. By default ZAP checks port 80 and 443. Scan an alternative port by setting it on the target url \"www.example.com:1234\""
}
],
"created_at": "2025-10-27T03:00:00Z",
"scheduled_by": "64fa7e5b3b3c1f27e3d92f50",
"report_id": "a3a10e1a-4555-46dc-8da5-ada055c9fcfd"
}
],
"next_page_token": "string"
}

Get a Scan by id

Returns a single Scan

Authorizations:

ApiKey

path Parameters

id

required

string

ID of the Scan to get

Responses

Response Schema: application/json

required

object (Scan)

The Scan object

id

required

string

Scan's ID

type

required

string (ScanType)

Enum: "DEPENDABOT" "DOMAIN_TAKEOVER" "NESSUS" "NESSUS_AGENT" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SNYK" "SSLYZE"

The scanner or integration that produced a Scan or Risk. DEPENDABOT, DOMAIN_TAKEOVER, NESSUS_AGENT, and SNYK come from integrations and cannot be started with the API; see RunnableScanType for the scan types you can run.

state

required

string (State)

Enum: "FAILED" "OVER_LIMIT" "QUEUED" "RUNNING" "STOPPING" "STOPPED" "SUCCEEDED"

State of a Scan. OVER_LIMIT means the scan did not run because the account exceeded its plan limits. FAILED means the scan could not be completed after retries, for example because none of the targets could be resolved; contact us if a scan fails unexpectedly.

progress

required

number

From 0 to 100. Starts at 0 and is 100 once the scan has SUCCEEDED. Some scan types do not report intermediate progress and go straight from 0 to 100.

is_authenticated

boolean

Whether the scan was set up to authenticate to its targets. Present only for these scan types:

OWASP_ZAP and OWASP_ZAP_ACTIVE: true when authentication was enabled (the default) and at least one target had a recorded login attached when the scan was created; absent otherwise. The login is replayed before each such target is scanned, and a target whose login fails is skipped with skipped_reason "Authentication Failed" while the rest of the scan continues, so check skipped_targets for login failures.
OPENVAS run by the Internal Scanner: true when credentials were configured for at least one target, false otherwise.
NESSUS_AGENT (Tenable agents): always true, because the agent runs on the host it scans.

object

The Risks for this Scan. HostedScan maps the findings from different scanners into a common Risk structure. Available once the scan has a SUCCEEDED state. Absent for scans that end in any other state.

Array of objects

New Risks that this Scan found

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

Array of objects

Risks that a previous Scan of the Target found and were still found by this Scan, including risks that had been closed and were detected again

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

Array of objects

Risks that a previous Scan of the Target found and were no longer found by this Scan

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

required

Array of objects

The full Result files from the Scan. These are the native outputs from the scanner. The structure may change when scanners are updated major versions and each scanner may only support some of the content types. Empty until the scan has a SUCCEEDED state.

Array

result_id	string
content_type	string Enum: "text/html" "application/pdf" "application/xml" "application/json"

required

Array of objects

Array

target_id	string Target's ID
target	string Target URL, FQDN, IP. Absent when the target has no active address

required

Array of objects

Array

target_id	string Target's ID
resolved_target	string Resolved target URL (after redirects or conversion of raw form e.g. `hostedscan.com` -> `https://hostedscan.com/`)

required

Array of objects

Array

target_id	string Target's ID
skipped_reason	string

created_at

required

string <date-time>

When the Scan was created

scheduled_by

string

Id of the Scheduled Scan that started this Scan. Absent for Scans started directly.

report_id

string <uuid>

Id of the report generated for this Scan, for use with Download a Report. Set shortly after the Scan reaches the SUCCEEDED state; absent before then and for Scans that did not produce results.

Request samples

cURL

curl https://api.hostedscan.com/v1/scans/SCAN_ID \
  -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY"

Response samples

200

Content type

application/json

{"data": {"id": "123422caac53b5e8c6616123",
"type": "NMAP",
"state": "RUNNING",
"progress": 57,
"is_authenticated": true,
"risks": {"new_open": [{"risk_id": "5432122caac53b5e8c6616123"
}
],
"still_open": [{"risk_id": "13131122caac53b5e8c6616123"
}
],
"closed": [{"risk_id": "232321122caac53b5e8c6616123"
}
]
},
"results": [{"result_id": "14141122caac53b5e8c6616123",
"content_type": "application/json"
}
],
"requested_targets": [{"target_id": "36361122caac53b5e8c6616987",
"target": "hostedscan.com"
}
],
"resolved_targets": [{"target_id": "36361122caac53b5e8c6616987",
"resolved_target": "https://hostedscan.com/"
}
],
"skipped_targets": [{"target_id": "17171122caac53b5e8c6616987",
"skipped_reason": "OWASP ZAP scans websites. Unable to GET a website at the target. By default ZAP checks port 80 and 443. Scan an alternative port by setting it on the target url \"www.example.com:1234\""
}
],
"created_at": "2025-10-27T03:00:00Z",
"scheduled_by": "64fa7e5b3b3c1f27e3d92f50",
"report_id": "a3a10e1a-4555-46dc-8da5-ada055c9fcfd"
}
}

Delete a Scan

Delete a completed Scan by id.

The scan must be in a terminal state (SUCCEEDED, STOPPED, FAILED, or OVER_LIMIT). Scans that are currently QUEUED, RUNNING, or STOPPING cannot be deleted.

Deleting a scan will also update associated risk history to reflect that the scan's findings are no longer considered.

Authorizations:

ApiKey

path Parameters

id

required

string

ID of the Scan to delete

Responses

Request samples

cURL

curl -X DELETE https://api.hostedscan.com/v1/scans/SCAN_ID \
  -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY"

Stop a running Scan

Request HostedScan to stop a running Scan. This endpoint transitions the Scan to STOPPING (or STOPPED when still QUEUED). Allowed states for stopping are RUNNING and QUEUED. If the scan is already in a terminal state, a 400 may be returned.

Authorizations:

ApiKey

path Parameters

id

required

string

ID of the Scan to stop

Responses

Response Schema: application/json

required

object (Scan)

The updated Scan object

id

required

string

Scan's ID

type

required

string (ScanType)

Enum: "DEPENDABOT" "DOMAIN_TAKEOVER" "NESSUS" "NESSUS_AGENT" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SNYK" "SSLYZE"

The scanner or integration that produced a Scan or Risk. DEPENDABOT, DOMAIN_TAKEOVER, NESSUS_AGENT, and SNYK come from integrations and cannot be started with the API; see RunnableScanType for the scan types you can run.

state

required

string (State)

Enum: "FAILED" "OVER_LIMIT" "QUEUED" "RUNNING" "STOPPING" "STOPPED" "SUCCEEDED"

State of a Scan. OVER_LIMIT means the scan did not run because the account exceeded its plan limits. FAILED means the scan could not be completed after retries, for example because none of the targets could be resolved; contact us if a scan fails unexpectedly.

progress

required

number

From 0 to 100. Starts at 0 and is 100 once the scan has SUCCEEDED. Some scan types do not report intermediate progress and go straight from 0 to 100.

is_authenticated

boolean

Whether the scan was set up to authenticate to its targets. Present only for these scan types:

OWASP_ZAP and OWASP_ZAP_ACTIVE: true when authentication was enabled (the default) and at least one target had a recorded login attached when the scan was created; absent otherwise. The login is replayed before each such target is scanned, and a target whose login fails is skipped with skipped_reason "Authentication Failed" while the rest of the scan continues, so check skipped_targets for login failures.
OPENVAS run by the Internal Scanner: true when credentials were configured for at least one target, false otherwise.
NESSUS_AGENT (Tenable agents): always true, because the agent runs on the host it scans.

object

The Risks for this Scan. HostedScan maps the findings from different scanners into a common Risk structure. Available once the scan has a SUCCEEDED state. Absent for scans that end in any other state.

Array of objects

New Risks that this Scan found

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

Array of objects

Risks that a previous Scan of the Target found and were still found by this Scan, including risks that had been closed and were detected again

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

Array of objects

Risks that a previous Scan of the Target found and were no longer found by this Scan

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

required

Array of objects

The full Result files from the Scan. These are the native outputs from the scanner. The structure may change when scanners are updated major versions and each scanner may only support some of the content types. Empty until the scan has a SUCCEEDED state.

Array

result_id	string
content_type	string Enum: "text/html" "application/pdf" "application/xml" "application/json"

required

Array of objects

Array

target_id	string Target's ID
target	string Target URL, FQDN, IP. Absent when the target has no active address

required

Array of objects

Array

target_id	string Target's ID
resolved_target	string Resolved target URL (after redirects or conversion of raw form e.g. `hostedscan.com` -> `https://hostedscan.com/`)

required

Array of objects

Array

target_id	string Target's ID
skipped_reason	string

created_at

required

string <date-time>

When the Scan was created

scheduled_by

string

Id of the Scheduled Scan that started this Scan. Absent for Scans started directly.

report_id

string <uuid>

Id of the report generated for this Scan, for use with Download a Report. Set shortly after the Scan reaches the SUCCEEDED state; absent before then and for Scans that did not produce results.

Request samples

cURL

curl -X POST https://api.hostedscan.com/v1/scans/SCAN_ID/stop \
  -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY"

Response samples

200

Content type

application/json

{"data": {"id": "123422caac53b5e8c6616123",
"type": "NMAP",
"state": "RUNNING",
"progress": 57,
"is_authenticated": true,
"risks": {"new_open": [{"risk_id": "5432122caac53b5e8c6616123"
}
],
"still_open": [{"risk_id": "13131122caac53b5e8c6616123"
}
],
"closed": [{"risk_id": "232321122caac53b5e8c6616123"
}
]
},
"results": [{"result_id": "14141122caac53b5e8c6616123",
"content_type": "application/json"
}
],
"requested_targets": [{"target_id": "36361122caac53b5e8c6616987",
"target": "hostedscan.com"
}
],
"resolved_targets": [{"target_id": "36361122caac53b5e8c6616987",
"resolved_target": "https://hostedscan.com/"
}
],
"skipped_targets": [{"target_id": "17171122caac53b5e8c6616987",
"skipped_reason": "OWASP ZAP scans websites. Unable to GET a website at the target. By default ZAP checks port 80 and 443. Scan an alternative port by setting it on the target url \"www.example.com:1234\""
}
],
"created_at": "2025-10-27T03:00:00Z",
"scheduled_by": "64fa7e5b3b3c1f27e3d92f50",
"report_id": "a3a10e1a-4555-46dc-8da5-ada055c9fcfd"
}
}

Get a Scan Result File by id

Get a Scan Result File

Authorizations:

ApiKey

path Parameters

id

required

string

ID of the Result to get

Responses

Request samples

cURL

curl https://api.hostedscan.com/v1/results/RESULT_ID \
  -o result.pdf \
  -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY"

Scheduled Scans

Scheduled Scans are used to automate scanning on a regular basis or schedule a one time scan at a specific time in the future.

Create a scheduled scan

Creates a scheduled scan for the authenticated organization.

The first run happens at start_time, or immediately when start_time is omitted, and then repeats according to schedule. Target selection is evaluated at each run, so targets added later that match the filter_set are included automatically.

Authorizations:

ApiKey

Request Body schema: application/json
required

schedule

required

string (Schedule)

Enum: "ONCE" "DAILY" "WEEKLY" "MONTHLY" "QUARTERLY" "CUSTOM"

Frequency of a Scheduled Scan.

ONCE: runs one time and is then deleted, so it disappears from the Scheduled Scans list after running.
DAILY and WEEKLY: run every 24 hours or every 7 days from the previous scheduled run time. Runs are not adjusted for daylight saving time changes.
MONTHLY: runs once a month on the day of the month of start_time.
QUARTERLY and CUSTOM: run on each of the schedule_dates. Dates that have passed are moved forward one year.

scan_types

required

Array of strings (RunnableScanType)

Items Enum: "NESSUS" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SSLYZE"

required

object

Target selection for the scheduled scan. Send {} to scan every target. When both target_ids and tags are given, only targets matching both are scanned.

target_ids	Array of strings
tags	Array of strings

email_notification

required

string (EmailNotification)

Enum: "NEVER" "ON_CHANGES" "ALWAYS"

Email notification preference for scans

start_time

string <date-time>

Time of the first run. Defaults to now, so a scheduled scan created without start_time runs right away and then repeats. A start_time in the past also runs right away. For MONTHLY schedules the day of month of start_time is the day each run happens. Not used as the first run time for QUARTERLY and CUSTOM schedules, which first run on the earliest schedule_dates entry.

schedule_dates

Array of strings <date-time> [ items <date-time > ]

Required when schedule is CUSTOM (1 to 100 dates) or QUARTERLY (exactly 4 dates, one per quarter). Ignored for other schedules.

email_to

Array of strings <email> <= 5 items [ items <email > ]

name

string [ 1 .. 100 ] characters

Responses

Response Schema: application/json

object (ScheduledScan)

id

required

string

name

string

Absent when the Scheduled Scan has no name

schedule

required

string (Schedule)

Enum: "ONCE" "DAILY" "WEEKLY" "MONTHLY" "QUARTERLY" "CUSTOM"

Frequency of a Scheduled Scan.

ONCE: runs one time and is then deleted, so it disappears from the Scheduled Scans list after running.
DAILY and WEEKLY: run every 24 hours or every 7 days from the previous scheduled run time. Runs are not adjusted for daylight saving time changes.
MONTHLY: runs once a month on the day of the month of start_time.
QUARTERLY and CUSTOM: run on each of the schedule_dates. Dates that have passed are moved forward one year.

scan_types

required

Array of strings (ScanType)

Items Enum: "DEPENDABOT" "DOMAIN_TAKEOVER" "NESSUS" "NESSUS_AGENT" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SNYK" "SSLYZE"

object

Criteria for selecting targets to scan, evaluated at each run. Absent when every target in the account is scanned. When both target_ids and tags are present, only targets matching both are scanned.

target_ids	Array of strings List of target IDs to include in the scan
tags	Array of strings List of tags. All targets with at least one matching tag will be scanned

last_ran

string <date-time>

Date of the last scan. Absent until the Scheduled Scan has run for the first time

next_run

required

string <date-time>

Date of the next upcoming scan

created_at

required

string <date-time>

Date when the Scheduled Scan was created

Request samples

Payload
cURL

Content type

application/json

{"schedule": "WEEKLY",
"scan_types": ["NMAP"
],
"filter_set": {"target_ids": ["string"
],
"tags": ["string"
]
},
"email_notification": "NEVER",
"start_time": "2019-08-24T14:15:22Z",
"schedule_dates": ["2019-08-24T14:15:22Z"
],
"email_to": ["user@example.com"
],
"name": "string"
}

Response samples

200
400

Content type

application/json

{"data": {"id": "64fa7e5b3b3c1f27e3d92f50",
"name": "Weekly Web App Scan",
"schedule": "WEEKLY",
"scan_types": ["NMAP"
],
"targets_filter": {"target_ids": ["64fa7e5b3b3c1f27e3d92f50",
"64fa7e5b3b3c1f27e3d92f51"
],
"tags": ["production",
"webserver"
]
},
"last_ran": "2025-10-27T03:00:00Z",
"next_run": "2025-11-03T03:00:00Z",
"created_at": "2025-09-15T14:12:00Z"
}
}

List all Scheduled Scans

Returns all Scheduled Scans, newest first.

Authorizations:

ApiKey

query Parameters

page_token	string Results are returned one page at a time: 500 objects by default, or `page_size` when set. When more results remain, the response includes `next_page_token`; pass it as `page_token` to fetch the next page.
page_size	integer [ 1 .. 499 ] Example: page_size=100 Number of objects per page. The default and largest page size is 500; pass a value from 1 to 499 to receive smaller pages. Values outside that range use the default.

Responses

Response Schema: application/json

required

Array of objects (ScheduledScan)

Array

id

required

string

name

string

Absent when the Scheduled Scan has no name

schedule

required

string (Schedule)

Enum: "ONCE" "DAILY" "WEEKLY" "MONTHLY" "QUARTERLY" "CUSTOM"

Frequency of a Scheduled Scan.

ONCE: runs one time and is then deleted, so it disappears from the Scheduled Scans list after running.
DAILY and WEEKLY: run every 24 hours or every 7 days from the previous scheduled run time. Runs are not adjusted for daylight saving time changes.
MONTHLY: runs once a month on the day of the month of start_time.
QUARTERLY and CUSTOM: run on each of the schedule_dates. Dates that have passed are moved forward one year.

scan_types

required

Array of strings (ScanType)

Items Enum: "DEPENDABOT" "DOMAIN_TAKEOVER" "NESSUS" "NESSUS_AGENT" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SNYK" "SSLYZE"

object

Criteria for selecting targets to scan, evaluated at each run. Absent when every target in the account is scanned. When both target_ids and tags are present, only targets matching both are scanned.

target_ids	Array of strings List of target IDs to include in the scan
tags	Array of strings List of tags. All targets with at least one matching tag will be scanned

last_ran

string <date-time>

Date of the last scan. Absent until the Scheduled Scan has run for the first time

next_run

required

string <date-time>

Date of the next upcoming scan

created_at

required

string <date-time>

Date when the Scheduled Scan was created

next_page_token

string

Token that is present when there are more results than can fit in the response. Use the token to get the page of results.

Response samples

200

Content type

application/json

{"data": [{"id": "64fa7e5b3b3c1f27e3d92f50",
"name": "Weekly Web App Scan",
"schedule": "WEEKLY",
"scan_types": ["NMAP"
],
"targets_filter": {"target_ids": ["64fa7e5b3b3c1f27e3d92f50",
"64fa7e5b3b3c1f27e3d92f51"
],
"tags": ["production",
"webserver"
]
},
"last_ran": "2025-10-27T03:00:00Z",
"next_run": "2025-11-03T03:00:00Z",
"created_at": "2025-09-15T14:12:00Z"
}
],
"next_page_token": "string"
}

Get a Scheduled Scan

Returns a single Scheduled Scan

Authorizations:

ApiKey

path Parameters

id

required

string

Example: 64fa7e5b3b3c1f27e3d92f50

ID of the Scheduled Scan to get

Responses

Response Schema: application/json

required

object (ScheduledScan)

The Scheduled Scan object

id

required

string

name

string

Absent when the Scheduled Scan has no name

schedule

required

string (Schedule)

Enum: "ONCE" "DAILY" "WEEKLY" "MONTHLY" "QUARTERLY" "CUSTOM"

Frequency of a Scheduled Scan.

ONCE: runs one time and is then deleted, so it disappears from the Scheduled Scans list after running.
DAILY and WEEKLY: run every 24 hours or every 7 days from the previous scheduled run time. Runs are not adjusted for daylight saving time changes.
MONTHLY: runs once a month on the day of the month of start_time.
QUARTERLY and CUSTOM: run on each of the schedule_dates. Dates that have passed are moved forward one year.

scan_types

required

Array of strings (ScanType)

Items Enum: "DEPENDABOT" "DOMAIN_TAKEOVER" "NESSUS" "NESSUS_AGENT" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SNYK" "SSLYZE"

object

Criteria for selecting targets to scan, evaluated at each run. Absent when every target in the account is scanned. When both target_ids and tags are present, only targets matching both are scanned.

target_ids	Array of strings List of target IDs to include in the scan
tags	Array of strings List of tags. All targets with at least one matching tag will be scanned

last_ran

string <date-time>

Date of the last scan. Absent until the Scheduled Scan has run for the first time

next_run

required

string <date-time>

Date of the next upcoming scan

created_at

required

string <date-time>

Date when the Scheduled Scan was created

Response samples

200

Content type

application/json

{"data": {"id": "64fa7e5b3b3c1f27e3d92f50",
"name": "Weekly Web App Scan",
"schedule": "WEEKLY",
"scan_types": ["NMAP"
],
"targets_filter": {"target_ids": ["64fa7e5b3b3c1f27e3d92f50",
"64fa7e5b3b3c1f27e3d92f51"
],
"tags": ["production",
"webserver"
]
},
"last_ran": "2025-10-27T03:00:00Z",
"next_run": "2025-11-03T03:00:00Z",
"created_at": "2025-09-15T14:12:00Z"
}
}

Delete a Scheduled Scan

Deletes a Scheduled Scan for the authenticated organization.

Authorizations:

ApiKey

path Parameters

id

required

string

Example: 64fa7e5b3b3c1f27e3d92f50

ID of the Scheduled Scan to delete

Responses

Request samples

cURL

curl -X DELETE 'https://api.hostedscan.com/v1/scans/scheduled/SCHEDULED_SCAN_ID' \
  -H 'X-HOSTEDSCAN-API-KEY: YOUR_API_KEY'

Update a Scheduled Scan

Replaces the configuration of a Scheduled Scan. schedule, filter_set, and email_notification must be sent on every update.

Omitted scan_types, email_to, disabled, and start_time keep their current values. An omitted name clears the name, so include it to keep it. schedule_dates is required when schedule is CUSTOM or QUARTERLY. next_run is recalculated on every update.

Authorizations:

ApiKey

path Parameters

id

required

string

Example: 64fa7e5b3b3c1f27e3d92f50

ID of the Scheduled Scan to update

Request Body schema: application/json
required

schedule

required

string (Schedule)

Enum: "ONCE" "DAILY" "WEEKLY" "MONTHLY" "QUARTERLY" "CUSTOM"

Frequency of a Scheduled Scan.

ONCE: runs one time and is then deleted, so it disappears from the Scheduled Scans list after running.
DAILY and WEEKLY: run every 24 hours or every 7 days from the previous scheduled run time. Runs are not adjusted for daylight saving time changes.
MONTHLY: runs once a month on the day of the month of start_time.
QUARTERLY and CUSTOM: run on each of the schedule_dates. Dates that have passed are moved forward one year.

scan_types

Array of strings (RunnableScanType)

Items Enum: "NESSUS" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SSLYZE"

required

object

Target selection for the scheduled scan. Send {} to scan every target. When both target_ids and tags are given, only targets matching both are scanned.

target_ids	Array of strings
tags	Array of strings

email_notification

required

string (EmailNotification)

Enum: "NEVER" "ON_CHANGES" "ALWAYS"

Email notification preference for scans

start_time

string <date-time>

When present and no more than 5 minutes in the past, used as the next run time. Otherwise the next run is recalculated from schedule and the last run.

schedule_dates

Array of strings <date-time> [ items <date-time > ]

Required when schedule is CUSTOM (1 to 100 dates) or QUARTERLY (exactly 4 dates, one per quarter). Ignored for other schedules.

email_to

Array of strings <email> <= 5 items [ items <email > ]

name

string [ 1 .. 100 ] characters

disabled

boolean

Set to true to pause the schedule without deleting it.

Responses

Response Schema: application/json

object (ScheduledScan)

id

required

string

name

string

Absent when the Scheduled Scan has no name

schedule

required

string (Schedule)

Enum: "ONCE" "DAILY" "WEEKLY" "MONTHLY" "QUARTERLY" "CUSTOM"

Frequency of a Scheduled Scan.

ONCE: runs one time and is then deleted, so it disappears from the Scheduled Scans list after running.
DAILY and WEEKLY: run every 24 hours or every 7 days from the previous scheduled run time. Runs are not adjusted for daylight saving time changes.
MONTHLY: runs once a month on the day of the month of start_time.
QUARTERLY and CUSTOM: run on each of the schedule_dates. Dates that have passed are moved forward one year.

scan_types

required

Array of strings (ScanType)

Items Enum: "DEPENDABOT" "DOMAIN_TAKEOVER" "NESSUS" "NESSUS_AGENT" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SNYK" "SSLYZE"

object

Criteria for selecting targets to scan, evaluated at each run. Absent when every target in the account is scanned. When both target_ids and tags are present, only targets matching both are scanned.

target_ids	Array of strings List of target IDs to include in the scan
tags	Array of strings List of tags. All targets with at least one matching tag will be scanned

last_ran

string <date-time>

Date of the last scan. Absent until the Scheduled Scan has run for the first time

next_run

required

string <date-time>

Date of the next upcoming scan

created_at

required

string <date-time>

Date when the Scheduled Scan was created

Request samples

Payload
cURL

Content type

application/json

{"schedule": "WEEKLY",
"scan_types": ["NMAP"
],
"filter_set": {"target_ids": ["string"
],
"tags": ["string"
]
},
"email_notification": "NEVER",
"start_time": "2019-08-24T14:15:22Z",
"schedule_dates": ["2019-08-24T14:15:22Z"
],
"email_to": ["user@example.com"
],
"name": "string",
"disabled": true
}

Response samples

200
400

Content type

application/json

{"data": {"id": "64fa7e5b3b3c1f27e3d92f50",
"name": "Weekly Web App Scan",
"schedule": "WEEKLY",
"scan_types": ["NMAP"
],
"targets_filter": {"target_ids": ["64fa7e5b3b3c1f27e3d92f50",
"64fa7e5b3b3c1f27e3d92f51"
],
"tags": ["production",
"webserver"
]
},
"last_ran": "2025-10-27T03:00:00Z",
"next_run": "2025-11-03T03:00:00Z",
"created_at": "2025-09-15T14:12:00Z"
}
}

Authenticated Scanning

Authenticated scanning lets the OWASP_ZAP and OWASP_ZAP_ACTIVE scanners log in to a website before scanning, so pages behind the login are tested too. The login is a Selenium IDE recording (a .side file) attached to the Target, replayed at the start of each scan. To record one, see the recorded login guide; for the feature overview see https://hostedscan.com/authenticated-web-app-vulnerability-scan.

Steps to run an authenticated scan

Create the Target with Create a new Target.
Attach the recording with Upload a Selenium login recording. The Target's auth_selenium_file field shows the attached file name; uploading again replaces it.
Start an OWASP_ZAP or OWASP_ZAP_ACTIVE scan with Start a new Scan. Authentication is on by default for those scan types; send use_authentication: false to run the scan without logging in. Other scan types cannot use the login session and reject use_authentication: true with 400.

What the Scan reports

The Scan's is_authenticated field is true when authentication was enabled and at least one of its targets had a recording attached when the scan was created. It reports that a login was configured, not that it succeeded: before each such target is scanned the recording is replayed, and if the login fails that target is skipped with skipped_reason "Authentication Failed" while the rest of the scan continues. Check skipped_targets on the finished Scan to see login failures.

Uploading the recording with curl

curl -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" -F file=@YourSeleniumRecording.side https://api.hostedscan.com/v1/targets/TARGET_ID/auth/selenium

Upload a Selenium login recording

Upload a Selenium IDE recording (.side file) of the login sequence for a Target. OWASP_ZAP and OWASP_ZAP_ACTIVE scans of the Target replay the recording to log in before scanning. Uploading again replaces the previous recording. See the Authenticated Scanning overview for the full workflow.

Authorizations:

ApiKey

path Parameters

id

required

string

ID of the Target to attach the recording to

Request Body schema: multipart/form-data
required

file

required

string <binary>

Selenium IDE recording. The file name must end in .side, the file must be at most 5MB, and the contents must be the JSON that Selenium IDE exports (format versions 1 to 3), including the top-level id, version, name, url, tests, and urls properties.

Responses

Response Schema: application/json

required

object (Target)

The updated Target object

id

required

string

target

string

The target's address. For targets imported from a code integration such as GitHub or Snyk this is the repository or project identifier. Absent for auto-imported targets that have no active address, such as a shut-down cloud instance.

label

string

tags

Array of strings

object

The target's current health score, derived from its open risks. Health scores are being rolled out and are currently returned for a limited set of accounts; for other accounts this field is absent. When enabled, it is present only for targets that have been scanned at least once. A scanned target with no open risks returns { "score": 0, "grade": "A" } (zero is best; higher scores indicate more severe risks).

score required	integer <int32> Numeric health score. `0` means no open risks; higher values indicate more severe open risks.
grade required	string Enum: "A" "B" "C" "D" "F" Letter grade derived from the score.

auth_selenium_file

string

Filename of the Selenium .side recording attached to this target for authenticated scanning. Absent when no recording is attached. Upload one with Upload a Selenium login recording.

object (ScannerSettings)

Scanner settings configured on this target. Returned only when the target has any set, and only the settings that are set are included.

object

Settings specific to the ZAP scanner

included_domains

Array of strings <= 20 items

Domains to include in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_domains

Array of strings <= 20 items

Domains to exclude in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_urls

Array of strings <= 20 items

Specific URLS to avoid on the site. Each entry must be an absolute URL with an http:// or https:// scheme

seed_urls

Array of strings <= 20 items

Specific seed URLS to help the crawler discover sections of your website that are hidden or hard to reach. Each entry must be an absolute URL with an http:// or https:// scheme

anti_csrf_tokens

Array of strings <= 30 items [ items <= 100 characters ^[a-zA-Z0-9\-_\[\]]+$ ]

Names of the anti-CSRF tokens used by the site, e.g. ["__RequestVerificationToken", "XSRF-TOKEN", "_csrf"]. These tokens will be automatically handled during scanning. Names may contain letters, numbers, underscores, hyphens, and square brackets

scan_discovered_subdomains

boolean

Default: true

Scan discovered subdomains of the initial target. Defaults to true when not set

scan_third_party_javascript

boolean

Default: true

Check included third party javascript for vulnerabilities. Defaults to true when not set

Array of objects <= 5 items

Custom headers to send with each request. Up to 5 headers

Array (<= 5 items)

key required	string <= 512 characters ^[a-zA-Z0-9\-_]+$ Header name. Letters, numbers, hyphens, and underscores only
value required	string <= 5000 characters Header value. Printable ASCII characters only

Array of objects <= 5 items

Custom cookies to send with each request. Up to 5 cookies

Array (<= 5 items)

domain required	string The host to which the cookie will be sent, as a hostname or IP address without a leading dot, e.g. `example.com`. More details here
expiry	number The date to expire the cookie, in the number of seconds from epoch e.g. 1675098987. Time is UTC.
httpOnly	boolean Default: false Makes the cookie inaccessible to JavaScript on the page. Defaults to `false`. More details here.
name required	string Defines the cookie name. Must be valid ASCII with some exclusions. More details here
path required	string Indicates the path that must exist in the requested URL for the browser to send the Cookie header. More details here.
sameSite	string Enum: "None" "Lax" "Strict" Controls whether or not a cookie is sent with cross-site requests. More details here.
secure	boolean Default: false Send only over https. Defaults to `false`. More details here.
value required	string Any US-ASCII character excluding control characters, whitespace, double quotes, commas, semicolons and backslashes. More details here.

Request samples

cURL

curl -X POST \
  -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" \
  -F "file=@login.side" \
  https://api.hostedscan.com/v1/targets/TARGET_ID/auth/selenium

Response samples

200
400

Content type

application/json

{"data": {"id": "111122caac53b5e8c6616e12",
"target": "www.example.com",
"label": "production-website",
"tags": ["prod"
],
"health_score": {"score": 150,
"grade": "A"
},
"auth_selenium_file": "login.side",
"scanner_settings": {"zap": {"included_domains": ["app.example.com"
],
"excluded_domains": ["blog.example.com"
],
"excluded_urls": ["https://example.com/scripts/"
],
"seed_urls": ["https://example.com/unlinked-page"
],
"anti_csrf_tokens": ["XSRF-TOKEN"
],
"scan_discovered_subdomains": true,
"scan_third_party_javascript": true,
"headers": [{"key": "X-API-KEY",
"value": "example"
}
],
"cookies": [{"domain": "example.com",
"expiry": 1734732496,
"httpOnly": false,
"name": "mycookie",
"path": "/webapp",
"sameSite": "Strict",
"secure": false,
"value": "test123"
}
]
}
}
}
}

Risks

Risks are the vulnerability findings from scans. For example, a vulnerable javascript dependency or an open port.

List Risks

Returns all Risks, including CLOSED ones, newest first (by the time the risk was first created, not by its latest detection). OpenVAS risks below your account's minimum Quality of Detection setting are not returned.

Authorizations:

ApiKey

query Parameters

page_token	string Results are returned one page at a time: 500 objects by default, or `page_size` when set. When more results remain, the response includes `next_page_token`; pass it as `page_token` to fetch the next page.
page_size	integer [ 1 .. 499 ] Example: page_size=100 Number of objects per page. The default and largest page size is 500; pass a value from 1 to 499 to receive smaller pages. Values outside that range use the default.
filters	string Example: filters={"risk_definition.scan_type": ["NMAP", "NMAP_UDP"]} A JSON object, sent as a single URL-encoded string, of filters where each value is an array to filter on. E.g. `{"risk_definition.scan_type": ["NMAP", "NMAP_UDP"]}` Allowed keys: `target_id`, `status`, `tags`, `label` (the target label), `risk_definition.scan_type`, `risk_definition.threat_level`, `risk_definition.title`, and `risk_definition.cve_ids` (up to 100 CVE ids such as `CVE-2024-3094`; matches risks whose definition references any of them). Keys that are not allowed are ignored. `status` accepts `OPEN` and `CLOSED`. Accepted risks keep the `OPEN` status, so use the `is_accepted` field of the returned Risks to tell them apart. `tags` and `risk_definition.title` are exact matches; tags are stored in lowercase.

Responses

Response Schema: application/json

required

Array of objects (Risk)

Array

id

required

string

target_id

required

string

target

string

The target's address, the same value as the target field of the Target. Absent when the target has no active address.

target_label

string

tags

Array of strings

status

required

string

Enum: "OPEN" "CLOSED"

CLOSED once a later scan of the same target no longer detects the risk. Accepted risks keep the OPEN status; see is_accepted.

first_detected_at

required

string <date-time>

When the risk was first detected on this target. Does not change when the risk closes and is detected again later.

last_detected_at

required

string <date-time>

When a scan most recently detected the risk. Not updated when the risk is closed.

is_accepted

required

boolean

true when at least one accepted risk rule in the account matches this risk, in which case accepted_by lists the matching rules.

required

Array of objects

The accepted risk rules that match this risk. Empty when the risk is not accepted.

Array

note	string
created_at required	string <date-time>
last_updated_at required	string <date-time>

required

object

scan_type required	string (ScanType) Enum: "DEPENDABOT" "DOMAIN_TAKEOVER" "NESSUS" "NESSUS_AGENT" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SNYK" "SSLYZE" The scanner or integration that produced a Scan or Risk. `DEPENDABOT`, `DOMAIN_TAKEOVER`, `NESSUS_AGENT`, and `SNYK` come from integrations and cannot be started with the API; see `RunnableScanType` for the scan types you can run.
title required	string
threat_level required	string (ThreatLevel) Enum: "LOW" "MEDIUM" "HIGH" "CRITICAL"
description	string May not be available for all scanners
solution	string May not be available for all scanners
references	Array of strings May not be available for all scanners
cvss	string or null CVSS base score as a string, e.g. `7.5`. May not be available for all scanners, and may be `null` for some integrations.
additional_info	object Scanner specific details for this risk: the scanner's description of the finding merged with the details from the most recent detection, such as the port, URL, or evidence. The keys are scanner specific and could change when scanners are updated to new major versions. Web application findings can include the request and response data the scanner captured.

next_page_token

string

Token that is present when there are more results than can fit in the response. Use the token to get the page of results.

Request samples

cURL
With Filters

curl -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" https://api.hostedscan.com/v1/risks

Response samples

200

Content type

application/json

{"data": [{"id": "111122caac53b5e8c6616123",
"target_id": "211122caac53b5e8c6616321",
"target": "www.example.com",
"target_label": "production-website",
"tags": ["prod"
],
"status": "OPEN",
"first_detected_at": "2019-08-24T14:15:22Z",
"last_detected_at": "2019-08-24T14:15:22Z",
"is_accepted": true,
"accepted_by": [{"note": "Expected behavior for production webserver to have ports 80 and 443 open",
"created_at": "2019-08-24T14:15:22Z",
"last_updated_at": "2019-08-24T14:15:22Z"
}
],
"risk_definition": {"scan_type": "NMAP",
"title": "Port 443 Open",
"threat_level": "MEDIUM",
"description": "Port 443 was detected open.",
"solution": "Close the port or restrict access to it with a firewall.",
"references": ["https://owasp.org/www-project-web-security-testing-guide/v41/4-Web_Application_Security_Testing/01-Information_Gathering/04-Enumerate_Applications_on_Webserver"
],
"cvss": "7.5",
"additional_info": { }
}
}
],
"next_page_token": "string"
}

Get a Risk by id

Returns a single Risk

Authorizations:

ApiKey

path Parameters

id

required

string

ID of the Risk to get

Responses

Response Schema: application/json

required

object (Risk)

The Risk object

id

required

string

target_id

required

string

target

string

The target's address, the same value as the target field of the Target. Absent when the target has no active address.

target_label

string

tags

Array of strings

status

required

string

Enum: "OPEN" "CLOSED"

CLOSED once a later scan of the same target no longer detects the risk. Accepted risks keep the OPEN status; see is_accepted.

first_detected_at

required

string <date-time>

When the risk was first detected on this target. Does not change when the risk closes and is detected again later.

last_detected_at

required

string <date-time>

When a scan most recently detected the risk. Not updated when the risk is closed.

is_accepted

required

boolean

true when at least one accepted risk rule in the account matches this risk, in which case accepted_by lists the matching rules.

required

Array of objects

The accepted risk rules that match this risk. Empty when the risk is not accepted.

Array

note	string
created_at required	string <date-time>
last_updated_at required	string <date-time>

required

object

scan_type required	string (ScanType) Enum: "DEPENDABOT" "DOMAIN_TAKEOVER" "NESSUS" "NESSUS_AGENT" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SNYK" "SSLYZE" The scanner or integration that produced a Scan or Risk. `DEPENDABOT`, `DOMAIN_TAKEOVER`, `NESSUS_AGENT`, and `SNYK` come from integrations and cannot be started with the API; see `RunnableScanType` for the scan types you can run.
title required	string
threat_level required	string (ThreatLevel) Enum: "LOW" "MEDIUM" "HIGH" "CRITICAL"
description	string May not be available for all scanners
solution	string May not be available for all scanners
references	Array of strings May not be available for all scanners
cvss	string or null CVSS base score as a string, e.g. `7.5`. May not be available for all scanners, and may be `null` for some integrations.
additional_info	object Scanner specific details for this risk: the scanner's description of the finding merged with the details from the most recent detection, such as the port, URL, or evidence. The keys are scanner specific and could change when scanners are updated to new major versions. Web application findings can include the request and response data the scanner captured.

Request samples

cURL

curl -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" https://api.hostedscan.com/v1/risks/RISK_ID

Response samples

200

Content type

application/json

{"data": {"id": "111122caac53b5e8c6616123",
"target_id": "211122caac53b5e8c6616321",
"target": "www.example.com",
"target_label": "production-website",
"tags": ["prod"
],
"status": "OPEN",
"first_detected_at": "2019-08-24T14:15:22Z",
"last_detected_at": "2019-08-24T14:15:22Z",
"is_accepted": true,
"accepted_by": [{"note": "Expected behavior for production webserver to have ports 80 and 443 open",
"created_at": "2019-08-24T14:15:22Z",
"last_updated_at": "2019-08-24T14:15:22Z"
}
],
"risk_definition": {"scan_type": "NMAP",
"title": "Port 443 Open",
"threat_level": "MEDIUM",
"description": "Port 443 was detected open.",
"solution": "Close the port or restrict access to it with a firewall.",
"references": ["https://owasp.org/www-project-web-security-testing-guide/v41/4-Web_Application_Security_Testing/01-Information_Gathering/04-Enumerate_Applications_on_Webserver"
],
"cvss": "7.5",
"additional_info": { }
}
}
}

Targets

Targets are the servers and websites to be scanned for vulnerabilities. A target is defined by an IP address, URL, or Fully Qualified Domain Name.

Create a new Target

Authorizations:

ApiKey

query Parameters

upsert

boolean

Set to true to update the existing Target with the same address instead of failing with 400. On an upsert, label and tags are replaced by the request values (an omitted label is removed and omitted tags become empty), while omitted scanner_settings are kept. Defaults to false.

Request Body schema: application/json
required

target

required

string <= 2048 characters

Public IPv4 address, Fully Qualified Domain Name, or URL with an http:// or https:// scheme, eg. 123.456.789.123, google.com, or https://google.com/path. Private or reserved IP addresses, IPv6 addresses, and CIDR ranges are not accepted by this endpoint — add CIDR targets in the dashboard.

label

string <= 255 characters

Label for the Target

tags

Array of strings <= 10 items [ items <= 255 characters ]

Up to 10 tags for filtering, selecting, and sorting. Tags are stored in lowercase.

object (ScannerSettings)

The settings to use with a particular scanner when scanning this target.

object

Settings specific to the ZAP scanner

included_domains

Array of strings <= 20 items

Domains to include in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_domains

Array of strings <= 20 items

Domains to exclude in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_urls

Array of strings <= 20 items

Specific URLS to avoid on the site. Each entry must be an absolute URL with an http:// or https:// scheme

seed_urls

Array of strings <= 20 items

Specific seed URLS to help the crawler discover sections of your website that are hidden or hard to reach. Each entry must be an absolute URL with an http:// or https:// scheme

anti_csrf_tokens

Array of strings <= 30 items [ items <= 100 characters ^[a-zA-Z0-9\-_\[\]]+$ ]

Names of the anti-CSRF tokens used by the site, e.g. ["__RequestVerificationToken", "XSRF-TOKEN", "_csrf"]. These tokens will be automatically handled during scanning. Names may contain letters, numbers, underscores, hyphens, and square brackets

scan_discovered_subdomains

boolean

Default: true

Scan discovered subdomains of the initial target. Defaults to true when not set

scan_third_party_javascript

boolean

Default: true

Check included third party javascript for vulnerabilities. Defaults to true when not set

Array of objects <= 5 items

Custom headers to send with each request. Up to 5 headers

Array (<= 5 items)

key required	string <= 512 characters ^[a-zA-Z0-9\-_]+$ Header name. Letters, numbers, hyphens, and underscores only
value required	string <= 5000 characters Header value. Printable ASCII characters only

Array of objects <= 5 items

Custom cookies to send with each request. Up to 5 cookies

Array (<= 5 items)

domain required	string The host to which the cookie will be sent, as a hostname or IP address without a leading dot, e.g. `example.com`. More details here
expiry	number The date to expire the cookie, in the number of seconds from epoch e.g. 1675098987. Time is UTC.
httpOnly	boolean Default: false Makes the cookie inaccessible to JavaScript on the page. Defaults to `false`. More details here.
name required	string Defines the cookie name. Must be valid ASCII with some exclusions. More details here
path required	string Indicates the path that must exist in the requested URL for the browser to send the Cookie header. More details here.
sameSite	string Enum: "None" "Lax" "Strict" Controls whether or not a cookie is sent with cross-site requests. More details here.
secure	boolean Default: false Send only over https. Defaults to `false`. More details here.
value required	string Any US-ASCII character excluding control characters, whitespace, double quotes, commas, semicolons and backslashes. More details here.

Responses

Response Schema: application/json

required

object (Target)

The created Target object

id

required

string

target

string

The target's address. For targets imported from a code integration such as GitHub or Snyk this is the repository or project identifier. Absent for auto-imported targets that have no active address, such as a shut-down cloud instance.

label

string

tags

Array of strings

object

The target's current health score, derived from its open risks. Health scores are being rolled out and are currently returned for a limited set of accounts; for other accounts this field is absent. When enabled, it is present only for targets that have been scanned at least once. A scanned target with no open risks returns { "score": 0, "grade": "A" } (zero is best; higher scores indicate more severe risks).

score required	integer <int32> Numeric health score. `0` means no open risks; higher values indicate more severe open risks.
grade required	string Enum: "A" "B" "C" "D" "F" Letter grade derived from the score.

auth_selenium_file

string

Filename of the Selenium .side recording attached to this target for authenticated scanning. Absent when no recording is attached. Upload one with Upload a Selenium login recording.

object (ScannerSettings)

Scanner settings configured on this target. Returned only when the target has any set, and only the settings that are set are included.

object

Settings specific to the ZAP scanner

included_domains

Array of strings <= 20 items

Domains to include in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_domains

Array of strings <= 20 items

Domains to exclude in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_urls

Array of strings <= 20 items

Specific URLS to avoid on the site. Each entry must be an absolute URL with an http:// or https:// scheme

seed_urls

Array of strings <= 20 items

Specific seed URLS to help the crawler discover sections of your website that are hidden or hard to reach. Each entry must be an absolute URL with an http:// or https:// scheme

anti_csrf_tokens

Array of strings <= 30 items [ items <= 100 characters ^[a-zA-Z0-9\-_\[\]]+$ ]

Names of the anti-CSRF tokens used by the site, e.g. ["__RequestVerificationToken", "XSRF-TOKEN", "_csrf"]. These tokens will be automatically handled during scanning. Names may contain letters, numbers, underscores, hyphens, and square brackets

scan_discovered_subdomains

boolean

Default: true

Scan discovered subdomains of the initial target. Defaults to true when not set

scan_third_party_javascript

boolean

Default: true

Check included third party javascript for vulnerabilities. Defaults to true when not set

Array of objects <= 5 items

Custom headers to send with each request. Up to 5 headers

Array (<= 5 items)

key required	string <= 512 characters ^[a-zA-Z0-9\-_]+$ Header name. Letters, numbers, hyphens, and underscores only
value required	string <= 5000 characters Header value. Printable ASCII characters only

Array of objects <= 5 items

Custom cookies to send with each request. Up to 5 cookies

Array (<= 5 items)

domain required	string The host to which the cookie will be sent, as a hostname or IP address without a leading dot, e.g. `example.com`. More details here
expiry	number The date to expire the cookie, in the number of seconds from epoch e.g. 1675098987. Time is UTC.
httpOnly	boolean Default: false Makes the cookie inaccessible to JavaScript on the page. Defaults to `false`. More details here.
name required	string Defines the cookie name. Must be valid ASCII with some exclusions. More details here
path required	string Indicates the path that must exist in the requested URL for the browser to send the Cookie header. More details here.
sameSite	string Enum: "None" "Lax" "Strict" Controls whether or not a cookie is sent with cross-site requests. More details here.
secure	boolean Default: false Send only over https. Defaults to `false`. More details here.
value required	string Any US-ASCII character excluding control characters, whitespace, double quotes, commas, semicolons and backslashes. More details here.

Request samples

Payload
cURL

Content type

application/json

{"target": "hostedscan.com",
"label": "production website",
"tags": ["prod"
],
"scanner_settings": {"zap": {"included_domains": ["app.example.com"
],
"excluded_domains": ["blog.example.com"
],
"excluded_urls": ["https://example.com/scripts/"
],
"seed_urls": ["https://example.com/unlinked-page"
],
"anti_csrf_tokens": ["XSRF-TOKEN"
],
"scan_discovered_subdomains": true,
"scan_third_party_javascript": true,
"headers": [{"key": "X-API-KEY",
"value": "example"
}
],
"cookies": [{"domain": "example.com",
"expiry": 1734732496,
"httpOnly": false,
"name": "mycookie",
"path": "/webapp",
"sameSite": "Strict",
"secure": false,
"value": "test123"
}
]
}
}
}

Response samples

200
400

Content type

application/json

{"data": {"id": "111122caac53b5e8c6616e12",
"target": "www.example.com",
"label": "production-website",
"tags": ["prod"
],
"health_score": {"score": 150,
"grade": "A"
},
"auth_selenium_file": "login.side",
"scanner_settings": {"zap": {"included_domains": ["app.example.com"
],
"excluded_domains": ["blog.example.com"
],
"excluded_urls": ["https://example.com/scripts/"
],
"seed_urls": ["https://example.com/unlinked-page"
],
"anti_csrf_tokens": ["XSRF-TOKEN"
],
"scan_discovered_subdomains": true,
"scan_third_party_javascript": true,
"headers": [{"key": "X-API-KEY",
"value": "example"
}
],
"cookies": [{"domain": "example.com",
"expiry": 1734732496,
"httpOnly": false,
"name": "mycookie",
"path": "/webapp",
"sameSite": "Strict",
"secure": false,
"value": "test123"
}
]
}
}
}
}

List Targets

Returns all Targets, newest first.

Authorizations:

ApiKey

query Parameters

page_token	string Results are returned one page at a time: 500 objects by default, or `page_size` when set. When more results remain, the response includes `next_page_token`; pass it as `page_token` to fetch the next page.
page_size	integer [ 1 .. 499 ] Example: page_size=100 Number of objects per page. The default and largest page size is 500; pass a value from 1 to 499 to receive smaller pages. Values outside that range use the default.
filters	string Example: filters={"tags": ["prod"], "label": ["prod-webserver"]} A JSON object, sent as a single URL-encoded string, of filters where each value is an array to filter on. E.g. `{ "tags": ["prod"] }` Allowed keys: `tags`, `label`, `target` (the target address, as returned in the `target` field), and `source_id` (the id of the Source the target belongs to, for example from Create a new Source). Keys that are not allowed are ignored. Values are exact matches; tags are stored in lowercase.
sort	string Example: sort=last_scanned desc Sort order: one or more comma-separated fields, each optionally followed by a space and `desc` for descending order, e.g. `created_at` or `last_scanned desc,created_at`. Allowed fields: `created_at` and `last_scanned`. Fields that are not allowed are ignored. The default order is newest first.

Responses

Response Schema: application/json

required

Array of objects (Target)

Array

id

required

string

target

string

The target's address. For targets imported from a code integration such as GitHub or Snyk this is the repository or project identifier. Absent for auto-imported targets that have no active address, such as a shut-down cloud instance.

label

string

tags

Array of strings

object

The target's current health score, derived from its open risks. Health scores are being rolled out and are currently returned for a limited set of accounts; for other accounts this field is absent. When enabled, it is present only for targets that have been scanned at least once. A scanned target with no open risks returns { "score": 0, "grade": "A" } (zero is best; higher scores indicate more severe risks).

score required	integer <int32> Numeric health score. `0` means no open risks; higher values indicate more severe open risks.
grade required	string Enum: "A" "B" "C" "D" "F" Letter grade derived from the score.

auth_selenium_file

string

Filename of the Selenium .side recording attached to this target for authenticated scanning. Absent when no recording is attached. Upload one with Upload a Selenium login recording.

object (ScannerSettings)

Scanner settings configured on this target. Returned only when the target has any set, and only the settings that are set are included.

object

Settings specific to the ZAP scanner

included_domains

Array of strings <= 20 items

Domains to include in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_domains

Array of strings <= 20 items

Domains to exclude in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_urls

Array of strings <= 20 items

Specific URLS to avoid on the site. Each entry must be an absolute URL with an http:// or https:// scheme

seed_urls

Array of strings <= 20 items

Specific seed URLS to help the crawler discover sections of your website that are hidden or hard to reach. Each entry must be an absolute URL with an http:// or https:// scheme

anti_csrf_tokens

Array of strings <= 30 items [ items <= 100 characters ^[a-zA-Z0-9\-_\[\]]+$ ]

Names of the anti-CSRF tokens used by the site, e.g. ["__RequestVerificationToken", "XSRF-TOKEN", "_csrf"]. These tokens will be automatically handled during scanning. Names may contain letters, numbers, underscores, hyphens, and square brackets

scan_discovered_subdomains

boolean

Default: true

Scan discovered subdomains of the initial target. Defaults to true when not set

scan_third_party_javascript

boolean

Default: true

Check included third party javascript for vulnerabilities. Defaults to true when not set

Array of objects <= 5 items

Custom headers to send with each request. Up to 5 headers

Array (<= 5 items)

key required	string <= 512 characters ^[a-zA-Z0-9\-_]+$ Header name. Letters, numbers, hyphens, and underscores only
value required	string <= 5000 characters Header value. Printable ASCII characters only

Array of objects <= 5 items

Custom cookies to send with each request. Up to 5 cookies

Array (<= 5 items)

domain required	string The host to which the cookie will be sent, as a hostname or IP address without a leading dot, e.g. `example.com`. More details here
expiry	number The date to expire the cookie, in the number of seconds from epoch e.g. 1675098987. Time is UTC.
httpOnly	boolean Default: false Makes the cookie inaccessible to JavaScript on the page. Defaults to `false`. More details here.
name required	string Defines the cookie name. Must be valid ASCII with some exclusions. More details here
path required	string Indicates the path that must exist in the requested URL for the browser to send the Cookie header. More details here.
sameSite	string Enum: "None" "Lax" "Strict" Controls whether or not a cookie is sent with cross-site requests. More details here.
secure	boolean Default: false Send only over https. Defaults to `false`. More details here.
value required	string Any US-ASCII character excluding control characters, whitespace, double quotes, commas, semicolons and backslashes. More details here.

next_page_token

string

Token that is present when there are more results than can fit in the response. Use the token to get the page of results.

Request samples

cURL
With Filters

curl https://api.hostedscan.com/v1/targets \
     -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY"

Response samples

200

Content type

application/json

{"data": [{"id": "111122caac53b5e8c6616e12",
"target": "www.example.com",
"label": "production-website",
"tags": ["prod"
],
"health_score": {"score": 150,
"grade": "A"
},
"auth_selenium_file": "login.side",
"scanner_settings": {"zap": {"included_domains": ["app.example.com"
],
"excluded_domains": ["blog.example.com"
],
"excluded_urls": ["https://example.com/scripts/"
],
"seed_urls": ["https://example.com/unlinked-page"
],
"anti_csrf_tokens": ["XSRF-TOKEN"
],
"scan_discovered_subdomains": true,
"scan_third_party_javascript": true,
"headers": [{"key": "X-API-KEY",
"value": "example"
}
],
"cookies": [{"domain": "example.com",
"expiry": 1734732496,
"httpOnly": false,
"name": "mycookie",
"path": "/webapp",
"sameSite": "Strict",
"secure": false,
"value": "test123"
}
]
}
}
}
],
"next_page_token": "string"
}

Get a Target by id

Returns a single Target

Authorizations:

ApiKey

path Parameters

id

required

string

ID of the Target to get

Responses

Response Schema: application/json

required

object (Target)

The Target object

id

required

string

target

string

The target's address. For targets imported from a code integration such as GitHub or Snyk this is the repository or project identifier. Absent for auto-imported targets that have no active address, such as a shut-down cloud instance.

label

string

tags

Array of strings

object

The target's current health score, derived from its open risks. Health scores are being rolled out and are currently returned for a limited set of accounts; for other accounts this field is absent. When enabled, it is present only for targets that have been scanned at least once. A scanned target with no open risks returns { "score": 0, "grade": "A" } (zero is best; higher scores indicate more severe risks).

score required	integer <int32> Numeric health score. `0` means no open risks; higher values indicate more severe open risks.
grade required	string Enum: "A" "B" "C" "D" "F" Letter grade derived from the score.

auth_selenium_file

string

Filename of the Selenium .side recording attached to this target for authenticated scanning. Absent when no recording is attached. Upload one with Upload a Selenium login recording.

object (ScannerSettings)

Scanner settings configured on this target. Returned only when the target has any set, and only the settings that are set are included.

object

Settings specific to the ZAP scanner

included_domains

Array of strings <= 20 items

Domains to include in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_domains

Array of strings <= 20 items

Domains to exclude in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_urls

Array of strings <= 20 items

Specific URLS to avoid on the site. Each entry must be an absolute URL with an http:// or https:// scheme

seed_urls

Array of strings <= 20 items

Specific seed URLS to help the crawler discover sections of your website that are hidden or hard to reach. Each entry must be an absolute URL with an http:// or https:// scheme

anti_csrf_tokens

Array of strings <= 30 items [ items <= 100 characters ^[a-zA-Z0-9\-_\[\]]+$ ]

Names of the anti-CSRF tokens used by the site, e.g. ["__RequestVerificationToken", "XSRF-TOKEN", "_csrf"]. These tokens will be automatically handled during scanning. Names may contain letters, numbers, underscores, hyphens, and square brackets

scan_discovered_subdomains

boolean

Default: true

Scan discovered subdomains of the initial target. Defaults to true when not set

scan_third_party_javascript

boolean

Default: true

Check included third party javascript for vulnerabilities. Defaults to true when not set

Array of objects <= 5 items

Custom headers to send with each request. Up to 5 headers

Array (<= 5 items)

key required	string <= 512 characters ^[a-zA-Z0-9\-_]+$ Header name. Letters, numbers, hyphens, and underscores only
value required	string <= 5000 characters Header value. Printable ASCII characters only

Array of objects <= 5 items

Custom cookies to send with each request. Up to 5 cookies

Array (<= 5 items)

domain required	string The host to which the cookie will be sent, as a hostname or IP address without a leading dot, e.g. `example.com`. More details here
expiry	number The date to expire the cookie, in the number of seconds from epoch e.g. 1675098987. Time is UTC.
httpOnly	boolean Default: false Makes the cookie inaccessible to JavaScript on the page. Defaults to `false`. More details here.
name required	string Defines the cookie name. Must be valid ASCII with some exclusions. More details here
path required	string Indicates the path that must exist in the requested URL for the browser to send the Cookie header. More details here.
sameSite	string Enum: "None" "Lax" "Strict" Controls whether or not a cookie is sent with cross-site requests. More details here.
secure	boolean Default: false Send only over https. Defaults to `false`. More details here.
value required	string Any US-ASCII character excluding control characters, whitespace, double quotes, commas, semicolons and backslashes. More details here.

Request samples

cURL

curl -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" https://api.hostedscan.com/v1/targets/TARGET_ID

Response samples

200

Content type

application/json

{"data": {"id": "111122caac53b5e8c6616e12",
"target": "www.example.com",
"label": "production-website",
"tags": ["prod"
],
"health_score": {"score": 150,
"grade": "A"
},
"auth_selenium_file": "login.side",
"scanner_settings": {"zap": {"included_domains": ["app.example.com"
],
"excluded_domains": ["blog.example.com"
],
"excluded_urls": ["https://example.com/scripts/"
],
"seed_urls": ["https://example.com/unlinked-page"
],
"anti_csrf_tokens": ["XSRF-TOKEN"
],
"scan_discovered_subdomains": true,
"scan_third_party_javascript": true,
"headers": [{"key": "X-API-KEY",
"value": "example"
}
],
"cookies": [{"domain": "example.com",
"expiry": 1734732496,
"httpOnly": false,
"name": "mycookie",
"path": "/webapp",
"sameSite": "Strict",
"secure": false,
"value": "test123"
}
]
}
}
}
}

Update a Target

Update a Target's label, tags, or scanner settings. The target address cannot be changed. Omitted fields keep their current values.

Within scanner_settings.zap, sending any of the crawl settings (included_domains, excluded_domains, excluded_urls, seed_urls, anti_csrf_tokens, scan_discovered_subdomains, scan_third_party_javascript) replaces all of the crawl settings, so include every crawl setting you want to keep. headers and cookies are each replaced only when sent.

Targets imported from a cloud provider keep the provider's label and tags; changes to those fields are ignored. Targets created from uploaded scan results cannot be updated and return 400.

Authorizations:

ApiKey

path Parameters

id

required

string

ID of the Target to update

Request Body schema: application/json
required

label

string <= 255 characters

Label for the Target

tags

Array of strings <= 10 items [ items <= 255 characters ]

Up to 10 tags for filtering, selecting, and sorting. Tags are stored in lowercase. Send an empty array to remove all tags.

object (ScannerSettings)

The settings to use with a particular scanner when scanning this target.

object

Settings specific to the ZAP scanner

included_domains

Array of strings <= 20 items

Domains to include in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_domains

Array of strings <= 20 items

Domains to exclude in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_urls

Array of strings <= 20 items

Specific URLS to avoid on the site. Each entry must be an absolute URL with an http:// or https:// scheme

seed_urls

Array of strings <= 20 items

Specific seed URLS to help the crawler discover sections of your website that are hidden or hard to reach. Each entry must be an absolute URL with an http:// or https:// scheme

anti_csrf_tokens

Array of strings <= 30 items [ items <= 100 characters ^[a-zA-Z0-9\-_\[\]]+$ ]

Names of the anti-CSRF tokens used by the site, e.g. ["__RequestVerificationToken", "XSRF-TOKEN", "_csrf"]. These tokens will be automatically handled during scanning. Names may contain letters, numbers, underscores, hyphens, and square brackets

scan_discovered_subdomains

boolean

Default: true

Scan discovered subdomains of the initial target. Defaults to true when not set

scan_third_party_javascript

boolean

Default: true

Check included third party javascript for vulnerabilities. Defaults to true when not set

Array of objects <= 5 items

Custom headers to send with each request. Up to 5 headers

Array (<= 5 items)

key required	string <= 512 characters ^[a-zA-Z0-9\-_]+$ Header name. Letters, numbers, hyphens, and underscores only
value required	string <= 5000 characters Header value. Printable ASCII characters only

Array of objects <= 5 items

Custom cookies to send with each request. Up to 5 cookies

Array (<= 5 items)

domain required	string The host to which the cookie will be sent, as a hostname or IP address without a leading dot, e.g. `example.com`. More details here
expiry	number The date to expire the cookie, in the number of seconds from epoch e.g. 1675098987. Time is UTC.
httpOnly	boolean Default: false Makes the cookie inaccessible to JavaScript on the page. Defaults to `false`. More details here.
name required	string Defines the cookie name. Must be valid ASCII with some exclusions. More details here
path required	string Indicates the path that must exist in the requested URL for the browser to send the Cookie header. More details here.
sameSite	string Enum: "None" "Lax" "Strict" Controls whether or not a cookie is sent with cross-site requests. More details here.
secure	boolean Default: false Send only over https. Defaults to `false`. More details here.
value required	string Any US-ASCII character excluding control characters, whitespace, double quotes, commas, semicolons and backslashes. More details here.

Responses

Response Schema: application/json

required

object (Target)

The updated Target object

id

required

string

target

string

The target's address. For targets imported from a code integration such as GitHub or Snyk this is the repository or project identifier. Absent for auto-imported targets that have no active address, such as a shut-down cloud instance.

label

string

tags

Array of strings

object

The target's current health score, derived from its open risks. Health scores are being rolled out and are currently returned for a limited set of accounts; for other accounts this field is absent. When enabled, it is present only for targets that have been scanned at least once. A scanned target with no open risks returns { "score": 0, "grade": "A" } (zero is best; higher scores indicate more severe risks).

score required	integer <int32> Numeric health score. `0` means no open risks; higher values indicate more severe open risks.
grade required	string Enum: "A" "B" "C" "D" "F" Letter grade derived from the score.

auth_selenium_file

string

Filename of the Selenium .side recording attached to this target for authenticated scanning. Absent when no recording is attached. Upload one with Upload a Selenium login recording.

object (ScannerSettings)

Scanner settings configured on this target. Returned only when the target has any set, and only the settings that are set are included.

object

Settings specific to the ZAP scanner

included_domains

Array of strings <= 20 items

Domains to include in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_domains

Array of strings <= 20 items

Domains to exclude in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_urls

Array of strings <= 20 items

Specific URLS to avoid on the site. Each entry must be an absolute URL with an http:// or https:// scheme

seed_urls

Array of strings <= 20 items

Specific seed URLS to help the crawler discover sections of your website that are hidden or hard to reach. Each entry must be an absolute URL with an http:// or https:// scheme

anti_csrf_tokens

Array of strings <= 30 items [ items <= 100 characters ^[a-zA-Z0-9\-_\[\]]+$ ]

Names of the anti-CSRF tokens used by the site, e.g. ["__RequestVerificationToken", "XSRF-TOKEN", "_csrf"]. These tokens will be automatically handled during scanning. Names may contain letters, numbers, underscores, hyphens, and square brackets

scan_discovered_subdomains

boolean

Default: true

Scan discovered subdomains of the initial target. Defaults to true when not set

scan_third_party_javascript

boolean

Default: true

Check included third party javascript for vulnerabilities. Defaults to true when not set

Array of objects <= 5 items

Custom headers to send with each request. Up to 5 headers

Array (<= 5 items)

key required	string <= 512 characters ^[a-zA-Z0-9\-_]+$ Header name. Letters, numbers, hyphens, and underscores only
value required	string <= 5000 characters Header value. Printable ASCII characters only

Array of objects <= 5 items

Custom cookies to send with each request. Up to 5 cookies

Array (<= 5 items)

domain required	string The host to which the cookie will be sent, as a hostname or IP address without a leading dot, e.g. `example.com`. More details here
expiry	number The date to expire the cookie, in the number of seconds from epoch e.g. 1675098987. Time is UTC.
httpOnly	boolean Default: false Makes the cookie inaccessible to JavaScript on the page. Defaults to `false`. More details here.
name required	string Defines the cookie name. Must be valid ASCII with some exclusions. More details here
path required	string Indicates the path that must exist in the requested URL for the browser to send the Cookie header. More details here.
sameSite	string Enum: "None" "Lax" "Strict" Controls whether or not a cookie is sent with cross-site requests. More details here.
secure	boolean Default: false Send only over https. Defaults to `false`. More details here.
value required	string Any US-ASCII character excluding control characters, whitespace, double quotes, commas, semicolons and backslashes. More details here.

Request samples

Payload
cURL

Content type

application/json

{"label": "production-webserver",
"tags": ["prod"
],
"scanner_settings": {"zap": {"included_domains": ["app.example.com"
],
"excluded_domains": ["blog.example.com"
],
"excluded_urls": ["https://example.com/scripts/"
],
"seed_urls": ["https://example.com/unlinked-page"
],
"anti_csrf_tokens": ["XSRF-TOKEN"
],
"scan_discovered_subdomains": true,
"scan_third_party_javascript": true,
"headers": [{"key": "X-API-KEY",
"value": "example"
}
],
"cookies": [{"domain": "example.com",
"expiry": 1734732496,
"httpOnly": false,
"name": "mycookie",
"path": "/webapp",
"sameSite": "Strict",
"secure": false,
"value": "test123"
}
]
}
}
}

Response samples

200

Content type

application/json

{"data": {"id": "111122caac53b5e8c6616e12",
"target": "www.example.com",
"label": "production-website",
"tags": ["prod"
],
"health_score": {"score": 150,
"grade": "A"
},
"auth_selenium_file": "login.side",
"scanner_settings": {"zap": {"included_domains": ["app.example.com"
],
"excluded_domains": ["blog.example.com"
],
"excluded_urls": ["https://example.com/scripts/"
],
"seed_urls": ["https://example.com/unlinked-page"
],
"anti_csrf_tokens": ["XSRF-TOKEN"
],
"scan_discovered_subdomains": true,
"scan_third_party_javascript": true,
"headers": [{"key": "X-API-KEY",
"value": "example"
}
],
"cookies": [{"domain": "example.com",
"expiry": 1734732496,
"httpOnly": false,
"name": "mycookie",
"path": "/webapp",
"sameSite": "Strict",
"secure": false,
"value": "test123"
}
]
}
}
}
}

Delete a Target

Delete a Target by id

Note: Deleting a target will also delete any risks associated with that target and remove it from any Scheduled Scans that select it by id. Scans that already ran against the target are kept.

Only Targets created manually (through this API or the dashboard) or discovered by an Internal Scanner can be deleted here. Targets imported from cloud providers, code integrations, or uploaded scan results are managed by their source and return 400.

Authorizations:

ApiKey

path Parameters

id

required

string

ID of the Target to delete

Responses

Request samples

cURL

curl -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" --request DELETE https://api.hostedscan.com/v1/targets/TARGET_ID

Upload OpenAPI File to Existing Target

Upload an OpenAPI specification file to an existing target for API-based vulnerability scanning.

Authorizations:

ApiKey

path Parameters

id

required

string

ID of the target to upload the OpenAPI file to

Request Body schema: multipart/form-data
required

file

required

string <binary>

OpenAPI specification file in JSON or YAML format.

Supported formats: .json, .yaml, .yml
Maximum size: 5MB
The file is stored as uploaded and its contents are not validated at upload time. Uploading again replaces the previous file.

Responses

Response Schema: application/json

required

object (Target)

The Target object

id

required

string

target

string

The target's address. For targets imported from a code integration such as GitHub or Snyk this is the repository or project identifier. Absent for auto-imported targets that have no active address, such as a shut-down cloud instance.

label

string

tags

Array of strings

object

The target's current health score, derived from its open risks. Health scores are being rolled out and are currently returned for a limited set of accounts; for other accounts this field is absent. When enabled, it is present only for targets that have been scanned at least once. A scanned target with no open risks returns { "score": 0, "grade": "A" } (zero is best; higher scores indicate more severe risks).

score required	integer <int32> Numeric health score. `0` means no open risks; higher values indicate more severe open risks.
grade required	string Enum: "A" "B" "C" "D" "F" Letter grade derived from the score.

auth_selenium_file

string

Filename of the Selenium .side recording attached to this target for authenticated scanning. Absent when no recording is attached. Upload one with Upload a Selenium login recording.

object (ScannerSettings)

Scanner settings configured on this target. Returned only when the target has any set, and only the settings that are set are included.

object

Settings specific to the ZAP scanner

included_domains

Array of strings <= 20 items

Domains to include in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_domains

Array of strings <= 20 items

Domains to exclude in ZAP crawl. Each entry must be a Fully Qualified Domain Name

excluded_urls

Array of strings <= 20 items

Specific URLS to avoid on the site. Each entry must be an absolute URL with an http:// or https:// scheme

seed_urls

Array of strings <= 20 items

Specific seed URLS to help the crawler discover sections of your website that are hidden or hard to reach. Each entry must be an absolute URL with an http:// or https:// scheme

anti_csrf_tokens

Array of strings <= 30 items [ items <= 100 characters ^[a-zA-Z0-9\-_\[\]]+$ ]

Names of the anti-CSRF tokens used by the site, e.g. ["__RequestVerificationToken", "XSRF-TOKEN", "_csrf"]. These tokens will be automatically handled during scanning. Names may contain letters, numbers, underscores, hyphens, and square brackets

scan_discovered_subdomains

boolean

Default: true

Scan discovered subdomains of the initial target. Defaults to true when not set

scan_third_party_javascript

boolean

Default: true

Check included third party javascript for vulnerabilities. Defaults to true when not set

Array of objects <= 5 items

Custom headers to send with each request. Up to 5 headers

Array (<= 5 items)

key required	string <= 512 characters ^[a-zA-Z0-9\-_]+$ Header name. Letters, numbers, hyphens, and underscores only
value required	string <= 5000 characters Header value. Printable ASCII characters only

Array of objects <= 5 items

Custom cookies to send with each request. Up to 5 cookies

Array (<= 5 items)

domain required	string The host to which the cookie will be sent, as a hostname or IP address without a leading dot, e.g. `example.com`. More details here
expiry	number The date to expire the cookie, in the number of seconds from epoch e.g. 1675098987. Time is UTC.
httpOnly	boolean Default: false Makes the cookie inaccessible to JavaScript on the page. Defaults to `false`. More details here.
name required	string Defines the cookie name. Must be valid ASCII with some exclusions. More details here
path required	string Indicates the path that must exist in the requested URL for the browser to send the Cookie header. More details here.
sameSite	string Enum: "None" "Lax" "Strict" Controls whether or not a cookie is sent with cross-site requests. More details here.
secure	boolean Default: false Send only over https. Defaults to `false`. More details here.
value required	string Any US-ASCII character excluding control characters, whitespace, double quotes, commas, semicolons and backslashes. More details here.

Request samples

Complete workflow: Create target + Upload OpenAPI file
Upload to existing target

# Step 1: Create target with authentication headers
TARGET_RESPONSE=$(curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" \
  -d '{
    "target": "https://api.example.com",
    "label": "My API Service",
    "scanner_settings": {
      "zap": {
        "headers": [
          {
            "key": "Authorization",
            "value": "Bearer your-api-token"
          }
        ]
      }
    }
  }' \
  https://api.hostedscan.com/v1/targets)
# Extract target ID
TARGET_ID=$(echo $TARGET_RESPONSE | jq -r '.data.id')
# Step 2: Upload OpenAPI file to the target
curl -X POST \
  -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" \
  -F "file=@openapi.yaml" \
  https://api.hostedscan.com/v1/targets/$TARGET_ID/openapi

Response samples

200
400

Content type

application/json

{"data": {"id": "111122caac53b5e8c6616e12",
"target": "www.example.com",
"label": "production-website",
"tags": ["prod"
],
"health_score": {"score": 150,
"grade": "A"
},
"auth_selenium_file": "login.side",
"scanner_settings": {"zap": {"included_domains": ["app.example.com"
],
"excluded_domains": ["blog.example.com"
],
"excluded_urls": ["https://example.com/scripts/"
],
"seed_urls": ["https://example.com/unlinked-page"
],
"anti_csrf_tokens": ["XSRF-TOKEN"
],
"scan_discovered_subdomains": true,
"scan_third_party_javascript": true,
"headers": [{"key": "X-API-KEY",
"value": "example"
}
],
"cookies": [{"domain": "example.com",
"expiry": 1734732496,
"httpOnly": false,
"name": "mycookie",
"path": "/webapp",
"sameSite": "Strict",
"secure": false,
"value": "test123"
}
]
}
}
}
}

Reports

Generate PDF, HTML, and CSV reports.

Create a new Report

Create a new Report. The report is generated before the response is returned, so the request can take several seconds, and PDF reports can take up to minutes depending on size. Download the finished report with Download a Report.

CSV reports require CSV export to be enabled on your account; otherwise the request fails with 403.

Authorizations:

ApiKey

Request Body schema: application/json
required

report_format

required

string

Enum: "PDF" "HTML" "CSV"

PDF, HTML, or CSV

object

Target ids, tags, or labels. { "target_ids": ["target-123"] }, { "tags": ["example-tag"] }, or { "label": ["production website"] }. Keys that are not allowed are ignored.

target_ids	Array of strings
tags	Array of strings
label	Array of strings

risks_filter

object

Key value pairs of filters, where each value is an array to filter on. E.g.

{"risk_definition.scan_type": ["NMAP", "NMAP_UDP"]}

Allowed keys: risk_definition_id, risk_definition.scan_type, risk_definition.threat_level, status, and risk_definition.title (deprecated — use risk_definition_id instead). Keys that are not allowed are ignored.

status accepts OPEN, ACCEPTED, and CLOSED. Unlike the Risks API, reports treat accepted risks as a separate ACCEPTED status.

Responses

Response Schema: application/json

required

object

id

required

string <uuid>

Unique identifier for the generated report

Request samples

Payload
Basic report
HTML report
Filtered report

Content type

application/json

{"report_format": "PDF",
"targets_filter": {"target_ids": ["string"
],
"tags": ["string"
],
"label": ["string"
]
},
"risks_filter": { }
}

Response samples

200
400
403

Content type

application/json

{"data": {"id": "a3a10e1a-4555-46dc-8da5-ada055c9fcfd"
}
}

Download a Report

Authorizations:

ApiKey

path Parameters

id

required

string

ID of the Report to get

query Parameters

filename	string Optional filename to use in the `Content-Disposition` download header. The server will sanitize the filename and ensure the extension matches the report format.
format	string Enum: "PDF" "HTML" "CSV" Format of the report to download; pass the `report_format` the report was created with. Defaults to `PDF` when omitted or unrecognized, and is required to download an `HTML` report. Case-insensitive.

Responses

Response Schema:
application/pdf

string <binary>

Request samples

PDF report (default)
HTML report

curl --header "X-HOSTEDSCAN-API-KEY: your-api-key-here" \
--output report.pdf \
https://api.hostedscan.com/v1/reports/id-of-created-report-here

Upload Results From Your Own Scanners

HostedScan is compatible with the top open-source scanning tools in the world. If you run these scanners yourself, you can upload their output to HostedScan to use dashboards and reports.

The API endpoints in this section are POST /v1/sources (create an IMPORTED source) and POST /v1/results (upload a scan file). The walkthrough below covers Nmap, OpenVAS, and ZAP end to end.

Steps to run vulnerability scans and upload the results

1. Create a HostedScan API key

Navigate to https://hostedscan.com/settings/api and generate an API key.

HostedScan API key

2. Create a new Source in your HostedScan account

HostedScan uses Sources to group related targets and vulnerability scan results. This keeps results from one network separate from others.

Create a source with source_type IMPORTED:

curl -H "Content-Type: application/json" \
     -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" \
     --request POST \
     --data '{"source_type":"IMPORTED", "name":"My Network"}' \
     https://api.hostedscan.com/v1/sources

curl.exe -H "Content-Type: application/json" `
       -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" `
       --request POST `
       --data '{\"source_type\":\"IMPORTED\", \"name\":\"My Network\"}' `
       https://api.hostedscan.com/v1/sources

Note the id in the JSON response — you will use it as source_id when uploading results.

{"data":{"id":"64c94d38714823ae20c1a9bc","source_type":"IMPORTED","name":"My Network"}}

You will also see the new Source in your account at https://hostedscan.com/targets.

A new Source for the internal network

3. Run your first scan — Nmap port scan

Note: Nmap is the most widely used port scanner in the world. Learn more about Nmap.

Nmap is available via most Linux package managers, Homebrew on macOS, and the Windows installer.

Example: scan private addresses 10.0.0.0–10.0.0.15 and write XML:

nmap -v -oX scan.xml 10.0.0.0/28

nmap -v -oX scan.xml 10.0.0.0/28

Example Nmap output (truncated):

Starting Nmap 7.94 ( https://nmap.org ) at 2023-08-01 11:54 PDT
...
Nmap scan report for 10.0.0.1
Host is up (0.010s latency).
PORT      STATE    SERVICE
53/tcp    open     domain
80/tcp    open     http
443/tcp   open     https
...

Upload the XML to HostedScan (scan_type NMAP):

curl \
  -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" \
  -F scan_type=NMAP \
  -F source_id=SOURCE_ID \
  -F file=@scan.xml \
  https://api.hostedscan.com/v1/results

curl.exe `
  -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" `
  -F "scan_type=NMAP" `
  -F "source_id=SOURCE_ID" `
  -F "file=@scan.xml" `
  https://api.hostedscan.com/v1/results

After processing, the scan appears in the HostedScan UI.

The scan in the HostedScan UI

Open port findings

4. Run the OpenVAS network vulnerability scan

OpenVAS (via Greenbone Community Edition) is a network vulnerability scanner. Use the GCE UI (often http://localhost:9392). See Greenbone scanning documentation.

Greenbone task wizard screen

When the scan finishes, save the Anonymous XML report. Short demo:

Upload the saved XML (scan_type OPENVAS):

curl \
  -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" \
  -F scan_type=OPENVAS \
  -F source_id=SOURCE_ID \
  -F file=@openvas-scan.xml \
  https://api.hostedscan.com/v1/results

curl.exe `
  -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" `
  -F "scan_type=OPENVAS" `
  -F "source_id=SOURCE_ID" `
  -F "file=@openvas-scan.xml" `
  https://api.hostedscan.com/v1/results

OpenVAS vulnerability findings

5. Run the ZAP web application scan

OWASP ZAP is a popular web app scanner (desktop, APIs, Docker). For HostedScan, export the Traditional JSON report. ZAP report generation.

ZAP report generation

Upload the JSON. target is required for ZAP uploads (the URL that was scanned):

curl \
  -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" \
  -F scan_type=OWASP_ZAP \
  -F source_id=SOURCE_ID \
  -F target="https://example.com" \
  -F file=@zap-scan.json \
  https://api.hostedscan.com/v1/results

curl.exe `
  -H "X-HOSTEDSCAN-API-KEY: YOUR_API_KEY" `
  -F "scan_type=OWASP_ZAP" `
  -F "source_id=SOURCE_ID" `
  -F "target=https://example.com" `
  -F "file=@zap-scan.json" `
  https://api.hostedscan.com/v1/results

Create a new Source

Create a Source used to group imported scan results. For BYO scanner uploads, use source_type IMPORTED and a human-readable name.

The response includes data.id — use that value as source_id on POST /v1/results.

Full walkthrough (curl, Nmap/OpenVAS/ZAP, screenshots): see the Upload Results From Your Own Scanners tag description.

Authorizations:

ApiKey

Request Body schema: application/json
required

source_type required	string Value: "IMPORTED"
name required	string A name for the Source

Responses

Response Schema: application/json

required

object

id required	string
source_type required	string Value: "IMPORTED"
name required	string

Request samples

Payload

Content type

application/json

{"source_type": "IMPORTED",
"name": "HQ Internal Network"
}

Response samples

200

Content type

application/json

{"data": {"id": "39391122caac7655e8c6616987",
"source_type": "IMPORTED",
"name": "HQ Internal Network"
}
}

Upload a Scan Result

Upload a scanner output file for an IMPORTED source. The request must be multipart/form-data with exactly one file part (field name file, max size 25 MB on the server).

Form fields

source_id (required): IMPORTED source id from POST /v1/sources.
scan_type (required): NMAP, NMAP_UDP, OPENVAS, OWASP_ZAP, or OWASP_ZAP_ACTIVE. Other scan types are not supported for uploads and return 400.
target (required for ZAP): e.g. https://example.com. Omitted for NMAP / OPENVAS — targets are inferred from the file.
file (required): Scanner output. Expected formats:
- NMAP: XML (-oX)
- OPENVAS: Greenbone Anonymous XML report
- OWASP_ZAP / OWASP_ZAP_ACTIVE: Traditional JSON export

Step-by-step examples: Upload Results From Your Own Scanners.

Authorizations:

ApiKey

Request Body schema: multipart/form-data
required

source_id required	string Id of the Source that this result will be grouped with
scan_type required	string Enum: "NMAP" "NMAP_UDP" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" The scanner that produced the file. Only these values are supported for uploads.
target	string The target that was scanned. e.g. https://example.com. Required only for the `OWASP_ZAP` and `OWASP_ZAP_ACTIVE` scan_types. For other scanners, such as `NMAP` and `OPENVAS` the targets will be automatically inferred.
file required	string <binary> Scanner output file (XML for Nmap/OpenVAS, Traditional JSON for ZAP). Exactly one file must be uploaded.

Responses

Response samples

400

Content type

application/json

{"error": "Target already exists: www.example.com",
"ref": "string"
}

Webhooks Overview

HostedScan uses webhooks to send event notifications to your application. Receive events when scans finish or when new risks are discovered.

Base Event Object

The webhook notifications sent by HostedScan are Event objects. An Event is a JSON structure with the following properties: the event id, the event_created_at time, the event type, and the data. The data is specific for each event. E.g. for a risk.created event the data is the Risk object and for a scan.created event the data is the Scan object.

{
  "id": "12345",
  "event_created_at": "2023-08-11T05:52:56.104Z",
  "type": "risk.created",
  "data": {
    ...
  }
}

Registering an Endpoint

Your webhook endpoint must use HTTPS with a signed certificate, such as one from https://letsencrypt.org/. HostedScan will not send to endpoints using self-signed certificates.

You can register new webhook endpoints and view your existing webhook endpoints in your account settings at https://hostedscan.com/settings. Webhook endpoints are managed in the dashboard only; there is no API for creating or listing them.

Registering a Webhook Endpoint with HostedScan

Message Delivery and Retries

Any 2xx response code from your endpoint is treated as a successful delivery. Any non-2xx status code, or no response within 5 seconds, is treated as a failure and will be retried. HostedScan makes up to 10 delivery attempts per event. The wait before each retry grows by 5 minutes, starting at about 10 seconds, so the attempts are spread over roughly 3 hours. Delivery is at-least-once: an event can occasionally be delivered more than once, so use the event id to de-duplicate.

Securing Your Webhooks

When you register an endpoint, HostedScan creates a signing secret for that endpoint. HostedScan uses this secret to send a signature in the header of each Event message. The signature can be validated using the signing secret to verify that an event was sent by HostedScan.

Validating the Webhook Signature

Each webhook message request includes an http header X-HOSTEDSCAN-SIGNATURE. The X-HOSTEDSCAN-SIGNATURE is a hash-based message authentication code (HMAC) generated with SHA-256. To validate this signature an application will first recreate the signature using the signing secret for that endpoint and then check that the signature sent in the X-HOSTEDSCAN-SIGNATURE header matches the recreated signature. To do this, follow the steps below:

Prepare the data to be signed. The data is: the message timestamp (sent in the X-HOSTEDSCAN-TIMESTAMP header, as milliseconds since the Unix epoch), the character . , and the raw JSON payload sent in the request body, exactly as received.
Compute the expected signature. HMAC with SHA256, using the endpoint's signing secret as the key, encoded as lowercase hexadecimal.
Compare the signature your application computed to ensure it matches the value sent in the X-HOSTEDSCAN-SIGNATURE header.

Sample Code

The hostedscan-api-examples Github repository has sample code for receiving webhooks with an AWS Lambda function.

Deprecated Events

The API has deprecated a couple of events you will see at your webhook endpoint. Our policy is to generally preserve API behavior to prevent unnecessary rework. The following events have been deprecated:

scan.succeeded
risk.opened
risk.closed

Our recommendation is to ignore these. Instead, the API uses created and updated events to denote changes to scans and risks.

Scan Events

Scan Created Webhook

A new Scan has been created

Request Body schema: application/json
required

id

required

string

Unique id of the event. The same event delivered to several endpoints, or redelivered after a failure, has the same id.

event_created_at

required

string <date-time>

created_at

integer

Deprecated

The event creation time as milliseconds since the Unix epoch. Deprecated, use event_created_at.

type

required

string

Value: "scan.created"

required

object

id

required

string

Scan's ID

type

required

string (ScanType)

Enum: "DEPENDABOT" "DOMAIN_TAKEOVER" "NESSUS" "NESSUS_AGENT" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SNYK" "SSLYZE"

The scanner or integration that produced a Scan or Risk. DEPENDABOT, DOMAIN_TAKEOVER, NESSUS_AGENT, and SNYK come from integrations and cannot be started with the API; see RunnableScanType for the scan types you can run.

state

required

string (State)

Enum: "FAILED" "OVER_LIMIT" "QUEUED" "RUNNING" "STOPPING" "STOPPED" "SUCCEEDED"

State of a Scan. OVER_LIMIT means the scan did not run because the account exceeded its plan limits. FAILED means the scan could not be completed after retries, for example because none of the targets could be resolved; contact us if a scan fails unexpectedly.

progress

required

number

From 0 to 100. Starts at 0 and is 100 once the scan has SUCCEEDED. Some scan types do not report intermediate progress and go straight from 0 to 100.

is_authenticated

boolean

Whether the scan was set up to authenticate to its targets. Present only for these scan types:

OWASP_ZAP and OWASP_ZAP_ACTIVE: true when authentication was enabled (the default) and at least one target had a recorded login attached when the scan was created; absent otherwise. The login is replayed before each such target is scanned, and a target whose login fails is skipped with skipped_reason "Authentication Failed" while the rest of the scan continues, so check skipped_targets for login failures.
OPENVAS run by the Internal Scanner: true when credentials were configured for at least one target, false otherwise.
NESSUS_AGENT (Tenable agents): always true, because the agent runs on the host it scans.

object

The Risks for this Scan. HostedScan maps the findings from different scanners into a common Risk structure. Available once the scan has a SUCCEEDED state. Absent for scans that end in any other state.

Array of objects

New Risks that this Scan found

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

Array of objects

Risks that a previous Scan of the Target found and were still found by this Scan, including risks that had been closed and were detected again

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

Array of objects

Risks that a previous Scan of the Target found and were no longer found by this Scan

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

required

Array of objects

The full Result files from the Scan. These are the native outputs from the scanner. The structure may change when scanners are updated major versions and each scanner may only support some of the content types. Empty until the scan has a SUCCEEDED state.

Array

result_id	string
content_type	string Enum: "text/html" "application/pdf" "application/xml" "application/json"

required

Array of objects

Array

target_id	string Target's ID
target	string Target URL, FQDN, IP. Absent when the target has no active address

required

Array of objects

Array

target_id	string Target's ID
resolved_target	string Resolved target URL (after redirects or conversion of raw form e.g. `hostedscan.com` -> `https://hostedscan.com/`)

required

Array of objects

Array

target_id	string Target's ID
skipped_reason	string

created_at

required

string <date-time>

When the Scan was created

scheduled_by

string

Id of the Scheduled Scan that started this Scan. Absent for Scans started directly.

report_id

string <uuid>

Id of the report generated for this Scan, for use with Download a Report. Set shortly after the Scan reaches the SUCCEEDED state; absent before then and for Scans that did not produce results.

Responses

Request samples

Payload

Content type

application/json

{"id": "evt_64fa7e5b3b3c1f27e3d92f50",
"event_created_at": "2019-08-24T14:15:22Z",
"created_at": 1691733176104,
"type": "scan.created",
"data": {"id": "123422caac53b5e8c6616123",
"type": "NMAP",
"state": "RUNNING",
"progress": 57,
"is_authenticated": true,
"risks": {"new_open": [{"risk_id": "5432122caac53b5e8c6616123"
}
],
"still_open": [{"risk_id": "13131122caac53b5e8c6616123"
}
],
"closed": [{"risk_id": "232321122caac53b5e8c6616123"
}
]
},
"results": [{"result_id": "14141122caac53b5e8c6616123",
"content_type": "application/json"
}
],
"requested_targets": [{"target_id": "36361122caac53b5e8c6616987",
"target": "hostedscan.com"
}
],
"resolved_targets": [{"target_id": "36361122caac53b5e8c6616987",
"resolved_target": "https://hostedscan.com/"
}
],
"skipped_targets": [{"target_id": "17171122caac53b5e8c6616987",
"skipped_reason": "OWASP ZAP scans websites. Unable to GET a website at the target. By default ZAP checks port 80 and 443. Scan an alternative port by setting it on the target url \"www.example.com:1234\""
}
],
"created_at": "2025-10-27T03:00:00Z",
"scheduled_by": "64fa7e5b3b3c1f27e3d92f50",
"report_id": "a3a10e1a-4555-46dc-8da5-ada055c9fcfd"
}
}

Scan Updated Webhook

A Scan has been updated. Sent for every change to the Scan, including progress updates while it runs, so expect several events per Scan. Check data.state to detect completion.

Request Body schema: application/json
required

id

required

string

Unique id of the event. The same event delivered to several endpoints, or redelivered after a failure, has the same id.

event_created_at

required

string <date-time>

created_at

integer

Deprecated

The event creation time as milliseconds since the Unix epoch. Deprecated, use event_created_at.

type

required

string

Value: "scan.updated"

required

object

id

required

string

Scan's ID

type

required

string (ScanType)

Enum: "DEPENDABOT" "DOMAIN_TAKEOVER" "NESSUS" "NESSUS_AGENT" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SNYK" "SSLYZE"

The scanner or integration that produced a Scan or Risk. DEPENDABOT, DOMAIN_TAKEOVER, NESSUS_AGENT, and SNYK come from integrations and cannot be started with the API; see RunnableScanType for the scan types you can run.

state

required

string (State)

Enum: "FAILED" "OVER_LIMIT" "QUEUED" "RUNNING" "STOPPING" "STOPPED" "SUCCEEDED"

State of a Scan. OVER_LIMIT means the scan did not run because the account exceeded its plan limits. FAILED means the scan could not be completed after retries, for example because none of the targets could be resolved; contact us if a scan fails unexpectedly.

progress

required

number

From 0 to 100. Starts at 0 and is 100 once the scan has SUCCEEDED. Some scan types do not report intermediate progress and go straight from 0 to 100.

is_authenticated

boolean

Whether the scan was set up to authenticate to its targets. Present only for these scan types:

OWASP_ZAP and OWASP_ZAP_ACTIVE: true when authentication was enabled (the default) and at least one target had a recorded login attached when the scan was created; absent otherwise. The login is replayed before each such target is scanned, and a target whose login fails is skipped with skipped_reason "Authentication Failed" while the rest of the scan continues, so check skipped_targets for login failures.
OPENVAS run by the Internal Scanner: true when credentials were configured for at least one target, false otherwise.
NESSUS_AGENT (Tenable agents): always true, because the agent runs on the host it scans.

object

The Risks for this Scan. HostedScan maps the findings from different scanners into a common Risk structure. Available once the scan has a SUCCEEDED state. Absent for scans that end in any other state.

Array of objects

New Risks that this Scan found

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

Array of objects

Risks that a previous Scan of the Target found and were still found by this Scan, including risks that had been closed and were detected again

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

Array of objects

Risks that a previous Scan of the Target found and were no longer found by this Scan

Array

risk_id

string

id of the Risk. Lookup of the full content by making a GET request to /risks/{id}

required

Array of objects

The full Result files from the Scan. These are the native outputs from the scanner. The structure may change when scanners are updated major versions and each scanner may only support some of the content types. Empty until the scan has a SUCCEEDED state.

Array

result_id	string
content_type	string Enum: "text/html" "application/pdf" "application/xml" "application/json"

required

Array of objects

Array

target_id	string Target's ID
target	string Target URL, FQDN, IP. Absent when the target has no active address

required

Array of objects

Array

target_id	string Target's ID
resolved_target	string Resolved target URL (after redirects or conversion of raw form e.g. `hostedscan.com` -> `https://hostedscan.com/`)

required

Array of objects

Array

target_id	string Target's ID
skipped_reason	string

created_at

required

string <date-time>

When the Scan was created

scheduled_by

string

Id of the Scheduled Scan that started this Scan. Absent for Scans started directly.

report_id

string <uuid>

Id of the report generated for this Scan, for use with Download a Report. Set shortly after the Scan reaches the SUCCEEDED state; absent before then and for Scans that did not produce results.

Responses

Request samples

Payload

Content type

application/json

{"id": "evt_64fa7e5b3b3c1f27e3d92f50",
"event_created_at": "2019-08-24T14:15:22Z",
"created_at": 1691733176104,
"type": "scan.updated",
"data": {"id": "123422caac53b5e8c6616123",
"type": "NMAP",
"state": "RUNNING",
"progress": 57,
"is_authenticated": true,
"risks": {"new_open": [{"risk_id": "5432122caac53b5e8c6616123"
}
],
"still_open": [{"risk_id": "13131122caac53b5e8c6616123"
}
],
"closed": [{"risk_id": "232321122caac53b5e8c6616123"
}
]
},
"results": [{"result_id": "14141122caac53b5e8c6616123",
"content_type": "application/json"
}
],
"requested_targets": [{"target_id": "36361122caac53b5e8c6616987",
"target": "hostedscan.com"
}
],
"resolved_targets": [{"target_id": "36361122caac53b5e8c6616987",
"resolved_target": "https://hostedscan.com/"
}
],
"skipped_targets": [{"target_id": "17171122caac53b5e8c6616987",
"skipped_reason": "OWASP ZAP scans websites. Unable to GET a website at the target. By default ZAP checks port 80 and 443. Scan an alternative port by setting it on the target url \"www.example.com:1234\""
}
],
"created_at": "2025-10-27T03:00:00Z",
"scheduled_by": "64fa7e5b3b3c1f27e3d92f50",
"report_id": "a3a10e1a-4555-46dc-8da5-ada055c9fcfd"
}
}

Risk Events

Risk Created Webhook

A new Risk has been created

Request Body schema: application/json
required

id

required

string

Unique id of the event. The same event delivered to several endpoints, or redelivered after a failure, has the same id.

event_created_at

required

string <date-time>

created_at

integer

Deprecated

The event creation time as milliseconds since the Unix epoch. Deprecated, use event_created_at.

type

required

string

Value: "risk.created"

required

object

id

required

string

target_id

required

string

target

string

The target's address, the same value as the target field of the Target. Absent when the target has no active address.

target_label

string

tags

Array of strings

status

required

string

Enum: "OPEN" "CLOSED"

CLOSED once a later scan of the same target no longer detects the risk. Accepted risks keep the OPEN status; see is_accepted.

first_detected_at

required

string <date-time>

When the risk was first detected on this target. Does not change when the risk closes and is detected again later.

last_detected_at

required

string <date-time>

When a scan most recently detected the risk. Not updated when the risk is closed.

is_accepted

required

boolean

true when at least one accepted risk rule in the account matches this risk, in which case accepted_by lists the matching rules.

required

Array of objects

The accepted risk rules that match this risk. Empty when the risk is not accepted.

Array

note	string
created_at required	string <date-time>
last_updated_at required	string <date-time>

required

object

scan_type required	string (ScanType) Enum: "DEPENDABOT" "DOMAIN_TAKEOVER" "NESSUS" "NESSUS_AGENT" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SNYK" "SSLYZE" The scanner or integration that produced a Scan or Risk. `DEPENDABOT`, `DOMAIN_TAKEOVER`, `NESSUS_AGENT`, and `SNYK` come from integrations and cannot be started with the API; see `RunnableScanType` for the scan types you can run.
title required	string
threat_level required	string (ThreatLevel) Enum: "LOW" "MEDIUM" "HIGH" "CRITICAL"
description	string May not be available for all scanners
solution	string May not be available for all scanners
references	Array of strings May not be available for all scanners
cvss	string or null CVSS base score as a string, e.g. `7.5`. May not be available for all scanners, and may be `null` for some integrations.
additional_info	object Scanner specific details for this risk: the scanner's description of the finding merged with the details from the most recent detection, such as the port, URL, or evidence. The keys are scanner specific and could change when scanners are updated to new major versions. Web application findings can include the request and response data the scanner captured.

Responses

Request samples

Payload

Content type

application/json

{"id": "evt_64fa7e5b3b3c1f27e3d92f50",
"event_created_at": "2019-08-24T14:15:22Z",
"created_at": 1691733176104,
"type": "risk.created",
"data": {"id": "111122caac53b5e8c6616123",
"target_id": "211122caac53b5e8c6616321",
"target": "www.example.com",
"target_label": "production-website",
"tags": ["prod"
],
"status": "OPEN",
"first_detected_at": "2019-08-24T14:15:22Z",
"last_detected_at": "2019-08-24T14:15:22Z",
"is_accepted": true,
"accepted_by": [{"note": "Expected behavior for production webserver to have ports 80 and 443 open",
"created_at": "2019-08-24T14:15:22Z",
"last_updated_at": "2019-08-24T14:15:22Z"
}
],
"risk_definition": {"scan_type": "NMAP",
"title": "Port 443 Open",
"threat_level": "MEDIUM",
"description": "Port 443 was detected open.",
"solution": "Close the port or restrict access to it with a firewall.",
"references": ["https://owasp.org/www-project-web-security-testing-guide/v41/4-Web_Application_Security_Testing/01-Information_Gathering/04-Enumerate_Applications_on_Webserver"
],
"cvss": "7.5",
"additional_info": { }
}
}
}

Risk Updated Webhook

A Risk has been updated

Request Body schema: application/json
required

id

required

string

Unique id of the event. The same event delivered to several endpoints, or redelivered after a failure, has the same id.

event_created_at

required

string <date-time>

created_at

integer

Deprecated

The event creation time as milliseconds since the Unix epoch. Deprecated, use event_created_at.

type

required

string

Value: "risk.updated"

required

object

id

required

string

target_id

required

string

target

string

The target's address, the same value as the target field of the Target. Absent when the target has no active address.

target_label

string

tags

Array of strings

status

required

string

Enum: "OPEN" "CLOSED"

CLOSED once a later scan of the same target no longer detects the risk. Accepted risks keep the OPEN status; see is_accepted.

first_detected_at

required

string <date-time>

When the risk was first detected on this target. Does not change when the risk closes and is detected again later.

last_detected_at

required

string <date-time>

When a scan most recently detected the risk. Not updated when the risk is closed.

is_accepted

required

boolean

true when at least one accepted risk rule in the account matches this risk, in which case accepted_by lists the matching rules.

required

Array of objects

The accepted risk rules that match this risk. Empty when the risk is not accepted.

Array

note	string
created_at required	string <date-time>
last_updated_at required	string <date-time>

required

object

scan_type required	string (ScanType) Enum: "DEPENDABOT" "DOMAIN_TAKEOVER" "NESSUS" "NESSUS_AGENT" "NMAP" "NMAP_UDP" "NUCLEI" "OPENVAS" "OWASP_ZAP" "OWASP_ZAP_ACTIVE" "SNYK" "SSLYZE" The scanner or integration that produced a Scan or Risk. `DEPENDABOT`, `DOMAIN_TAKEOVER`, `NESSUS_AGENT`, and `SNYK` come from integrations and cannot be started with the API; see `RunnableScanType` for the scan types you can run.
title required	string
threat_level required	string (ThreatLevel) Enum: "LOW" "MEDIUM" "HIGH" "CRITICAL"
description	string May not be available for all scanners
solution	string May not be available for all scanners
references	Array of strings May not be available for all scanners
cvss	string or null CVSS base score as a string, e.g. `7.5`. May not be available for all scanners, and may be `null` for some integrations.
additional_info	object Scanner specific details for this risk: the scanner's description of the finding merged with the details from the most recent detection, such as the port, URL, or evidence. The keys are scanner specific and could change when scanners are updated to new major versions. Web application findings can include the request and response data the scanner captured.

Responses

Request samples

Payload

Content type

application/json

{"id": "evt_64fa7e5b3b3c1f27e3d92f50",
"event_created_at": "2019-08-24T14:15:22Z",
"created_at": 1691733176104,
"type": "risk.updated",
"data": {"id": "111122caac53b5e8c6616123",
"target_id": "211122caac53b5e8c6616321",
"target": "www.example.com",
"target_label": "production-website",
"tags": ["prod"
],
"status": "OPEN",
"first_detected_at": "2019-08-24T14:15:22Z",
"last_detected_at": "2019-08-24T14:15:22Z",
"is_accepted": true,
"accepted_by": [{"note": "Expected behavior for production webserver to have ports 80 and 443 open",
"created_at": "2019-08-24T14:15:22Z",
"last_updated_at": "2019-08-24T14:15:22Z"
}
],
"risk_definition": {"scan_type": "NMAP",
"title": "Port 443 Open",
"threat_level": "MEDIUM",
"description": "Port 443 was detected open.",
"solution": "Close the port or restrict access to it with a firewall.",
"references": ["https://owasp.org/www-project-web-security-testing-guide/v41/4-Web_Application_Security_Testing/01-Information_Gathering/04-Enumerate_Applications_on_Webserver"
],
"cvss": "7.5",
"additional_info": { }
}
}
}

Sample Code

Sample code can be found on Github at https://github.com/hostedscan/hostedscan-api-examples

HostedScan API (V1)

Getting Started

Support

API Overview

Authentication

HTTP Responses

SDKs and Tools

AI Agents

Testing with Postman

Deprecation Policy

Scans

Scan lifecycle

Scan output

Risks (vulnerabilities)

Scanner output files

Reports

Start a new Scan

Authorizations:

Request Body schema: application/jsonrequired

Responses

Response Schema: application/json

Request samples

Response samples

List Scans

Authorizations:

query Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Get a Scan by id

Authorizations:

path Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Delete a Scan

Authorizations:

path Parameters

Responses

Request samples

Stop a running Scan

Authorizations:

path Parameters

Responses

Response Schema: application/json

Request samples

Response samples

Get a Scan Result File by id

Authorizations:

path Parameters

Responses

Request samples

Scheduled Scans

Create a scheduled scan

Authorizations:

Request Body schema: application/jsonrequired

Responses

Response Schema: application/json

Request samples

Response samples

List all Scheduled Scans

Authorizations:

query Parameters

Responses

Response Schema: application/json

Response samples

Get a Scheduled Scan

Authorizations:

path Parameters

Responses

Response Schema: application/json

Response samples

Delete a Scheduled Scan

Authorizations:

path Parameters

Responses

Request samples

Update a Scheduled Scan

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: multipart/form-data
required

Request Body schema: application/json
required

Request Body schema: application/json
required