The API adheres to the REST standard using resource-oriented URLs. All responses are JSON-encoded, follow standard HTTP response codes, and require authentication. The current API version is v1 and significant changes will increment the version number. The major version is part of the URL structure.
OAuth2 Bearer tokens authenticate API access. Tokens expire after 5 minutes and clients should retrieve a new token per request. Unauthorized access triggers a 401 Unauthorized error The API exclusively operates over HTTPS, HTTP requests are rejected.
Standard HTTP response codes indicate API success or failure. Codes in the 2xx range signify success, while 4xx codes denote request-side errors like missing or invalid parameters. Codes in the 5xx range indicate server errors. Certain responses contain a nullable error field, revealing any issues on the request. Access the API example kit here for Python examples on file submission, fetching analysis results, executing searches, and more. The accompanying README explains environment setup, dependencies, and authentication.
Threatray relies on fundamental entities across both API and UI: sample, analysis, code region, and function. Analyzing a sample yields one or more analyses, with each analysis comprising one or more code regions. Each code region may contain functions for binary files with code. The term code region generically refers to a potential code-containing section within an analysis, such as memory dumps from dynamic analysis or the static analysis of a submitted file.
These base entities are uniquely identifiable:
sample: Identified by Hash (MD5, SHA1, SHA256)analysis: Identified by UUIDcode region: Identified by analysis identifier, hash (MD5, SHA1, SHA256), PID, base addressfunction: Identified by code region identifier, effective address
API endpoints return adequate information on these entities, enabling subsequent API calls, like fetching an analysis report after searching for analyses.
Certain API actions initiate tasks lasting seconds or minutes, notably file/URL submissions and signature modifications. These actions return a task ID used to track task status as follows:
queued: Awaiting processinganalyzing: Undergoing processingdone: Successfully completedfailed: Unsuccessful due to an error