POST lookup

Performs an indicator search.

Path

/api/%API_VERSION%/lookup

Method

POST

Request headers

This request has the following headers.

Request headers

Name	Value	Description
Authorization	string (base 64)	Authentication string.
Accept	application/json	Response content type.
Content-Type	application/json	Request content type. You can also specify the utf-8 charset type. For example: Content-Type: application/json; charset=utf-8
Content-Length	integer	Request body size, in bytes. The maximum body size for this request is 64 MB (67108864).

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
object	string	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 dXNlcjpwYXNzd29yZA== Content-Length: 81 [{"object":"http:\/\/example.com"},{"object":"C1153422C5F68E731347F6A33F791598"}]

Response headers

The response has the following headers.

Response headers

Name	Value	Description
Content-Type	application/json	Response content type.
Content-Length	integer	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	string	Object that was searched.
result	string	Search result. The following values are possible: detected A match with indicators was detected. not detected No matches with indicators were detected. error An error occurred during the search.
categories	array	An array of category objects, as described below. This property is included if result is "detected".
reason	string	Cause of the error.

Properties of category objects are described in the following table.

Category object properties

Property	Value	Description
category	string	Detection category.
detected_indicator	string	Matched indicator.
context	array	Array of context objects.

Properties of context objects are described in the following table.

Context object properties

Property	Value	Description
%field_name%	string	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
status	string	Error description.
reason	string	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"}]

Page top