API - URLs

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 urls API

The urls API allows you to request that one or more URLs be scanned. 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 getting 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.

Usage

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

  • 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

path

The URL to be scanned.

Yes

String

user_agent_string

A User Agent string the URL will be scanned with.

No

String

user_location

The user location (USA, Europe, etc).

No

String

callback_url

The URL the system will send its response to.

No

String

callback_params

Additional params to be sent to the callback_url.

No

JSON

callback_headers

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

No

JSON

Response

The response will be the scan ID, for example:

inherit 
{
  "scan_id": 123456
}

If you supply a "callback_params" field, then it 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 the "www.acme.com" URL, with no callback to send the response to.

    inherit 
    response = requests.post(
        "https://<PERCEPTION-POINT-URL>/api/v1/urls/",
        data={"path": "www.acme.com"},
        headers=json.dumps({"Authorization": "Token <TOKEN_VALUE>"}),
    )
    print response
    {"scan_id": 123456}

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

    inherit 
    response = requests.post(
        "https://<PERCEPTION-POINT-URL>/api/v1/urls/",
        data={
            "path": "http://images.google.com",
            "callback_url": "https://my-api.com/callback",
            "Callback_headers": json.dumps({"Auth": "<TOKEN_VALUE>"}),
        },
        headers=json.dumps({"Authorization": "Token <TOKEN_VALUE>"}),
    )
    print response
    {"scan_id": 123456}

Flow chart diagram

See also: