# 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.malwation.com/threatzone/threat.zone-api-migration-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.