Threat.Zone API Migration Guide

Public API Migration Guide (v1 → v3)

This guide helps users migrate from the old Public API (v1) to the new API (v3).

Overview of Changes

Aspect	Old (v1)	New (v3)
Base Path	/public-api/scan/*, /public-api/get/*	/submissions/*, /config/*
Authentication	Mixed (Bearer + Cookies)	Consistent Bearer token
Pagination	0-based with URL params (/:page/:jump)	1-based with query params (?page=&limit=)
Downloads	Separate routes	Nested under /submissions/:uuid/download/*

---

Authentication

Old Method

# Bearer token (most endpoints)
curl -H "Authorization: Bearer <api-key>" ...

# Cookie-based (some download endpoints)
curl --cookie "accesstoken=<token>" ...

New Method

# All endpoints now use Bearer token
curl -H "Authorization: Bearer <api-key>" ...

---

Submission Endpoints

Create Sandbox Submission (Dynamic + Static Analysis)

Old Request:

POST /public-api/scan/sandbox
Content-Type: multipart/form-data
Authorization: Bearer <api-key>

[email protected]
analyzeConfig=[{"metafieldId":"timeout","value":"120"}]
modules=["cdr"]
entrypoint=malware.exe
password=infected

New Request:

POST /submissions/sandbox
Content-Type: multipart/form-data
Authorization: Bearer <api-key>

[email protected]
environment=w10_x64
metafields=[{"key":"timeout","value":"120"}]
private=false
entrypoint=malware.exe
password=infected

Key Changes:

• analyzeConfig → metafields (with key/value instead of metafieldId/value)

• Added environment parameter (e.g., w10_x64, w11_x64)

• Removed extensionCheck (now automatic)

• Added private boolean flag

• Removed modules parameter - Use dedicated endpoints (/submissions/cdr) instead

---

Create Static-Only Submission

Old Request:

POST /public-api/scan/static-scan
Content-Type: multipart/form-data
Authorization: Bearer <api-key>

[email protected]
entrypoint=sample.exe
password=infected

New Request:

POST /submissions/static
Content-Type: multipart/form-data
Authorization: Bearer <api-key>

[email protected]
private=false
entrypoint=sample.exe
password=infected

---

Create CDR Submission

Old Request:

POST /public-api/scan/cdr
Content-Type: multipart/form-data
Authorization: Bearer <api-key>

[email protected]
entrypoint=document.docx
password=infected

New Request:

POST /submissions/cdr
Content-Type: multipart/form-data
Authorization: Bearer <api-key>

[email protected]
private=false
entrypoint=document.docx
password=infected

---

Create URL Submission

Old Request:

POST /public-api/scan/url-analysis
Content-Type: application/json
Authorization: Bearer <api-key>

{
  "url": "https://example.com",
  "private": false
}

New Request:

POST /submissions/url
Content-Type: application/json
Authorization: Bearer <api-key>

{
  "url": "https://example.com",
  "private": false
}

---

Response Format (All Submissions)

Old Response:

{
  "message": "You have successfully submitted a submission.",
  "uuid": "02312c96-d287-420e-a7e5-c295bb264052"
}

New Response:

{
  "uuid": "02312c96-d287-420e-a7e5-c295bb264052",
  "message": "Submission created successfully",
  "sha256": "a1b2c3d4e5f6..."
}

---

Query Endpoints

Get Submission Details

Old Request:

GET /public-api/get/submission/:uuid
Authorization: Bearer <api-key>

New Request:

GET /submissions/:uuid
Authorization: Bearer <api-key>

---

List Submissions

Old Request:

# List my submissions (page 0, 20 items per page)
GET /public-api/get/my-submissions/0/20
Authorization: Bearer <api-key>

New Request:

# List submissions with filters (page 1, 20 items per page)
GET /submissions?page=1&limit=20
Authorization: Bearer <api-key>

New Query Parameters:

Parameter	Type	Description
page	number	Page number (1-based)
limit	number	Items per page
level	string[]	Filter by threat level (malicious, suspicious, benign, unknown)
type	string	Filter by type (file, url)
sha256	string	Search by SHA256 hash (64 characters)
filename	string	Search by filename
startDate	ISO 8601	Filter from date
endDate	ISO 8601	Filter to date
private	boolean	Filter by privacy
tags	string[]	Filter by tags

Example:

GET /submissions?page=1&limit=10&type=file&level=malicious,suspicious&startDate=2025-01-01

---

Search by SHA256 Hash

Old Request:

GET /public-api/get/:hash/0/20
Authorization: Bearer <api-key>

New Request:

GET /submissions/search/sha256/:sha256
Authorization: Bearer <api-key>

Note: The new API only supports SHA256 hash search. MD5 and SHA1 searches are no longer available. You must use the full 64-character SHA256 hash.

---

Download Endpoints

Download Sample

Old Request:

GET /sample/:uuid
Authorization: Bearer <api-key>

New Request:

GET /submissions/:uuid/download/sample
Authorization: Bearer <api-key>

---

Download HTML Report

Old Request:

GET /htmlreport/:submission
Cookie: accesstoken=<token>

New Request:

GET /submissions/:uuid/download/html-report
Authorization: Bearer <api-key>

---

Download PCAP

Old Request:

GET /pcap/:submission
Cookie: accesstoken=<token>

New Request:

GET /submissions/:uuid/download/pcap
Authorization: Bearer <api-key>

---

Download Generated YARA Rule

Old Request:

GET /generated-yara-rule/:submission
Cookie: accesstoken=<token>

New Request:

GET /submissions/:uuid/download/yara-rule
Authorization: Bearer <api-key>

---

Download Artifact

Old Request:

GET /artifact/:submission/:artifactId
Cookie: accesstoken=<token>

New Request:

GET /submissions/:uuid/download/artifact/:artifactId
Authorization: Bearer <api-key>

---

Get Screenshot (URL Analysis)

Old Request:

GET /screenshot/:uuid
Authorization: Bearer <api-key>

New Request:

GET /submissions/:uuid/screenshot
Authorization: Bearer <api-key>

---

Get Media Files (Screenshots, Videos)

Old Request:

GET /media/:uuid/:fileId
Authorization: Bearer <api-key>

New Request:

# List all media files
GET /submissions/:uuid/media
Authorization: Bearer <api-key>

# Get specific media file
GET /submissions/:uuid/media/:fileId
Authorization: Bearer <api-key>

---

Configuration Endpoints

Get Metafields Configuration

Old Request:

GET /public-api/constants/metafields
Authorization: Bearer <api-key>

New Request:

# Get all metafields (grouped by scan type)
GET /config/metafields
Authorization: Bearer <api-key>

# Get metafields for specific scan type
GET /config/metafields/sandbox
GET /config/metafields/static
GET /config/metafields/cdr
GET /config/metafields/url
Authorization: Bearer <api-key>

---

Get Available Environments

New Endpoint (no v1 equivalent):

GET /config/environments
Authorization: Bearer <api-key>

Returns list of available operating systems for sandbox analysis.

---

User Info Endpoints

Get Current User Info

Old Request:

GET /public-api/me
Authorization: Bearer <api-key>

New Request:

GET /me
Authorization: Bearer <api-key>

---

Deprecated Endpoints

The following endpoints are no longer available in v3:

Old Endpoint	Notes
GET /public-api/get/submission/:uuid/varist-hybrid-analyzer-results	Deprecated
GET /public-api/get/submission/:uuid/analysis-artifacts	Use /submissions/:uuid response
GET /public-api/get/submission/:uuid/config-extractor-results	Deprecated
GET /public-api/get/submission/:uuid/dns	Data in network report
GET /public-api/get/submission/:uuid/http	Data in network report
GET /public-api/get/submission/:uuid/tcp	Data in network report
GET /public-api/get/submission/:uuid/udp	Data in network report
GET /public-api/get/submission/:uuid/threats	Data in indicators report
GET /public-api/get/public-submissions/:page/:jump	Use /submissions with filters
GET /private/*	Internal only, not exposed
GET /additionalFiles/:uuid/:fileId	Deprecated
GET /parts/:uuid?files=...	Deprecated
GET /exportable-parts/:uuid	Deprecated
GET /cdr/:submission	Use /submissions/:uuid/download/cdr-sanitized

---

Quick Migration Checklist

• Update base URLs from /public-api/* to /submissions/*, /config/*

• Replace cookie-based auth with Bearer token

• Update pagination from 0-based URL params to 1-based query params

• Update download URLs to nested format (/submissions/:uuid/download/*)

• Update submission creation request bodies:

  • analyzeConfig → metafields with key/value format

  • Add environment parameter for sandbox

  • Add private boolean if needed

• Update response parsing (new sha256 field in creation response)

• Remove deprecated endpoint calls

• Test all endpoints after migration

---

Example: Full Workflow

Old Workflow

# 1. Submit file
RESPONSE=$(curl -X POST /public-api/scan/sandbox \
  -H "Authorization: Bearer $API_KEY" \
  -F "[email protected]" \
  -F 'analyzeConfig=[{"metafieldId":"timeout","value":"120"}]')
UUID=$(echo $RESPONSE | jq -r '.uuid')

# 2. Poll for completion
curl -X GET "/public-api/get/submission/$UUID" \
  -H "Authorization: Bearer $API_KEY"

# 3. Download report
curl -X GET "/htmlreport/$UUID" \
  --cookie "accesstoken=$TOKEN" \
  -o report.html

New Workflow

# 1. Submit file
RESPONSE=$(curl -X POST /submissions/sandbox \
  -H "Authorization: Bearer $API_KEY" \
  -F "[email protected]" \
  -F "environment=w10_x64" \
  -F 'metafields=[{"key":"timeout","value":"120"}]')
UUID=$(echo $RESPONSE | jq -r '.uuid')

# 2. Poll for completion
curl -X GET "/submissions/$UUID" \
  -H "Authorization: Bearer $API_KEY"

# 3. Download report
curl -X GET "/submissions/$UUID/download/html-report" \
  -H "Authorization: Bearer $API_KEY" \
  -o report.html

---

Support

If you encounter issues during migration, please contact support with:

• Your old API request format

• The error message you're receiving

• Your expected behavior