Skip to main content

Introduction

Welcome to the Scanning Solution REST API. This API enables you to interact programmatically with our platform, allowing you to manage your scans, and access results directly from your applications.

The API follows standard REST principles, where resources are represented as URLs and accessed using HTTP verbs.

Our API accepts JSON-encoded requests and returns JSON-encoded responses.

Quickstart Guide​

This quickstart will guide you through a common use case for interacting with our API: Authentication, Creating a Target, and Running a Scan.

Let's walk through each step.

Step 1: Access the API​

You can access the API at https://api.your-instance.com/v2/. For the complete list of endpoints, please refer to the REST API Reference.

info

All the endpoints in the API require the API key to be passed in the X-API-KEY header.

Step 2: Authentication​

To authenticate, you can use either JWT Token or Basic Authorization. Each has its advantages, depending on your usage.

Option 1: Authenticate with JWT Token​

To authenticate with JWT Token, you need to obtain a token by sending a POST request to the /auth/sign_in endpoint.

Use this endpoint with your username and password to obtain a JWT token. This token is used to authenticate requests and expires periodically, requiring you to re-authenticate.

Example Request​
POST /auth/sign_in
Content-Type: application/json

{
  "username": "your_username",
  "password": "your_password"
}
Example Response​
{
  "token" "your-jwt-token",
  ...other data...
}

Use this token in the Authorization header for all subsequent requests.

Authorization Bearer your-jwt-token

Option 2: Authenticate with Basic Authorization​

For long-term access (e.g., applications that don’t need regular logins), you can use a standard generated API token. This token does not expire and can be managed under My Settings -> Access Token in the portal (see [How to generate an Access Token] for details).

Authorization Basic your-access-token

Step 3: Create a Target​

Once authenticated, you can create a Target—the resource representing the host you want to scan.

This endpoint creates a new target with the specified host details.

Example Request​

POST /v2/targets

Authorization: Bearer your_jwt_token
Content-Type: application/json
    
{
    "target": {
        "name": "My Target",
        "hosts": "example.com"
    }
}

Example Response​

{
  "id": "target-id",
  ...other data...
}

Take note of the id field in the response. You will need this ID to run a scan on this target.

Step 4: Create and Run a Scan​

With the target created, you can now create a scan and run it.

This endpoint creates a new scan for the specified target.

note

The run_now field is set to true to start the scan immediately.

Example Request​

POST /v2/scans

Authorization: Bearer your_jwt_token
Content-Type: application/json

{
    "scan": {
        "name": "My Scan",
        "target_id": "target-id",
        "run_now": true
    }
}

Example Response​

{
  "id": "scan-id",
  ...other data...
}

With this response, the scan is now active and will progress automatically. You can monitor its status or retrieve the results once completed.

Next Steps​

This quickstart guide provides a basic overview of the API and how to interact with it. For more detailed information on the available endpoints and their usage, please refer to the REST API Reference.