NAV Navigation
Shell HTTP JavaScript Ruby Python PHP Java Go

Scan Management API v1

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Describes the API calls used to trigger the Constellation scan process.

Base URLs:

Authentication

Scans

Retrieves status of all scans

Code samples

# You can also use wget
curl -X GET /api/v1/scans/allusers \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
GET /api/v1/scans/allusers HTTP/1.1

Accept: application/json

const headers = {
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/scans/allusers',
{
method: 'GET',

headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'

headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/api/v1/scans/allusers',
params: {
}, headers: headers

p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}

r = requests.get('/api/v1/scans/allusers', headers = headers)

print(r.json())
<?php

require 'vendor/autoload.php';

$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
$response = $client->request('GET','/api/v1/scans/allusers', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
URL obj = new URL("/api/v1/scans/allusers");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main

import (
"bytes"
"net/http"
)

func main() {

headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {access-token}"},
}

data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "/api/v1/scans/allusers", data)
req.Header = headers

client := &http.Client{}
resp, err := client.Do(req)
// ...
}

GET /scans/allusers

This endpoint enables bulk retrieval of scan information from all users. Access to this functionality is restricted to requests that include a suitable ‘scope’.

The optional query parameters enable the results to be filtered by their start date, end date, the scan status and the scan’s owner.

Where a large number of scans are returned the results are paged, with links available to provide access to the ‘previous’ and ‘next’ page of results.

Parameters

Name In Type Required Description
startDate query string(date-time) false Include only scans started after the specified ‘startDate’
endDate query string(date-time) false Include only scans stared before the specified ‘endDate’
scanStatus query array[string] false Include only scans with the specified ‘scanStatus’
users query array[string] false Include only scans submitted by the listed owners
pageSize query integer false Limits the number of records returned in the response.
page query integer false Identifies which page in the results is required. If the value exceeds the number of available pages, then the last page is returned.

Detailed descriptions

users: Include only scans submitted by the listed owners

pageSize: Limits the number of records returned in the response.

page: Identifies which page in the results is required. If the value exceeds the number of available pages, then the last page is returned.

Enumerated Values

Parameter Value
scanStatus Listing
scanStatus Processing
scanStatus Cancelled
scanStatus Completed
scanStatus Errored
scanStatus Unknown

Example responses

200 Response

{
"total": 220,
"scans": [
{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}
],
"pageLinks": {
"totalPages": 4,
"curr": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=3",
"next": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=4",
"prev": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=2"
}
}

Responses

Status Meaning Description Schema
200 OK A list of all scans with their current status ScanStatusItemListAllUsers
400 Bad Request Invalid request parameters None
401 Unauthorized Insufficient authorisation None

Response Headers

Status Header Type Format Description
200 Cache-Control string none
200 Content-Type string none
200 X-Content-Type-Options string none
200 X-Frame-Options string none
200 Content-Security-Policy string none
200 Strict-Transport-Security string none

Retrieves status of all self-started scans

Code samples

# You can also use wget
curl -X GET /api/v1/scans \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
GET /api/v1/scans HTTP/1.1

Accept: application/json

const headers = {
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/scans',
{
method: 'GET',

headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'

headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/api/v1/scans',
params: {
}, headers: headers

p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}

r = requests.get('/api/v1/scans', headers = headers)

print(r.json())
<?php

require 'vendor/autoload.php';

$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
$response = $client->request('GET','/api/v1/scans', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
URL obj = new URL("/api/v1/scans");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main

import (
"bytes"
"net/http"
)

func main() {

headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {access-token}"},
}

data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "/api/v1/scans", data)
req.Header = headers

client := &http.Client{}
resp, err := client.Do(req)
// ...
}

GET /scans

The optional query parameters enable the results to be filtered by their start date, end date, the scan status and the scan’s owner.

Only scans generated by the requester will be included in the response.

Where a large number of scans are returned the results are paged, with links available to provide access to the ‘previous’ and ‘next’ page of results.

Parameters

