Skip to main content
Version: Spectra Analyze 9.1.2

Advanced Search API

POST /api/samples/v3/search/

Search for samples​

Search for samples available on the local Spectra Analyze instance and Spectra Intelligence using the Advanced Search capabilities. Users can authenticate with their regular Spectra Analyze tokens.

  • All restricted words and characters must be escaped with double quotation marks.
  • All datetime fields are in UTC format: YYYY-MM-DDThh:mm:ssZ.
  • The default and only supported response format is JSON.
  • Requests must contain the HTTP header field with Content-­Type: application/json.
  • By default, the API returns 20 samples per page.

Request Format​

{
   "query": "<field_name>:<field_value> <field_name>:<field_value> ...",
   "page": 1,
   "records_per_page": 20,
   "sort": "<field_name> desc"
}

Request Parameters

NAMEDESCRIPTIONREQUIRED
queryString representing the search expression.Yes
ticloudShow only cloud results in the response. This parameter is false by default. If omitted, the response will show only local results.No
pageIf more than <records_per_page> records match the requested criteria, the response will have a next_page value, which can be used in the request to fetch the next page with up to <records_per_page> results. This is the value defining which page of results to return in the response. Defaults to first page (1) if omitted.No
records_per_pageValue defining how many results should be returned per page. Defaults to 20 if omitted. Maximum value is 100.No
sortString that allows sorting the results by one of the supported fields: sha1, firstseen, threatname, sampletype, filecount, size. The results can be sorted in ascending or descending order by using the asc or desc keywords. By default, the results are sorted by firstseen in descending order (most recent to oldest).No
start_search_dateThe starting date for the search. This parameter represents the later date, as searches are performed backwards in time.Only used if ticloud is set to true
end_search_dateThe ending date for the search. This parameter represents the earlier date, as searches are performed backwards in time.Only used if ticloud is set to true

Using time range parameters​

Both time range parameters should be formatted as strings in the “YYYY-MM-DD” format. For further granularity, the firstseen keyword can be used to specify a particular time of day.

Search queries progress backward in time, meaning that results are first returned closer to the end_search_date. Both start_search_date and end_search_date are included in the search, allowing the query to return results for both dates, if available.

It is possible that the query only returns results until some point in time, instead of for the whole given time range. In that case, the last_search_date parameter will be returned, which can be used as end_search_date in the next query.

Note: The last_search_date is not included in search.

When the end_of_dataset parameter is returned in the response, it means that the query found all samples which meet the search criteria in the given time range. This parameter applies only to Cloud searches, and should be ignored in local queries.

Advanced Search Queries​

The query field contains the search expression that will be submitted to the API. Every search expression must contain at least one keyword and one value.

Search expressions are built according to the following formula: <field_name>:<field_value>.

Supported values for field_name correspond to keywords currently supported by Advanced Search.

For field_value, the following are supported:

  • equals operator - to search for exact matches (classification:malicious, available:true…)
  • range operator - to search for closed ranges of values, including the upper and lower boundary (firstseen:[2018-01-01T00:00:00Z TO 2018-01-02T00:00:00Z]) or open-ended ranges indicating greater/less-than values (threatlevel:[0 TO *])
  • in operator - to search for any value in the specified list (classification:[malicious, suspicious])
  • wildcard symbols - for search keywords that support them (av-detection:*crypto)

It is also possible to use operators and multi-keyword combinations.

Search Query Example

{
   "query": "firstseen:2018-01-01T00:00:00Z (av-detection:trojan AND type:binary NOT positives:[* TO 3])"
}

Request Examples​

Format of the POST request body:

{
   "query":"classification:[malicious, suspicious]",
   "records_per_page":10,
   "start_search_date":"2023-01-01",
   "end_search_date":"2023-07-01",
   "ticloud":true
}

Query contains all the keywords related to the sample, while the other fields specify the format of the response.

cURL

