SorbSecurity Cloud URLProtect API Reference

SorbSecurity Cloud URLProtect(SCU) provides an Application Programming Interface (API) framework for external applications to access core functions through the REST protocol.

The API is implemented as a RESTful web services API. Each request will require the user’s API key. REST stands for Representational State Transfer. It relies on a stateless, client-server and cacheable communication protocol – HTTP. It is an architecture style for designing networked applications. RESTful applications use HTTP requests to post data (create and/or update), get data (query information) and delete data. Thus, REST uses HTTP for all CRUD (Create/Read/Update/Delete) operations. It is a lightweight alternative to mechanisms like RPC (Remote Procedure Calls) and Web Services such as SOAP and WSDL.

Each organization has limits on request rate and total requests; these limits are laid out in each organization’s terms of service. Unless otherwise specified, there are separate limits for report requests and run requests.

API	Description
URL Analysis	Submit a URL link to URLProtect analysis, return format is JSON.
Analysis Status	Request analysis status of a given analysis task ID, return format is JSON.
Analysis Result	Request the summary analysis result of an analysis task ID, return format is JSON.
Details	Request the full analysis result of an analysis task ID, return format is JSON.
Search Task ID	Query the latest analyzed task_id of the given URL, return format is JONS.
Vedict Disposition	Report False Positive, False Negative, or restore the original verdict of the analysis result of an analysis task ID, return format is JSON.

1. URL Analysis

Submit a URL link to SorbSecurity Cloud URLProtect(SCU) for the analysis, return format is JSON.

How to use:

Format:
curl -s -H 'Content-Type:application/json' -X POST -d '{"url":"https://somebadness.tld"}' https://urlarmor.sorbsecurity.com/api/<api_key>/scan/

Example:
curl -s -H 'Content-Type:application/json' -X POST -d '{"url":"https://somebadness.tld"}' https://urlarmor.sorbsecurity.com/api/1c1d0f251235c4456b2d06be7502835a/scan/

Successful Returns:

{
    "error": false,
    "task_id": "zB0GFGz_TsFxAX47m6oODL4jE70oxJzEZRVh8Jgmshk=",
    "query_url":
    {
        "status": "/api/1c1d0f251235c4456b2d06be7502835a/status/zB0GFGz_TsFxAX47m6oODL4jE70oxJzEZRVh8Jgmshk=/",
        "result": "/api/1c1d0f251235c4456b2d06be7502835a/result/zB0GFGz_TsFxAX47m6oODL4jE70oxJzEZRVh8Jgmshk=/"
    }
}

Error Returns:

{
    "msg": "invalid method",
    "error": true
}

{
    "msg": "invalid json",
    "error": true
}

2. Analysis Status

Request SorbSecurity Cloud URLProtect(SCU) analysis status of a given analysis task ID, return format is JSON.

How to use

Format:
curl -s https://urlarmor.sorbsecurity.com/api/<api_key>/status/<task_id>/

Example:
curl -s https://urlarmor.sorbsecurity.com/api/1c1d0f251235c4456b2d06be7502835a/status/zB0GFGz_TsFxAX47m6oODL4jE70oxJzEZRVh8Jgmshk=/

Successful Returns:

{
    "status": "completed",
    "error": false
}

Error Returns:

{
    "msg": "task not found",
    "error": true
}

{
    "msg": "wrong task id",
    "error": true
}

3. Analysis Result

Request the summary of SorbSecurity Cloud URLProtect(SCU) analysis result of an analysis task ID, return format is JSON.

How to use:

Format:
curl -s https://urlarmor.sorbsecurity.com/api/<api_key>/result/<task_id>/

Example:
curl -s https://urlarmor.sorbsecurity.com/api/1c1d0f251235c4456b2d06be7502835a/result/zB0GFGz_TsFxAX47m6oODL4jE70oxJzEZRVh8Jgmshk=/

Successful Returns:

{
    "url": "somebadness.tld",
    "verdict": {
        "phishing": 0.0,
        "advertising": 0.0,
        "malicious": 0.0,
        "illegal": 0.0
    },
    "error": false
}

Error Returns:

{
    "msg": "wrong task id",
    "error": true
}

{
    "msg": "task not found",
    "error": true
}

{
    "msg": "task not completed yet",
    "error": true
}

{
    "msg": "failed to get result",
    "error": true
}

4. Details

Request the full SorbSecurity Cloud URLProtect(SCU) analysis result of an analysis task ID, return format is JSON.

How to use:

Format:
curl -s https://urlarmor.sorbsecurity.com/api/<api_key>/result/detail/<task_id>/

Example:
curl -s https://urlarmor.sorbsecurity.comm/api/1c1d0f251235c4456b2d06be7502835a/result/detail/zB0GFGz_TsFxAX47m6oODL4jE70oxJzEZRVh8Jgmshk=/

Successful Returns:

{
    "error": false,
    "detail": {}
}

Error Returns:

{
    "msg": "wrong task id",
    "error": true
}

{
    "msg": "task not found",
    "error": true
}

{
    "msg": "task not completed yet",
    "error": true
}

{
    "msg": "failed to get result",
    "error": true
}

5. Search Task ID

Query the latest SorbSecurity Cloud URLProtect(SCU) analyzed task_id of the given URL, return format is JONS.

How to use:

curl -s -H 'Content-Type:application/json' -X POST -d '{"url":"https://somebadness.tld"}' https://urlarmor.sorbsecurity.com/api/1c1d0f251235c4456b2d06be7502835a/search/task_id/

Successful Returns:

{
    "error": false,
    "task_id": "zB0GFGz_TsFxAX47m6oODL4jE70oxJzEZRVh8Jgmshk="
}

Error Returns:

{
    "msg": "invalid method",
    "error": true
}

{
    "msg": "invalid json",
    "error": true
}

{
    "msg": "invalid url",
    "error": true
}

{
    "msg": "task not found",
    "error": true
}

6. Vedict Disposition

Report False Positive, False Negative, or restore the original verdict of the analysis result of the SorbSecurity Cloud URLProtect(SCU) analysis task ID, return format is JSON.

How to use:

Format(Report FP):
curl -s https://urlarmor.sorbsecurity.com/api/<api_key>/verdict/report/<task_id>/<verdict_type>/fp/

Example:
curl -s https://urlarmor.sorbsecurity.com/api/1c1d0f251235c4456b2d06be7502835a/verdict/report/zB0GFGz_TsFxAX47m6oODL4jE70oxJzEZRVh8Jgmshk=/phishing/fp/


Format(Report FN):
curl -s https://urlarmor.sorbsecurity.com/api/<api_key>/verdict/report/<task_id>/<verdict_type>/fn/

Example:
curl -s https://urlarmor.sorbsecurity.com/api/1c1d0f251235c4456b2d06be7502835a/verdict/report/zB0GFGz_TsFxAX47m6oODL4jE70oxJzEZRVh8Jgmshk=/phishing/fn/


Format(Restore Original Vedict):
curl -s https://urlarmor.sorbsecurity.com/api/<api_key>/verdict/report/<task_id>/<verdict_type>/restore/

Example:
curl -s https://urlarmor.sorbsecurity.com/api/1c1d0f251235c4456b2d06be7502835a/verdict/report/zB0GFGz_TsFxAX47m6oODL4jE70oxJzEZRVh8Jgmshk=/phishing/restore/

Successful Returns:

{
    "error": false
}

Error Returns:

{
    "msg": "task not found",
    "error": true
}

{
    "msg": "verdict_type error.",
    "error": true
}

{
    "msg": "task not completed yet",
    "error": true
}

{
    "msg": "Option error.",
    "error": true
}