API - Files

Note: Before implementing any of the Perception Point X‑Ray API functionality, contact your Customer Success Manager for Perception Point X‑Ray to make sure that the API functionality is included in your license.

This page includes the following topics:

About the files API

The files API allows you to request that one or more files be scanned by Perception Point X‑Ray. The scan results will be included in the Scans page inside Perception Point X‑Ray - in the API [] channel.

The files API can be used in two ways:

  • Callbacks: Provides a callback mechanism that allows receiving notifications when scanning is completed. For details, see API - Callback.

  • Polling: Continuously polls the service until the scan is completed.

For authentication requirements, and other details about the Perception Point API, see API Authentication.

Note: You can use the files API to scan files up to a maximum size of 500 MB. Larger files can't be scanned.

Request URL

POST <PERCEPTION-POINT-URL>/api/v1/files/

  • For US environments:

https://api.perception-point.io

  • For EU environments:

https://api.eu.perception-point.io

  • For AUS environments:

https://api.aus.perception-point.io

  1. In Perception Point X‑Ray, go to Account > Preferences.

  2. The Environment of your organization will appear under General > Info: US, EU, or AUS.

For additional information about formatting the above endpoint, see API URL format.

Available fields

Field name

Field description

Mandatory

Field type

data

File data.

Yes*

Binary

path

Path to the file in storage (i.e the S3 bucket).

Yes*

String

name

The name of the file to scan.

No

String

download_link

May be passed instead of data or path. Must contain a direct download link.

No

String

storage

The storage that path reads from.

(default is the Perception Point internal S3.)

No

String

file_password

The password for the file.

No

String

callback_url

The URL to which the system will send its response.

No

String

callback_params

Additional params to be sent to the callback_url.

No

JSON

callback_headers

Headers for the callback_url. This can be used for authentication, for example.

No

JSON

* only one of the two is required

Response

The response will be the scan ID, for example:

inherit 
{
  "scan_id": 123456
}

If you supply a "callback_params" field, then the details will be included in the response under "callback_params". For example:

inherit 
{
  "scan_id": 123456,
  "callback_params": {
    "key1": "value1",
    "key2": "value2"
  }
}

For details about "callback_params", see API - Callback.

Examples

  • Example 1: Request to scan a file, called sample.doc, that is located in the default storage. There is no callback to send the response to.

    inherit 
    response = requests.post(
        "https://<PERCEPTION-POINT-URL>/api/v1/files/",
        data={"path": "sample.doc"},
        headers={"Authorization": "Token <TOKEN_VALUE>"},
    )
    print response
    {"scan_id": 123456}

  • Example 2: Request to scan a file from my file system located at /tmp. The file is called "my_file.doc".

    The response of the scan will be sent to "https://my-api.com/callback", with {"Auth": "<TOKEN_VALUE>"} as a header.

    inherit 
    file = open("/tmp/example.pdf", "rb")
    response = requests.post(
        "https://<PERCEPTION-POINT-URL>/api/v1/files/",
        files={"data": file},
        data={
            "name": "my_file.doc",
            "callback_url": "https://my-api.com/callback",
            "callback_headers": {"Auth": "<TOKEN_VALUE>"},
        },
        headers={"Authorization": "Token <TOKEN_VALUE>"},
    )
    print response
    {"scan_id": 123456}

Flow chart diagram

See also: