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