Skip to main content

Getting started with Spectra Intelligence

This guide walks you through your first Spectra Intelligence API call — a file reputation lookup by hash. You will authenticate, send a request, and interpret the response.

What you'll accomplish:

  • Obtain your API credentials
  • Make your first file reputation request
  • Parse and understand the response

Prerequisites​

Before you begin:

  • A Spectra Intelligence account with API access
  • Your API credentials (username and password)
  • curl or Python 3 installed on your machine

If you do not have an account, contact ReversingLabs sales to request access or an evaluation.

Step 1: Get your API credentials​

Your Spectra Intelligence API credentials (username and password) are provided by ReversingLabs Support when your account is activated. These credentials are used for HTTP Basic Authentication on all API requests.

All API requests must be made over HTTPS to data.reversinglabs.com.

Step 2: Make your first file reputation request​

The simplest API call is a file hash reputation lookup using the TCA-0101 endpoint. It accepts an MD5, SHA1, or SHA256 hash and returns a classification verdict instantly.

Using curl:

curl -u "your-username:your-password" \
  "https://data.reversinglabs.com/api/databrowser/rl_data/query/sha1/list?format=json" \
  -H "Content-Type: application/json" \
  -d '{"rl": {"query": {"hash_type": "sha1", "hashes": ["3395856ce81f2b7382dee72602f798b642f14d45"]}}}'

Using Python:

import requests

username = "your-username"
password = "your-password"

hashes = ["3395856ce81f2b7382dee72602f798b642f14d45"]

url = "https://data.reversinglabs.com/api/databrowser/rl_data/query/sha1/list?format=json"
payload = {"rl": {"query": {"hash_type": "sha1", "hashes": hashes}}}

response = requests.post(url, auth=(username, password), json=payload)
print(response.json())

You can also use the ReversingLabs Python SDK for a higher-level interface to all Spectra Intelligence APIs.

Step 3: Parse the response​

A successful response returns a JSON object with the file classification:

{
  "rl": {
    "entries": [
      {
        "hash_type": "sha1",
        "hash_value": "3395856ce81f2b7382dee72602f798b642f14d45",
        "classification": {
          "classification": "MALICIOUS",
          "factor": 5,
          "scan_results": []
        }
      }
    ]
  }
}

Key fields:

  • classification.classification — MALICIOUS, SUSPICIOUS, GOODWARE, or UNKNOWN
  • classification.factor — Confidence level (1–5, where 5 is highest)
  • scan_results — Detections from individual AV engines

If the hash is not in the database, the response returns UNKNOWN.

Troubleshooting​

If your request fails, check the HTTP status code:

  • 401 Unauthorized — Invalid credentials. Verify your username and password.
  • 403 Forbidden — Your account does not have access to this endpoint. Contact support.
  • 429 Too Many Requests — Daily or monthly quota exceeded. Daily quotas reset at 00:00 UTC.

For a complete list of response codes and error handling, see General Information.

Next steps​

Now that you've made your first API call, explore the full capabilities of Spectra Intelligence: