# Classification Status API — Spectra Analyze

> Retrieve threat classification, risk score, and detection status for samples in Spectra Analyze, with optional Spectra Intelligence fallback for unknown samples.

## Retrieve classification status for a sample

```
GET /api/samples/v3/{hash_value}/classification/
```

Get classification results for a sample. The sample must be present on the appliance.

By default, if the requested sample is not found on the appliance, or if **classification** for the sample is “UNKNOWN”, the API automatically sends a request to Spectra Intelligence for any classification information and return it in the response. The prerequisite for this functionality is a properly configured Spectra Intelligence account on the appliance.

To disable automatic Spectra Intelligence querying, the optional parameter `localonly` can be used in the request. When set to `localonly=1`, it specifies that only local classification data should be returned for the sample, without falling back to querying Spectra Intelligence.

Queries from the appliance to Spectra Intelligence are limited to 10 000 requests per day. If the user makes 10 000 requests to Spectra Intelligence via this endpoint (by querying hashes that don’t exist on the appliance), the endpoint will respond with a 429 HTTP status code until the start of the next calendar day (00:01 UTC).

**Important: Spectra Intelligence queries for samples that exist on the appliance, but don’t have a local classification (samples with *Unknown* status) **do not count** towards the daily limit. Spectra Intelligence queries for samples that don’t exist on the appliance are the only ones that count towards the limit.**


### Request Format

**Request Parameters**

| NAME        | REQUIRED | DESCRIPTION                                                  | TYPE          |
| :---------- | :------- | :----------------------------------------------------------- | :------------ |
| hash_value  | Required | Hash of the sample for which the classification status should be returned. Only one hash can be submitted in one request. Supported hash types: SHA1, SHA256, MD5 | path, string  |
| localonly   | Optional | Defines the source of the classification data to be returned. Supported values: 0, 1. If it is set to 1, automatic requests to Spectra Intelligence are disabled, and `av_scanners=1` cannot be used in the same request. If the parameter is omitted from the request, or submitted with the value of 0 (default), the API returns classification status for samples on the Spectra Analyze appliance. If the requested samples are not found on the appliance, it automatically sends a request to Spectra Intelligence. If the parameter is submitted with the value of 1, the API returns classification status only for samples on the appliance and does not send requests to Spectra Intelligence. | query, string |
| av_scanners | Optional | Specifies whether to include the AV scanners summary information in the response. Supported values: 0, 1. If the parameter is omitted from the request, or submitted with the default value of 0, the AV scanners metadata is not included in the response. When set to 1, AV scanners metadata is included in the response. The API first looks for any existing local metadata. If there is no local metadata, a request is sent to Spectra Intelligence. **This request counts towards the Spectra Intelligence usage quota.** This parameter cannot be used with `localonly=1` in the same request, because that disables requests to Spectra Intelligence. | query, string |

**Request Examples**

**cURL**

```bash
# Add --insecure before the URL if you are using a self-signed SSL certificate
curl -X GET 'https://appliance.example.com/api/samples/v3/cf8e42c4a0862c807f0de3c656d2cd1c99cc5a27/classification/' \
  --header 'Authorization: Token exampletoken'
```

**Python**

```python

# Change the values of token and hash_value
token = "exampletoken"
hash_value = "examplehash"
# Change the host name in the URL and the fields to be included in the response
url = f"https://appliance.example.com/api/v2/samples/{hash_value}/classification/"

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)
```

**Python with optional parameters**

```python

# Change the values of token and hash_value
token = "exampletoken"
hash_value = "examplehash"
# Change the host name in the URL and the fields to be included in the response
url = f"https://a1000.example.com/api/v2/samples/{hash_value}/classification/?av_scanners=1"

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**

Default response

```json
{
  "classification": "malicious",
  "riskscore": 10,
  "first_seen": "2014-08-27T04:35:43Z",
  "last_seen": "2016-04-30T04:11:00Z",
  "classification_result": "Win32.Backdoor.Poison",
  "classification_origin": { <hashes> },
  "classification_reason: "CLOUD"
}
```

Response when the requested sample is not found on the appliance

```json
{
   "message": "Hash not found.",
   "hash_value": "3d879d037184b17e47bc3391ff6c0b72"
}
```

**Response Fields**

| FIELD NAME            | TYPE    | DESCRIPTION                                                  |
| :-------------------- | :------ | :----------------------------------------------------------- |
| sha1                  | string  | SHA1 hash of the sample                                      |
| sha256                | string  | SHA256 hash of the sample                                    |
| md5                   | string  | MD5 hash of the sample                                       |
| classification        | string  | Indicator of sample status (MALICIOUS, SUSPICIOUS, GOODWARE, UNKNOWN) |
| riskscore             | integer | Risk score value of the sample (0-10, lowest to highest)     |
| first_seen            | string  | UTC date-time (example: “2014-08-27T04:35:43Z”)              |
| last_seen             | string  | UTC date-time (example: “2014-08-27T04:35:43Z”)              |
| classification_result | string  | RL normalized threat name (example: “Win32.Backdoor.Poison”) |
| classification_origin | object  | List of hashes that the sample classification came from. Returns null if the request has been made directly to Spectra Intelligence, or if Spectra Intelligence has not been queried for local samples. |
| classification_reason | string  | Indicates the reason for the sample’s classification. Can be one of the following: UNKNOWN, THREAT REPUTATION, SIGNATURE, CERTIFICATE, FORMAT, EXPLOIT, YARA, RHA1, USER, CLOUD |
| cloud_last_lookup     | string  | Timestamp when the last response from Spectra Intelligence was received (if the sample resides on the appliance). Returns null if the request has been made directly to Spectra Intelligence, or if Spectra Intelligence has not been queried for local samples. |
| data_source           | string  | Indicates the source of the provided data set - either the appliance or Spectra Intelligence. |
| av_scanners           | object  | Returned only if the `av_scanners=1` parameter is included in the request. Provides information about AV scanner count, matches, and percentage for the requested sample. Corresponds to the `av_scanners_summary` object from the [Sample Details API](./full-report-api.md) response. |

**Response Status Codes**

| CODE | DESCRIPTION                                                  |
| :--- | :----------------------------------------------------------- |
| 200  | This response is returned even when the sample is not found on the appliance. |
| 403  | This response is returned when the request isn’t authenticated. |
| 404  | Invalid or malformed hash.                                   |
| 429  | Too many requests (daily Spectra Intelligence query max limit reached). |
| 503  | Service unavailable (Spectra Intelligence API-related errors, i.e., Unauthorized). |
