Performs an indicator search.
Path
/api/%API_VERSION%/lookup
Method
POST
Request headers
This request has the following headers.
Request headers
Name |
Value |
Description |
---|---|---|
|
|
|
|
|
Response content type. |
|
|
Request content type. You can also specify the |
|
|
Request body size, in bytes. The maximum body size for this request is 64 MB ( |
Request body
This request body contains a JSON array of objects for search. At least one object must be specified.
[{"object":"%OBJECT_VALUE%"},...{"object":"%OBJECT_VALUE%"}]
Object properties are described in the following table.
Object properties
Property |
Value |
Mandatory |
Description |
---|---|---|---|
|
|
Yes |
Object for search. |
Request example
The following is an example of a POST lookup request.
POST https://192.0.2.57/api/1.1/lookup
Accept: application/json Content-Type: application/json Authorization: Basic Content-Length: 81
[{"object":"http:\/\/example.com"},{"object":"C1153422C5F68E731347F6A33F791598"}] |
Response headers
The response has the following headers.
Response headers
Name |
Value |
Description |
---|---|---|
Content-Type |
|
Response content type. |
Content-Length |
|
Response body size, in bytes. |
Response body
The response body contains a JSON array of search result objects.
[
{
"object": "%OBJECT_VALUE%",
"result": "%LOOKUP_RESULT%",
"categories":
[
{
"category": "%CATEGORY_1%",
"detected_indicator": "%DETECTED_INDICATOR%",
"context":
{
"%supplier_field_1%": "%supplier_field_1_value%",
...
"%supplier_field_N%": "%supplier_field_N_value%"
}
},
...
{
"category": "%CATEGORY_N%",
"detected_indicator": "%DETECTED_INDICATOR%",
"context":
{
"%supplier_field_1%": "%supplier_field_1_value%",
...
"%supplier_field_N%": "%supplier_field_N_value%"
}
}
]
},
...
{
"object": "%OBJECT_VALUE%",
"result": "%LOOKUP_RESULT%",
"categories":
[
{
"category": "%CATEGORY_1%",
"detected_indicator": "%DETECTED_INDICATOR%",
"context":
{
"%supplier_field_1%": "%supplier_field_1_value%",
...
}
},
...
]
}
]
Search result object properties are described in the following table.
Search result object properties
Property |
Value |
Description |
---|---|---|
|
|
Object that was searched. |
|
|
Search result. The following values are possible:
|
|
|
An array of category objects, as described below. This property is included if result is |
|
|
Cause of the error. |
Properties of category objects are described in the following table.
Category object properties
Property |
Value |
Description |
---|---|---|
|
|
Detection category. |
|
|
Matched indicator. |
|
|
Array of context objects. |
Properties of context objects are described in the following table.
Context object properties
Property |
Value |
Description |
---|---|---|
|
|
The name of the property corresponds to the name of a field of a matched indicator. The value of the property contains the value of the field. |
Response example
The following is an example of a POST lookup request response.
НТТР/1.1 200 ОК Date:Mon, 23 Dec 2019 09:56:10 UTC Content-Type: application/json Content-Length: 372
[{"object":"http:\/\/example.com","result":"not detected"}, {"object":"C1153422C5F68E731347F6A33F791598","result":"detected", "detects": [{"category":"KL_Malicious_Hash","detected_indicator":"C1153422C5F68E731347F6A33F791598","context":{"first_seen":"10.07.2015 23:53","threat":"Trojan.Win32.Generic"}}]}, {"object":"http:\/\/error.example.com","result":"error","reason":"Limit on the lookup operation exceeded"} ] |
Error responses
For more information about possible response statuses, see section "Response statuses".
An error response contains a JSON object with the error description.
[
{
"status": "%ERROR%"
}
]
Error object properties are described in the following table.
Error object properties
Property |
Value |
Description |
---|---|---|
|
|
Error description. |
|
|
Cause of the error. |
Error response example
The following is an example of a POST lookup error response.
НТТР/1.1 500 Internal Server Error Date:Mon, 23 Dec 2019 09:56:10 UTC Content-Type: application/json Content-Length: 75
[{"status": "An error occurred while performing the lookup of indicators", "reason": "The database is not available"}] |