Name In Type Required Description
startDate query string(date-time) false Include only scans started after the specified ‘startDate’
endDate query string(date-time) false Include only scans stared before the specified ‘endDate’
scanStatus query array[string] false Include only scans with the specified ‘scanStatus’
pageSize query integer false Limits the number of records returned in the response.
page query integer false Identifies which page in the results is required. If the value exceeds the number of available pages, then the last page is returned.

Detailed descriptions

pageSize: Limits the number of records returned in the response.

page: Identifies which page in the results is required. If the value exceeds the number of available pages, then the last page is returned.

Enumerated Values

Parameter Value
scanStatus Listing
scanStatus Processing
scanStatus Cancelled
scanStatus Completed
scanStatus Errored
scanStatus Unknown

Example responses

200 Response

{
"total": 220,
"scans": [
{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}
],
"pageLinks": {
"totalPages": 4,
"curr": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=3",
"next": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=4",
"prev": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=2"
}
}

Responses

Status Meaning Description Schema
200 OK A list of all scans with their current status ScanStatusItemList
400 Bad Request Invalid request parameters None
401 Unauthorized Insufficient authorisation None

Response Headers

Status Header Type Format Description
200 Cache-Control string none
200 Content-Type string none
200 X-Content-Type-Options string none
200 X-Frame-Options string none
200 Content-Security-Policy string none
200 Strict-Transport-Security string none

Starts a new scan of the specified storage container

Code samples

# You can also use wget
curl -X POST /api/v1/scans \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
POST /api/v1/scans HTTP/1.1

Content-Type: application/json
Accept: application/json
const inputBody = '{
"sourceConnectionString": "BlobEndpoint=https://scantest.blob.core.windows.net/;QueueEn......%3D",
"sourceContainerPath": "sourceContainer",
"destinationConnectionString": "BlobEndpoint=https://scantest.blob.core.windows.net/;QueueEn......%3D",
"targetContainerPath": "targetContainerName",
"quarantineContainerPath": "quarantineContainerName",
"autoRescan": false
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/scans',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/api/v1/scans',
params: {
}, headers: headers

p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}

r = requests.post('/api/v1/scans', headers = headers)

print(r.json())
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
$response = $client->request('POST','/api/v1/scans', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
URL obj = new URL("/api/v1/scans");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main

import (
"bytes"
"net/http"
)

func main() {

headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {access-token}"},
}

data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "/api/v1/scans", data)
req.Header = headers

client := &http.Client{}
resp, err := client.Do(req)
// ...
}

POST /scans

This will start a new scan of the specified storage container

Body parameter

{
"sourceConnectionString": "BlobEndpoint=https://scantest.blob.core.windows.net/;QueueEn......%3D",
"sourceContainerPath": "sourceContainer",
"destinationConnectionString": "BlobEndpoint=https://scantest.blob.core.windows.net/;QueueEn......%3D",
"targetContainerPath": "targetContainerName",
"quarantineContainerPath": "quarantineContainerName",
"autoRescan": false
}

Parameters

Name In Type Required Description
body body ScanStartItem false Configuration required to setup and start a scan of a storage container

Example responses

200 Response

{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}

Responses

Status Meaning Description Schema
200 OK Details of the new scan ScanStatusItem
400 Bad Request List of validation errors ErrorResponseList
401 Unauthorized Insufficient authorisation None
412 Precondition Failed The source container was empty. EmptyContainerErrorResponseList

Response Headers

Status Header Type Format Description
200 Cache-Control string none
200 Content-Type string none
200 X-Content-Type-Options string none
200 X-Frame-Options string none
200 Content-Security-Policy string none
200 Strict-Transport-Security string none
400 Cache-Control string none
400 Content-Type string none
400 X-Content-Type-Options string none
400 X-Frame-Options string none
400 Content-Security-Policy string none
400 Strict-Transport-Security string none
412 Cache-Control string none
412 Content-Type string none
412 X-Content-Type-Options string none
412 X-Frame-Options string none
412 Content-Security-Policy string none
412 Strict-Transport-Security string none

