Processing Status API

Check status of submitted files

POST /api/samples/status/

Provides information on the processing status of requested samples in the Spectra Analyze system. All hash values in the request must be of the same type (SHA1, SHA256, SHA512, or MD5).

The response returns “not_found” status for sample hashes that don’t exist on the current Spectra Analyze instance, and “processed” for samples already on the current Spectra Analyze instance.

Optionally, the results can be filtered by “processed” or “not_found” status by providing the “status” parameter in the request. If status=not_found in the request, the response will include only the values for samples with the “not found” status on the appliance.

Request Format

Request Parameters

NAME	REQUIRED	DESCRIPTION	TYPE
hash_values	Required	Hash of the sample for which the user wants to check the processing status. At least one hash must be provided in the request. All hashes in a request must be of the same type. Supported hash types: SHA1, SHA256, SHA512, MD5	application/json
status	Optional	Optional parameter that allows filtering hashes by their status. When this parameter is included in the request, only the hashes matching the requested status are returned in the response. Supported values: processed, not_found	query, string

Request Examples

cURL

# Add --insecure before the URL if you are using a self-signed SSL certificate
curl -X POST 'https://appliance.example.com/api/samples/status/?status=processed' \
  --header 'Authorization: Token exampletoken' \
  --header 'Content-Type: application/json' \
  --data '{"hash_values": ["9dc5e23c7ab2692b83f0690a736b123a1837ae56", "4b21a49eadac1bc01477eff778041fdb765b8139"]}'

Python

import requests

# Change the token
token = "exampletoken"

# Change the hostname in the URL
url = "https://appliance.example.com/api/samples/status/"

params = {"status": "processed"}

json = {
  "hash_values": [
    "a0a968161aec928a45b0b9340eecfa5ec41fe9f2",
        "713e365e6e03d1e0b16c802a177fb94330cbe6e0"
  ]
}

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

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

print(response.text)

Response Format

Response Examples

{
  "hash_type": "sha1",
  "results": [
    {
      "hash_value": "9dc5e23c7ab2692b83f0690a736b123a1837ae56",
      "status": "processed"
    },
    {
      "hash_value": "4b21a49eadac1bc01477eff778041fdb765b8139",
      "status": "processed"
    }
  ]
}

Response Fields

FIELD NAME	TYPE
hash_type	string
results	array

Response Status Codes

CODE	DESCRIPTION
200	OK
400	Validation error, JSON parse error, or other error related to the validity of the data passed in the request.

Check status of submitted URLs

GET /api/uploads/v2/url-samples/{ID}

Check the processing status of a submitted URL. The ID path parameter is required and must correspond to the id value in the response from the Submissions API.

Request Format

Request Parameters

NAME	REQUIRED	DESCRIPTION	TYPE
id	Required	Identification number of the submission processing task on the appliance. This number is automatically generated and returned in the response of the Submissions API.	path, string

Request Examples

cURL

# Add --insecure before the URL if you are using a self-signed SSL certificate
curl -X GET 'https://appliance.example.com/api/uploads/v2/url-samples/1234' \
  --header 'Authorization: Token exampletoken'

Python

import requests

# Change the values of token and ID
token = "exampletoken"
ID = "123" # From the response of the URL submission API
# Change the hostname in the URL
url = f"https://appliance.example.com/api/uploads/v2/url-samples/{ID}"

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

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

Response Format

Response Examples

The processing_status field in the response indicates the status of the URL submission.

{
  "processing_status": "downloading",
  "message": "",
  "report": {}
}
{
  "processing_status": "processing",
  "message": "",
  "report": {}
}

When the URL is successfully submitted and processed on the appliance, the full analysis report is returned in the response.

{
  "processing_status": "complete",
  "message": "",
  "report": {}
}

If the URL submission fails, the response indicates that with the "processing_status": "error" field. In this case, the message field contains a more detailed message explaining why the URL submission failed.

{
 "processing_status": "error",
 "message": "the following error occured - Server responded with error 404: Not Found. Logs may contain more information on why this happened.",
 "report": {}
}

Response Status Codes

CODE	DESCRIPTION
200	OK