Netscan API

Table of Contents

You can access Netscan's API on https://api.netscan.co. If you have any problems or requests please contact support.

  1. Netscan API Overview
    1. Current Version
    2. Schema
    3. Error Handling
    4. Authentication
  2. Endpoints
    1. Fetch scan results
    2. Fetch scan results summary
    3. Fetch a single scan
    4. Change TURN credentials

Netscan API Overview

Current Version

By default, all requests receive the v1 version of the Netscan API. We advise that you explicitly state the version you are requesting using the Accept HTTP Header:

We encourage you to explicitly request this version via the Accept header.

Accept: application/vnd.netscan.v1+json

⬆ back to TOC

Schema

  • You can access Netscan's API only over HTTPS, by using https://api.netscan.co. All data is sent and received as JSON.
  • All blank fields are included as null instead of being omitted.
  • All timestamps are returned in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

Error Handling

When an error occures you will get a response from netscan with a status code of 4xx in case of a client error or 5xx in case of a server error. In all cases you will get the standard error object:

{
  "message": "Invalid auth token",
  "error": true,
  "type": "error"
}
  • message String The error message.
  • error Boolean Always true.
  • type String The error type, possible types are: error.

⬆ back to TOC

Authentication

Some endpoints are privileged and accessible only from your account. To access them you will need to generate an Authorization Token. You can manage your API Tokens in your dashboard, under Settings.

Once you have a valid API token you should add it in your request's headers, using the key x-netscan-auth.

curl -H "x-netscan-auth: xxxxxx" -i https://api.netscan.co/scan

Pagination

Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with the ?page query parameter. You can define a custom per page size of up to 100 items using the ?show query parameter.

curl 'https://api.netscan.co/scan?page=2&show=100'

Total records

All resources with pagination will have the x-query-total header with a number representing the total records this resource has.

Paginated resources will have the Link HTTP header populated. The Link Header indicates relationships between resources. It is based on RFC5988 and looks like this:

Link: <http://api.netscan.co:25979/scan?page=3&show=30>; rel="next",
  <http://api.netscan.co:25979/scan?page=170&show=30>; rel="last"

Linebreak is included for readability.

The possible rel values are:

Name Description
next The link relation for the immediate next page of results.
last The link relation for the last page of results.

⬆ back to TOC

Endpoints

Fetch scan results

This endpoint will fetch a paginated data set of all the scans you performed with your SDK Token. The response of this endpoint is an Array of Result Data Objects.

GET /scan

Requires authentication

Fetch scan results summary

This endpoint will fetch a paginated data set of all the scans you performed with your SDK Token. The response of this endpoint is an Array of reduced Result Data Objects so as to reduce transfer size. This endpoint is optimal if you want to display the results in a table and you only need limited information.

GET /scan-summary

Requires authentication

Fetch a single scan

Returns the Result Data Object of the given scan ID.

GET /scan/:scanId

⬆ back to TOC

Change TURN credentials

Update the user account TURN credentials.

POST /user/turn

Requires authentication

  • username String The TURN server username
  • credential String The TURN server required credential.
  • urls Array An array of strings with the TURN servers in their format.

Example request body:

{
  "username": "turnuser",
  "credential": "strongpassword",
  "urls": [
    "turn:coturn.netscan.co:443?transport=udp",
    "turn:coturn.netscan.co:443?transport=tcp"
  ]
}

The server responds with HTTP Code 204 No Content.

⬆ back to TOC