> For the complete documentation index, see [llms.txt](https://docs.malwation.com/threatzone/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.malwation.com/threatzone/threat.zone-api-migration-guide.md). # 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 ```bash # Bearer token (most endpoints) curl -H "Authorization: Bearer " ... # Cookie-based (some download endpoints) curl --cookie "accesstoken=" ... ``` #### New Method ```bash # All endpoints now use Bearer token curl -H "Authorization: Bearer " ... ``` *** ### Submission Endpoints #### Create Sandbox Submission (Dynamic + Static Analysis) **Old Request:** ```bash POST /public-api/scan/sandbox Content-Type: multipart/form-data Authorization: Bearer file=@malware.exe analyzeConfig=[{"metafieldId":"timeout","value":"120"}] modules=["cdr"] entrypoint=malware.exe password=infected ``` **New Request:** ```bash POST /submissions/sandbox Content-Type: multipart/form-data Authorization: Bearer file=@malware.exe 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:** ```bash POST /public-api/scan/static-scan Content-Type: multipart/form-data Authorization: Bearer file=@sample.exe entrypoint=sample.exe password=infected ``` **New Request:** ```bash POST /submissions/static Content-Type: multipart/form-data Authorization: Bearer file=@sample.exe private=false entrypoint=sample.exe password=infected ``` *** #### Create CDR Submission **Old Request:** ```bash POST /public-api/scan/cdr Content-Type: multipart/form-data Authorization: Bearer file=@document.docx entrypoint=document.docx password=infected ``` **New Request:** ```bash POST /submissions/cdr Content-Type: multipart/form-data Authorization: Bearer file=@document.docx private=false entrypoint=document.docx password=infected ``` *** #### Create URL Submission **Old Request:** ```bash POST /public-api/scan/url-analysis Content-Type: application/json Authorization: Bearer { "url": "https://example.com", "private": false } ``` **New Request:** ```bash POST /submissions/url Content-Type: application/json Authorization: Bearer { "url": "https://example.com", "private": false } ``` *** #### Response Format (All Submissions) **Old Response:** ```json { "message": "You have successfully submitted a submission.", "uuid": "02312c96-d287-420e-a7e5-c295bb264052" } ``` **New Response:** ```json { "uuid": "02312c96-d287-420e-a7e5-c295bb264052", "message": "Submission created successfully", "sha256": "a1b2c3d4e5f6..." } ``` *** ### Query Endpoints #### Get Submission Details **Old Request:** ```bash GET /public-api/get/submission/:uuid Authorization: Bearer ``` **New Request:** ```bash GET /submissions/:uuid Authorization: Bearer ``` *** #### List Submissions **Old Request:** ```bash # List my submissions (page 0, 20 items per page) GET /public-api/get/my-submissions/0/20 Authorization: Bearer ``` **New Request:** ```bash # List submissions with filters (page 1, 20 items per page) GET /submissions?page=1&limit=20 Authorization: Bearer ``` **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:** ```bash GET /submissions?page=1&limit=10&type=file&level=malicious,suspicious&startDate=2025-01-01 ``` *** #### Search by SHA256 Hash **Old Request:** ```bash GET /public-api/get/:hash/0/20 Authorization: Bearer ``` **New Request:** ```bash GET /submissions/search/sha256/:sha256 Authorization: Bearer ``` **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:** ```bash GET /sample/:uuid Authorization: Bearer ``` **New Request:** ```bash GET /submissions/:uuid/download/sample Authorization: Bearer ``` *** #### Download HTML Report **Old Request:** ```bash GET /htmlreport/:submission Cookie: accesstoken= ``` **New Request:** ```bash GET /submissions/:uuid/download/html-report Authorization: Bearer ``` *** #### Download PCAP **Old Request:** ```bash GET /pcap/:submission Cookie: accesstoken= ``` **New Request:** ```bash GET /submissions/:uuid/download/pcap Authorization: Bearer ``` *** #### Download Generated YARA Rule **Old Request:** ```bash GET /generated-yara-rule/:submission Cookie: accesstoken= ``` **New Request:** ```bash GET /submissions/:uuid/download/yara-rule Authorization: Bearer ``` *** #### Download Artifact **Old Request:** ```bash GET /artifact/:submission/:artifactId Cookie: accesstoken= ``` **New Request:** ```bash GET /submissions/:uuid/download/artifact/:artifactId Authorization: Bearer ``` *** #### Get Screenshot (URL Analysis) **Old Request:** ```bash GET /screenshot/:uuid Authorization: Bearer ``` **New Request:** ```bash GET /submissions/:uuid/screenshot Authorization: Bearer ``` *** #### Get Media Files (Screenshots, Videos) **Old Request:** ```bash GET /media/:uuid/:fileId Authorization: Bearer ``` **New Request:** ```bash # List all media files GET /submissions/:uuid/media Authorization: Bearer # Get specific media file GET /submissions/:uuid/media/:fileId Authorization: Bearer ``` *** ### Configuration Endpoints #### Get Metafields Configuration **Old Request:** ```bash GET /public-api/constants/metafields Authorization: Bearer ``` **New Request:** ```bash # Get all metafields (grouped by scan type) GET /config/metafields Authorization: Bearer # Get metafields for specific scan type GET /config/metafields/sandbox GET /config/metafields/static GET /config/metafields/cdr GET /config/metafields/url Authorization: Bearer ``` *** #### Get Available Environments **New Endpoint (no v1 equivalent):** ```bash GET /config/environments Authorization: Bearer ``` Returns list of available operating systems for sandbox analysis. *** ### User Info Endpoints #### Get Current User Info **Old Request:** ```bash GET /public-api/me Authorization: Bearer ``` **New Request:** ```bash GET /me Authorization: Bearer ``` *** ### 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 ```bash # 1. Submit file RESPONSE=$(curl -X POST /public-api/scan/sandbox \ -H "Authorization: Bearer $API_KEY" \ -F "file=@malware.exe" \ -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 ```bash # 1. Submit file RESPONSE=$(curl -X POST /submissions/sandbox \ -H "Authorization: Bearer $API_KEY" \ -F "file=@malware.exe" \ -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