Retrieves status of the specified scan.

Code samples

# You can also use wget
curl -X GET /api/v1/scans/{scanId} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
GET /api/v1/scans/{scanId} HTTP/1.1

Accept: application/json

const headers = {
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/scans/{scanId}',
{
method: 'GET',

headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'

headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/api/v1/scans/{scanId}',
params: {
}, headers: headers

p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}

r = requests.get('/api/v1/scans/{scanId}', headers = headers)

print(r.json())
<?php

require 'vendor/autoload.php';

$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
$response = $client->request('GET','/api/v1/scans/{scanId}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
URL obj = new URL("/api/v1/scans/{scanId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main

import (
"bytes"
"net/http"
)

func main() {

headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {access-token}"},
}

data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "/api/v1/scans/{scanId}", data)
req.Header = headers

client := &http.Client{}
resp, err := client.Do(req)
// ...
}

GET /scans/{scanId}

This endpoint enables information regarding the status of the specified scan to be retrieved.

Requests submitted with the ‘StandardUser’ role are only permitted to view self-started scans.

Parameters

Name In Type Required Description
scanId path string(uuid) true Unique identifier for a scan process.

Example: 56d61ae4-8147-4778-acb1-1f1f9c881fa7

Example responses

200 Response

{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}

Responses

Status Meaning Description Schema
200 OK Information about a specific scan ScanStatusItem
401 Unauthorized Insufficient authorisation None
404 Not Found Specified scan not found None

Response Headers

Status Header Type Format Description
200 Cache-Control string none
200 Content-Type string none
200 X-Content-Type-Options string none
200 X-Frame-Options string none
200 Content-Security-Policy string none
200 Strict-Transport-Security string none

Cancels the specified scan.

Code samples

# You can also use wget
curl -X DELETE /api/v1/scans/{scanId} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
DELETE /api/v1/scans/{scanId} HTTP/1.1

Accept: application/json

const headers = {
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/scans/{scanId}',
{
method: 'DELETE',

headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'

headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete '/api/v1/scans/{scanId}',
params: {
}, headers: headers

p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}

r = requests.delete('/api/v1/scans/{scanId}', headers = headers)

print(r.json())
<?php

require 'vendor/autoload.php';

$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
$response = $client->request('DELETE','/api/v1/scans/{scanId}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
URL obj = new URL("/api/v1/scans/{scanId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main

import (
"bytes"
"net/http"
)

func main() {

headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {access-token}"},
}

data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("DELETE", "/api/v1/scans/{scanId}", data)
req.Header = headers

client := &http.Client{}
resp, err := client.Do(req)
// ...
}

DELETE /scans/{scanId}

This endpoint enables an active scan to be cancelled. The action of cancellation stops the cataloging action of the scan from finding files in the specified container. Any files that have already been found and submitted for processing will continue to be processed.

Requests submitted with the ‘StandardUser’ role are only permitted to cancel self-started scans.

Parameters

Name In Type Required Description
scanId path string(uuid) true Unique identifier for a scan process.

Example: 56d61ae4-8147-4778-acb1-1f1f9c881fa7

Example responses

202 Response

{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}

Responses

Status Meaning Description Schema
202 Accepted Information about the cancelled scan ScanStatusItem
401 Unauthorized Insufficient authorisation None
404 Not Found Scan not found None
405 Method Not Allowed Not allowed - Scan cancellation failed, page listing already completed None

Response Headers

Status Header Type Format Description
202 Cache-Control string none
202 Content-Type string none
202 X-Content-Type-Options string none
202 X-Frame-Options string none
202 Content-Security-Policy string none
202 Strict-Transport-Security string none

Restarts an existing scan.

Code samples

# You can also use wget
curl -X PATCH /api/v1/scans/{scanId} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
PATCH /api/v1/scans/{scanId} HTTP/1.1

Accept: application/json

const headers = {
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/scans/{scanId}',
{
method: 'PATCH',

headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'

headers = {
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}'
}

result = RestClient.patch '/api/v1/scans/{scanId}',
params: {
}, headers: headers

p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}

r = requests.patch('/api/v1/scans/{scanId}', headers = headers)

print(r.json())
<?php

require 'vendor/autoload.php';

$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
$response = $client->request('PATCH','/api/v1/scans/{scanId}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
URL obj = new URL("/api/v1/scans/{scanId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PATCH");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main

import (
"bytes"
"net/http"
)

func main() {

headers := map[string][]string{
"Accept": []string{"application/json"},
"Authorization": []string{"Bearer {access-token}"},
}

data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("PATCH", "/api/v1/scans/{scanId}", data)
req.Header = headers

client := &http.Client{}
resp, err := client.Do(req)
// ...
}

PATCH /scans/{scanId}

When a scan completes, if any files have been added to the container during or after the scan they may not be included in the scan results. This endpoint enables a scan to be restarted to include those new files.

Requests submitted with the ‘StandardUser’ role are only permitted to restart self-started scans.

Rescans are not permitted whilst the original/parent scan is still in the ‘Listing’ status.

Parameters

Name In Type Required Description
scanId path string(uuid) true Unique identifier for a scan process.

Example: 56d61ae4-8147-4778-acb1-1f1f9c881fa7

Example responses

200 Response

{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}

Responses

Status Meaning Description Schema
200 OK Scan restarted ScanStatusItem
401 Unauthorized Insufficient authorisation None
404 Not Found Specified scan not found None
409 Conflict Rescan failure as another rescan is in progress for the original/parent scan. None
412 Precondition Failed List of validation errors ErrorResponseList
425 Unknown Rescan failure as the original/parent scan is still in the “Listing” status. None

Response Headers

Status Header Type Format Description
200 Cache-Control string none
200 Content-Type string none
200 X-Content-Type-Options string none
200 X-Frame-Options string none
200 Content-Security-Policy string none
200 Strict-Transport-Security string none
412 Cache-Control string none
412 Content-Type string none
412 X-Content-Type-Options string none
412 X-Frame-Options string none
412 Content-Security-Policy string none
412 Strict-Transport-Security string none

Schemas

ScanStartItem

{
"sourceConnectionString": "BlobEndpoint=https://scantest.blob.core.windows.net/;QueueEn......%3D",
"sourceContainerPath": "sourceContainer",
"destinationConnectionString": "BlobEndpoint=https://scantest.blob.core.windows.net/;QueueEn......%3D",
"targetContainerPath": "targetContainerName",
"quarantineContainerPath": "quarantineContainerName",
"autoRescan": false
}

Properties

Name Type Required Restrictions Description
sourceConnectionString string true none Connection string for the storage account to be scanned. It should conform to the following.
1. Signed Service (ss) must include blob
2. Signed Resource Type (srt) must include service and object.
3. Signed Permission (sp) must include Read ( r ) and List (l)
4. Signed Start (st) must preceded UTC.Now()
5. Signed Expiry (se) must be in the future
sourceContainerPath string true none Name of the container to be scanned in the specified storage account
destinationConnectionString string true none Connection string for the storage account to which scan results are to be written. It should conform to the following.
1. Signed Service (ss) must include blob
2. Signed Resource Type (srt) must include service, container and object.
3. Signed Permission (sp) must include Read ( r ) Write (w) Create ( c ) and List (l)
4. Signed Start (st) must preceded UTC.Now()
5. Signed Expiry (se) must be in the future
targetContainerPath string true none Name of the container in the destination storage account into which rebuilt files are to be written.
quarantineContainerPath string true none Name of the container in the destination storage account into which quarantine reports are to be written.
autoRescan boolean false none Configures whether a rescan of the container is required once the original scan is completed.

ScanStatusItemList

{
"total": 220,
"scans": [
{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}
],
"pageLinks": {
"totalPages": 4,
"curr": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=3",
"next": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=4",
"prev": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=2"
}
}

Properties

Name Type Required Restrictions Description
total integer false none The total number of items that match the query
scans [ScanStatusItem] true none none
pageLinks ScanResultsLinks false none These links provide access to the paged results either side of the current page segment
along with the total number of pages.

If the number of results returned is within a single page segment, then these links are not included in the response.

ScanStatusItemListAllUsers

{
"total": 220,
"scans": [
{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}
],
"pageLinks": {
"totalPages": 4,
"curr": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=3",
"next": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=4",
"prev": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=2"
}
}

Properties

Name Type Required Restrictions Description
total integer false none The total number of items that match the query
scans [ScanStatusItem] true none none
pageLinks ScanResultsLinksAllUsers false none These links provide access to the paged results either side of the current page segment, along with the total number of pages.

If the number of results returned is within a single page segment, then these links are not included in the response.

ScanStatusItem

{
"scanOwner": "string",
"scanId": "83d71394-faa2-4b6c-b13b-6d3118de459e",
"scanStatus": "Processing",
"scanStartTime": "2019-08-24T14:15:22Z",
"scanEndTime": "2019-08-24T14:15:22Z",
"sourceStorage": "scan-source.blob.core.windows.net",
"sourceContainerPath": "SourceContainer",
"targetStorage": "output-location.blob.core.windows.net",
"targetContainerPath": "TargetContainerName",
"quarantineContainerPath": "QuarantineContainerName",
"autoRescan": true,
"parentScan": "f18eda36-7eb5-477a-a1b1-51c71ab2ba81",
"childScans": null
}

Properties

Name Type Required Restrictions Description
scanOwner string true none Identity of the scan starter
scanId string(uuid) true none Unique identifier for the scan
scanStatus string true none Reports the current processing status of the scan
scanStartTime string(date-time) true none The time at which the scan started
scanEndTime string(date-time)¦null false none The time at which the scan finished, or was cancelled. Null if scan still in progress.
sourceStorage string true none Storage account containing the sourceContainerPath.
sourceContainerPath string true none Name of the container to be scanned in the specified storage account
targetStorage string true none Storage account containing the targetContainerPath and quarantineContainerPath.
targetContainerPath string true none Name of the container in the destination storage account into which rebuilt files are to be written
quarantineContainerPath string true none Name of the container in the destination storage account into which quarantine reports are to be written
autoRescan boolean true none Flag is set to ‘true’ if an automatic rescan has been configured to start when the original scan is completed.
parentScan string(uuid) false none If this scan is a rescan, then the parent scan’s identity is recorded in this property.
childScans [string] false none If and rescans have been requested, based on this scan, then the identities of the rescans are recorded in this property.

Enumerated Values

Property Value
scanStatus Listing
scanStatus Processing
scanStatus Cancelled
scanStatus Completed
scanStatus Error
scanStatus Unknown
{
"totalPages": 4,
"curr": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=3",
"next": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=4",
"prev": "/scans?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=2"
}

These links provide access to the paged results either side of the current page segment
along with the total number of pages.

If the number of results returned is within a single page segment, then these links are not included in the response.

Properties

Name Type Required Restrictions Description
totalPages integer false none The total number of pages that
curr string false none URL providing access to the current page of results
next string false none URL providing access to the next page of results
prev string false none URL providing access to the previous page of results

ScanResultsLinksAllUsers

{
"totalPages": 4,
"curr": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=3",
"next": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=4",
"prev": "/scans/allusers?startDate=2022-12-20T16:44:41.741Z?endDate=2022-12-20T16:44:41.741Z?scanStatus=Processing&scanStatus=Completed?pageSize=10?page=2"
}

These links provide access to the paged results either side of the current page segment, along with the total number of pages.

If the number of results returned is within a single page segment, then these links are not included in the response.

Properties

Name Type Required Restrictions Description
totalPages integer false none The total number of pages that
curr string false none URL providing access to the current page of results
next string false none URL providing access to the next page of results
prev string false none URL providing access to the previous page of results

PageLinksForFiles

{
"totalPages": 4,
"curr": "/scan-results/{scanId}/files?pageSize=100?includeRebuilt=true?page=3",
"next": "/scan-results/{scanId}/files?pageSize=100?includeRebuilt=true?page=4",
"prev": "/scan-results/{scanId}/files?pageSize=100?includeRebuilt=true?page=2"
}

These links provide access to the paged results either side of the current page segment, along with the total number of pages.

If the number of results returned is within a single page segment, then these links are not included in the response.

Properties

Name Type Required Restrictions Description
totalPages integer false none The total number of pages.
curr string false none URL providing access to the current page of results
next string false none URL providing access to the next page of results
prev string false none URL providing access to the previous page of results

PageLinksForArchives

{
"totalPages": 4,
"curr": "/scan-results/{scanId}/files/{fileId}?pageSize=100?includeRebuilt=true?page=3",
"next": "/scan-results/{scanId}/files/{fileId}?pageSize=100?includeRebuilt=true?page=4",
"prev": "/scan-results/{scanId}/files/{fileId}?pageSize=100?includeRebuilt=true?page=2"
}

These links provide access to the paged results either side of the current page segment, along with the total number of pages.

If the number of results returned is within a single page segment, then these links are not included in the response.

Properties

Name Type Required Restrictions Description
totalPages integer false none The total number of pages that
curr string false none URL providing access to the current page of results
next string false none URL providing access to the next page of results
prev string false none URL providing access to the previous page of results

ScanFilesAssessmentMetadata

{
"fileLocation": "supported/1/test.png",
"fileSize": 123456,
"fileHash": "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=",
"fileId": "cd88f362-6c83-49a1-bbcb-7c08389a0caa",
"status": "Failed"
}

Properties

Name Type Required Restrictions Description
fileLocation string false none Full file path locating the processed file
fileSize integer false none Size of the processed file in bytes
fileHash string false none SHA256 Hash of the processed file
fileId string(uuid) false none Uniquely identifies the file
status string false none Status of the processed file from CDR Engine
- Failed: File was not rebuilt due to policy
- Errored: File was not rebuilt due to processing error
- Rebuilt: File was successfully rebuilt

Enumerated Values

Property Value
status Failed
status Errored
status Rebuilt

EmptyContainerErrorResponseList

[
{
"errorCode": 107,
"message": "Source container was empty."
}
]

List of errors found during validation

Properties

Name Type Required Restrictions Description
errorCode integer false none Error code from the validation
message string false none Error description for the error code

ErrorResponseList

[
{
"errorCode": 105,
"message": "The signed start (se) parameter must be in the future for the source connection string."
}
]

List of errors found during validation

Properties

Name Type Required Restrictions Description
errorCode integer false none Error code from the validation
message string false none Error description for the error code

CacheControlHeader

"no-store"

Prevent sensitive information from being cached.

Properties

Name Type Required Restrictions Description
anonymous string false none Prevent sensitive information from being cached.

ContentTypeHeader

"application/json"

Indicates the response content type

Properties

Name Type Required Restrictions Description
anonymous string false none Indicates the response content type

ContentTypeOptionsHeader

"nosniff"

To prevent browsers from performing MIME sniffing, and inappropriately interpreting responses as HTML.

Properties

Name Type Required Restrictions Description
anonymous string false none To prevent browsers from performing MIME sniffing, and inappropriately interpreting responses as HTML.

FrameOptionsHeader

"DENY"

To protect against drag-and-drop style clickjacking attacks.

Properties

Name Type Required Restrictions Description
anonymous string false none To protect against drag-and-drop style clickjacking attacks.

ContentSecurityPolicyHeader

"frame-ancestors 'none'"

To protect against drag-and-drop style clickjacking attacks.

Properties

Name Type Required Restrictions Description
anonymous string false none To protect against drag-and-drop style clickjacking attacks.

StrictTransportSecurityHeader

"max-age=604800"

Uses a week long max-age to prevent any communications from being sent to this domain over HTTP

Properties

Name Type Required Restrictions Description
anonymous string false none Uses a week long max-age to prevent any communications from being sent to this domain over HTTP