# Add --insecure before the URL if you're using a self-signed SSL certificate
curl -X POST 'https://appliance.example.com/api/samples/v3/search/' \
--header 'Authorization: Token exampletoken' \
--header 'Content-Type: application/json' \
--data '{"query":"classification:[malicious, suspicious]","records_per_page":10,"start_search_date":"2023-01-01","end_search_date":"2023-07-01","ticloud":true}'

Python

import requests

# Change the token
token = "exampletoken"
# Change the hostname in the URL
url = "https://appliance.example.com/api/samples/v3/search/"

json = {"query":"classification:[malicious, suspicious]","records_per_page":10,"start_search_date":"2023-01-01","end_search_date":"2023-07-01","ticloud":true}

headers = {'Authorization': f'Token {token}'}

# Add verify=False in the request if you are using a self-signed SSL certificate
response = requests.post(url, headers=headers, json=json)
print(response.text)

Response Format​

{
   "rl":{
      "web_search_api":{
         "next_page":2,
         "more_pages":true,
         "sample_count":10,
         "entries":[
            {
               "sha1":"465aa6e49e02cd677924a6c4486f82f53a6a90f1",
               "sha256":"92fdba6367ea91001515b3b1a0a47892fb04a3606fe7c339a95431ea71467c43",
               "md5":"d35bd156250608f3a182fe75a72cd032",
               "filename":"_00145",
               "antivirus":28,
               "firstseen":"2023-07-01T23:59:59Z",
               "lastseen":"2023-07-04T08:05:19Z",
               "available":true,
               "size":52175,
               "sampletype":"PE/Exe",
               "classification":"malicious",
               "threatname":"Win32.Worm.Eggnog",
               "factor":10,
               "filecount":0
            },
            "..."
         ],
         "last_search_date":"2023-06-30",
         "end_of_dataset":false
      }
   }
}

If the ticloud parameter is set and the available field is true, the sample is shareable in the Spectra Intelligence cloud, but if it is false, the sample is private.

The total_count field will be returned only if "ticloud"=false. Total sample count for Spectra Intelligence data must be retrieved with the Total Count endpoint documented below.

Response Status Codes

CODEDESCRIPTION
200OK
400Bad request. E.g. invalid value for a field, or other validation error.
403Forbidden. This response is returned when the request isn’t authenticated.
404Not found. E.g. wrong URL.

Total Count​

POST /api/samples/v3/search/total-count

This endpoint returns total counts for samples present in the Spectra Intelligence cloud. It always behaves as if the ticloud parameter is set to true.

Total counts for local samples are returned in regular search query responses as the total_count field, if ticloud=false.

It supports single queries and follows the same rules as the search query endpoint.

Bulk queries return response code 400 with the message “Bulk query not supported on total count endpoint”.

Since the total count query goes backwards in time, it is possible that the total_count query only returns count until some point in time, instead of for the whole given time range. In that case, the last_search_date parameter will be returned, which can be used as end_search_date in the next query.

Note: last_search_date is not included in the count.

Request Format

{
   "query": "<field_name>:<field_value> <field_name>:<field_value> ...",
   "start_search_date": "YYYY-MM-DD",
   "end_search_date": "YYYY-MM-DD"
}

Request Parameters

NAMEDESCRIPTIONREQUIRED
queryString representing the search expression. Refer to the the Advanced Search endpoint documentation above for more information.Yes
start_search_dateThe starting date for the search. This parameter represents the later date, as searches are performed backwards in time.Yes
end_search_dateThe ending date for the search. This parameter represents the earlier date, as searches are performed backwards in time.Yes

Request Examples​

{
   "query":"classification:[malicious, suspicious]",
   "start_search_date":"2023-01-01",
   "end_search_date":"2023-07-01",
}
Response Format​
{
"total_count": 1510377,
"last_search_date": "2023-06-30",
"end_of_dataset": false
}