PolySwarm RESTful API

RESTful API endpoints for interacting with the PolySwarm Customer APIs.

Getting Started

Using the API

PolySwarm's API provides a RESTful interface for various PolySwarm features. If you'd like to report an issue or provide feedback for this page, please contact customersuccess@polyswarm.io

The PolySwarm API is available at https://api.polyswarm.network/v3

For the rest of this document, the base API URL will not be included in any endpoints (e.g., the branch for search will be described as /v3/search rather than https://api.polyswarm.network/v3/search). You will be responsible for adding the correct base API URL.

The overview of the API Endpoints will include required and optional parameters, with a curl example.

Community (free) users have a limit of 60 calls per hour, Paying Enterprise Customers have a limit of 1000 calls per second. Each feature (i.e. Scanning) may have its own set monthly quota, and utilize a daily or monthly api limit too. See the team's usage page to better understand these numbers.

Authentication

Every API request must include an HTTP Authorization Header with an API key.

Locate the api_key for the User/Team from here

Example:

curl -X GET -H "Authorization: $API_KEY" 'https://api.polyswarm.network/v3/search/url?url=https%3A%2F%2Fpolyswarm.io&community=default'

Retrieve account information

Account details

/v3/public/accounts/whois

Query Sample

curl https://api.polyswarm.network/v3/public/accounts/whois -H "Authorization: $POLYSWARM_API_KEY"

Account features and quotas

/v3/public/accounts

Query Sample

curl https://api.polyswarm.network/v3/public/accounts -H "Authorization: $POLYSWARM_API_KEY"

Pagination and Offset Handling

When interacting with paginated endpoints, each page of results consumes one quota unit.

Key Points on Pagination:

• The has_more flag indicates whether additional pages of results are available.
• If has_more=true, the response will include an encrypted offset value.
• For the first request, specify a limit parameter (e.g., limit=50). The server will return an offset value for the next page in the response.
• For subsequent requests, include the offset value returned by the server in the previous response. The server will always provide the next offset, which must be sent back unmodified in subsequent calls.

Example Initial Request

curl -H 'Authorization: <API_KEY>' 'https://api.polyswarm.network/v3/hunt/live/list?limit=50&timeout=30'

The response will include an offset value for the next page.

Example Subsequent Request

curl -H 'Authorization: <API_KEY>' 'https://api.polyswarm.network/v3/hunt/live/list?limit=50&timeout=30&offset=<OFFSET>'

Note: The offset is an encrypted token generated by the server. Clients must use it as-is and not attempt to modify it.

Hash Search and Collision Handling

For the Hash Search endpoint, the has_more flag will typically return false. However, consider the following:

• A sha256 collision is highly unlikely, but not impossible.
• Collisions are more probable with weaker hash algorithms like md5 or sha1.

To address potential risks:

• Use the has_more flag to manage collisions, particularly when working with md5 or sha1.
• Decide whether to rely on this flag based on your specific use case and risk tolerance.

Artifact Lookup

To retrieve the results of a scan or sandbox, you can do an artifact lookup. In the scanning/sandboxing sections we will remind you of this.

GET /v3/consumer/submission/default/{artifact_id}

Once the scan has completed the returned window_closed value will be true, if this value is false then the scan is still processing, so you will need to poll periodically. If the value failed is true then the scan has failed.

Scanning Artifacts

The following are the 3 sequential steps in a Scanning operation:

• POST Inform PolySwarm to start a scan, returns an artifact_id and pre signed AWS URL that the artifact can be uploaded to
• PUT Upload the artifact to the AWS URL location
• PUT Inform PolySwarm that the artifact is uploaded and to start the scan

Lastly, lookup the artifact for the verdict, follow this process here.

URL Scanning

POST /v3/instance

Inform PolySwarm to start a scan, returns an artifact_id and pre signed AWS URL that the file/url can be uploaded to

Body Schema (application/json)

Query Sample

curl -X POST -d '{
  "artifact_name": "https://www.google.com",
  "artifact_type": "URL",
  "scan_config": "most-time",
  "community": "default"
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY"  https://api.polyswarm.network/v3/instance

Here is a sample of how to scan a URL that is inside a QR Code image:

curl -X POST -d '{
  "artifact_name": "qrcode.png",
  "artifact_type": "URL",
  "community": "default",
  "preprocessing": {"type": "qrcode"}
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY"  https://api.polyswarm.network/v3/instance

PUT https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}

Provide the artifact to upload to the AWS URL.

Query Sample

curl -X PUT '<PRE_SIGNED_AWS_URL>' -d 'content=www.google.com'

PUT /v3/instance

Inform PolySwarm the upload is complete and to start the scan.

Query Parameters

Query Sample

curl -X PUT -H "Content-Type: application/json" https://api.polyswarm.network/v3/instance?id=49722305458696948 -H "Authorization: $API_KEY"

Lastly, lookup the artifact for the verdict, follow this process here.

File Scanning

POST /v3/instance

Inform PolySwarm to start a scan, returns an artifact_id and pre signed AWS url that the file needs to be placed into.

Body Schema (application/json)

Body / Preprocessing Schema (application/json)

|

Query Sample

Scan a file install.exe example:

curl -X POST -d '{
  "artifact_name": "install.exe",
  "artifact_type": "FILE",
  "community": "default"
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/instance

The file to scan is inside an encrypted zip:

curl -X POST -d '{
  "artifact_name": "install.exe",
  "artifact_type": "FILE",
  "community": "default",
  "preprocessing": {"type": "zip", "password": "password"}
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/instance

The file to scan is an encrypted PDF:

curl -X POST -d '{
  "artifact_name": "encrypted.pdf",
  "artifact_type": "FILE",
  "community": "default",
  "preprocessing": {"type": "pdf", "password": "s3cret"}
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/instance

PUT https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}

Provide the artifact to upload to the AWS URL.

Query Sample

curl --upload-file ./tests/eicar.yara "<PRE_SIGNED_AWS_URL>"

PUT /v3/instance

Inform PolySwarm the upload is complete and to start the scan.

Query Parameters

Query Sample

curl -X PUT https://api.polyswarm.network/v3/instance?id=49722305458696948 -H "Authorization: $API_KEY"

Lastly, lookup the artifact for the verdict, follow this process here.

Rescanning Artifacts

POST /v3/consumer/submission/default/rescan/sha256/{sha256}

Other Endpoints include: /v3/consumer/submission/default/rescan/md5/{md5} and /v3/consumer/submission/default/rescan/sha1/{sha1}

This endpoint can only be used to rescan files, for urls see rescan by id below.

Query Parameters

Query Sample

curl -X POST 'https://api.polyswarm.network/v3/consumer/submission/default/rescan/sha256/5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a?community=default&scan_config=more-time' -H "Authorization: $API_KEY"

Lastly, lookup the artifact for the verdict, follow this process here.

Rescanning Artifacts by ID

POST /v3/consumer/submission/{community}/rescan/{id}

Rescan an existing artifact by its artifact_id (also referred to as instance_id) rather than by hash. The community (default or private) is specified as part of the URL path, include this.

Path Parameters

Query Parameters

Query Sample

curl -X POST 'https://api.polyswarm.network/v3/consumer/submission/private/rescan/3147283219576984' -H "Authorization: $API_KEY"

Query Sample with scan-config in private

curl -X POST 'https://api.polyswarm.network/v3/consumer/submission/private/rescan/3147283219576984?scan_config=more-time' -H "Authorization: $API_KEY"

Lastly, lookup the artifact for the verdict, follow this process here.

Downloading

Download an Artifact

GET /v3/consumer/download/sha256/{sha256}

Other Endpoints include: /v3/consumer/download/sha256/{md5} and /v3/consumer/download/sha256/{sha1}

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/consumer/download/sha256/5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a?community=default' -H "Authorization: $API_KEY"

Download via id

GET /v3/instance/download

Tip: Can be used to download reports and files from a sandbox detonation, see sandboxing sections to retrieve the instance_id.

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/instance/download?instance_id=84432173138232095' -H "Authorization: $API_KEY"

Download Bundle

Create the Bundle

POST /v3/bundle

Body Schema (application/json)

Query Sample

curl -X POST "https://api.polyswarm.network/v3/bundle" \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instance_ids": ["51375268900310741", "58964500531258633"], "preserve_filenames": true, "filename": "output-archive.zip"}' \

Check Status of Bundle

GET /v3/bundle

Query Parameters

Query Sample

curl -X GET "https://api.polyswarm.network/v3/bundle?id=41476135624684596&community=private" -H "Authorization: $POLYSWARM_API_KEY"

Download the Bundle

GET https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}

Note: The previous GET command returns the PRE_SIGNED_AWS_URL once the report generation has been completed.

Query Sample

curl -o output-archive.zip -X GET 'https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}'

Reporting

Downloading Reports

PolySwarm provides the ability to generate and download HTML/PDF reports for Scanning and Sandboxing, these are separate reports.

The following are the 3 sequential steps in a report generation operation:

• POST Inform PolySwarm to start generating the report.
• GET Poll PolySwarm to understand when the report has finished generating.
• GET Download the report locally once generation is successful.

POST /v3/reports

Body Schema (application/json)

Query Sample Scan Report

curl -X POST -d '{"type": "scan", "format": "pdf", "template_metadata": {"includes": ["summary", "detections"]}, "instance_id": "97903321852386706"}'  -H "Content-Type: application/json" -H "Authorization: $API_KEY"  https://api.polyswarm.network/v3/reports

Query Sample Sandbox ZIP File

The below example downloads the report json and the pcap files in a single zip file.

curl -X POST -d '{"type": "sandbox_zip", "format": "zip", "template_metadata": {"sandbox_artifact_types": ["report", "pcap"]}, "sandbox_task_id": "97903321852386706"}'  -H "Content-Type: application/json" -H "Authorization: $API_KEY"  https://api.polyswarm.network/v3/reports

GET /v3/reports

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/reports?id=59403308938961820' -H "Authorization: $API_KEY"

GET https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}

Note: The previous GET command returns the PRE_SIGNED_AWS_URL once the report generation has been completed.

Query Sample

curl -o scan-97903321852386706.pdf -X GET 'https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}'

Report Templates

List templates

GET /v3/reports/templates/list

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/reports/templates/list' -H "Authorization: $API_KEY"

Create a template

POST /v3/reports/templates

Body Schema (application/json)

Query Sample

curl -X POST -d '{"template_name": "temptest", "primary_color": "ff0000", "includes": ["summary", "detections", "fileMetadata"]}'  -H "Content-Type: application/json" -H "Authorization: $API_KEY"  https://api.polyswarm.network/v3/reports/templates

Delete a templates

DELETE /v3/reports/templates

Query Parameters

Query Sample

curl -X DELETE 'https://api.polyswarm.network/v3/reports/templates?id=10512439389909571' -H "Authorization: $API_KEY"

Get template details

GET /v3/reports/templates

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/reports/templates?id=89035259732911602' -H "Authorization: $API_KEY"

Update a template

PUT /v3/reports/templates

NOTE: despite being a PUT endpoint, only fields passed in the JSON body are updated, the remaining fields retain their values. Query Parameters

Body Schema (application/json)

Query Sample

curl -X PUT -d '{"primary_color": "7bfa7f", "includes": ["summary", "detections", "fileMetadata"]}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" "https://api.polyswarm.network/v3/reports/templates?id=89035259732911602"

Upload template logo

PUT /v3/reports/templates/logo

A logo can be provided for an already created template. The image is only used in the first page of the PDF reports. Can be either a PNG or JPEG file, the max size allowed is 40 Kb, and the max resolution 960px x 960px.

Query Parameters

Body Parameters

The body has to be the binary data of the image. Max length allowed is 40 Kb.

Header Parameters

Query Sample

Having a file logo.jpg in the same folder were curl is executed:

curl -X PUT 'https://api.polyswarm.network/v3/reports/templates/logo?id=89035259732911602' --data-binary @logo.jpg -H "Content-Type: image/jpeg" -H "Authorization: $API_KEY"

Delete template logo

DELETE v3/reports/templates/logo

Query Parameters

Query Sample

curl -X DELETE 'https://api.polyswarm.network/v3/reports/templates/logo?id=89035259732911602' -H "Authorization: $API_KEY"

Download template logo

GET v3/reports/templates/logo

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/reports/templates/logo?id=89035259732911602' -H "Authorization: $API_KEY" --output /Users/John/Documents/logo.jpg

LLM Reports

LLM reports provide AI-generated analysis summaries for both scans and sandbox detonations using language models.

For this to work, the team plan must include access to downloads. This feature consumes one unit from the PolySwarm Intelligence quota per report generated, which covers both the create and download steps.

Create LLM Report

POST /v3/reports/llm

Creates an LLM report task that will generate an AI-powered analysis summary. The system automatically detects duplicate pending reports and returns the existing one instead of creating a duplicate.

Body Schema (application/json)

At least one of instance_id, cape_sandbox_task_id, or triage_sandbox_task_id is required. You may combine cape_sandbox_task_id and triage_sandbox_task_id together, optionally alongside instance_id, to generate a single unified report from multiple sources.

Query Sample for Scan Report

curl -X POST -d '{"instance_id": "97903321852386706", "community": "default"}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/reports/llm

Query Sample for Cape Sandbox Report

curl -X POST -d '{"cape_sandbox_task_id": "97903321852386706"}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/reports/llm

Query Sample for Triage Sandbox Report

curl -X POST -d '{"triage_sandbox_task_id": "97903321852386706"}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/reports/llm

Query Sample for Combined Cape + Triage Report

curl -X POST -d '{"cape_sandbox_task_id": "97903321852386706", "triage_sandbox_task_id": "12345678901234567"}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/reports/llm

Get LLM Report

GET /v3/reports/llm

Retrieve the status and details of an LLM report task. Use the id returned from the POST request.

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/reports/llm?id=12345678901234567&community=default' -H "Authorization: $API_KEY"

Searching

Hash Searching

GET /v3/search/hash/sha256

Other Endpoints include: /v3/search/hash/md5 and /v3/search/hash/sha1

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/search/hash/sha256?hash=5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a&community=default' -H "Authorization: $API_KEY"

View Scan History

GET /v3/search/instances

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/search/instances?hash=95531b268adee781f88c962f4b6d747ed82e1c1a58b636fdd925ca3ce31e9cf5&community=default' -H "Authorization: $API_KEY"

Known Good Binaries

Known Good Binaries (KGB) lets PolySwarm instantly recognize trusted, legitimate files. When a submitted or looked-up file exactly matches a trusted catalog by its sha256, PolySwarm marks it Known Good and skips scanning and sandboxing entirely — no scan or API quota is spent on files already known to be safe. Coverage is currently for Windows binaries, with additional platforms planned.

A known-good artifact instance in a scan, sandbox, or search response carries these additional fields:

A known-good file is not scanned or sandboxed; the scan and sandbox responses are returned directly from the hash match with a 0.0 score.

URL Searching

GET /v3/search/url

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/search/url?url=https%3A%2F%2Fpolyswarm.io&community=default' -H "Authorization: $API_KEY"

Metadata Searching

GET /v3/search/metadata/query

To understand how to build out a Metadata query see the How-To Guide.

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/search/metadata/query?query=artifact.sha256:5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a' -H "Authorization: $API_KEY"

Query Sample

The below query searches for artifacts related to emotet and only return the Triage TTP values, making use of the include option.

curl -X GET 'https://api.polyswarm.network/v3/search/metadata/query?include=triage_sandbox_v0.ttp&query=polyunite.malware_family%3AEmotet&community=default' -H "Authorization: $API_KEY"

IOC Searching

• Searching for Associated IOCs related to a Hash: This returns IOCs that were observed by our sandbox during analysis. These IP's and Domains are classified as C2 or malicious.
• Searching for Associated Hashes related to an IP, URL, imphash or MITRE TTP: This returns file hashes that were seen communicating with the specified IPs or domains in our sandbox — regardless of whether the communication was malicious or not.

Search for Associated IOCs

GET /v3/ioc/sha256/{sha256}

Other Endpoints include: /v3/ioc/md5/{md5} and /v3/ioc/sha1/{sha1}. Include the desired hash value in the endpoint to retrieve associated ip,domain, ttp and imphash results.

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/ioc/sha256/2a85d68c1c503d9b6efcf124ac7d7afc0f3a8a0543f5d6790ebd978f4e8468bd?community=default' -H "Authorization: $API_KEY"

Search for Associated Hashes

GET /v3/ioc/search

Query Parameters

Requires at least one of the values imphash, domain, ttp or ip in the query.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/ioc/search?ip=193.138.218.74&community=default' -H "Authorization: $API_KEY"

Sandboxing

List Sandboxes

GET /v3/sandbox/provider/list

List the provider_slug and vm_slug values for sandboxing a file and/or artifact.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/sandbox/provider/list' -H "Authorization: $API_KEY"

Sandboxing a File/URL

Want to know what files types are supported? See here

POST /v3/sandbox/sandboxtask/instance

Inform PolySwarm to start a sandbox, returns an id value in the json and pre signed AWS url that the file needs to be placed into. This is the same process for Sandboxing a File and Sandboxing a URL, as the process for URL will be to upload a file with the URL inside it.

Body Schema (application/json)

Body / Preprocessing Schema (application/json)

Query Sample

Here is a simple sandboxing POST request:

curl -X POST -d '{
  "artifact_name": "eicar.txt",
  "artifact_type": "FILE",
  "community": "default",
  "sandbox": "cape"
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/sandbox/sandboxtask/instance

Here is an example using the "preprocessing" argument to send an encrypted zip file:

curl -X POST -d '{
  "artifact_name": "target.zip",
  "artifact_type": "FILE",
  "community": "default",
  "sandbox": "cape",
  "preprocessing": {"type": "zip", "password": "password"}
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/sandbox/sandboxtask/instance

Here is an example using the "preprocessing" argument to sandbox an encrypted PDF:

curl -X POST -d '{
  "artifact_name": "encrypted.pdf",
  "artifact_type": "FILE",
  "community": "default",
  "sandbox": "cape",
  "preprocessing": {"type": "pdf", "password": "s3cret"}
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/sandbox/sandboxtask/instance

PUT https://s3.us-east-2.amazonaws.com/{PRE_SIGNED_AWS_URL}

Provide the file to upload to the AWS URL.

Query Sample

curl --upload-file ./tests/eicar.txt "<PRE_SIGNED_AWS_URL>"

PUT /v3/sandbox/sandboxtask/instance

Inform PolySwarm the upload is complete and to start the sandbox.

Query Parameters

Query Sample

curl -X PUT 'https://api.polyswarm.network/v3/sandbox/sandboxtask/instance?id=49722305458696948' -H "Authorization: $API_KEY"

Query Sample

curl -X PUT 'https://api.polyswarm.network/v3/sandbox/sandboxtask/instance?id=49722305458696948&community=private' -H "Authorization: $API_KEY"

Sandboxes have multiple returned statuses, these are listed below.

Query every 30 seconds to understand if the Sandbox session has been successful, see the Lookup Sandbox Task section below.

Sandboxing an Existing Artifact

POST /v3/sandbox/sandboxtask

Send an existing artifact to be sandboxed by providing its artifact id, and the chosen Sandbox provider.

Body Schema (application/json)

Query Sample

curl -X POST -d '{"artifact_id": "66885603025097785", "provider_slug": "cape"}'  -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/sandbox/sandboxtask

Lookup Sandbox Task

GET /v3/sandbox/sandboxtask

Lookup the results from the specified sandbox task.

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/sandbox/sandboxtask?community=default&sandbox_task_id=29603365297891589' -H "Authorization: $API_KEY"

Lookup Latest Sandbox Task

GET /v3/sandbox/sandboxtask/latest

Lookup the results from the most recent sandbox task that was run on the provided sha256 in the provided sandbox.

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/sandbox/sandboxtask/latest?community=default&sandbox=cape&sha256=5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a' -H "Authorization: $API_KEY"

Download Sandbox Artifact

To download Sandbox Artifacts like pcap, jarm or report files follow this section to download via instance_id.

Each file (pcap,report etc) will have its own instance_id, these can be found by using the "Lookup Sandbox Task" (/v3/sandbox/sandboxtask) command, and each file name will have an instance_id listed beside it.

List my Sandbox Tasks

GET /v3/sandbox/sandboxtask/my-tasks

Find all sandbox tasks that you or your team members have run in the chosen date range.

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/sandbox/sandboxtask/my-tasks?community=default' -H "Authorization: $API_KEY"

Search Sandbox Tasks

GET /v3/sandbox/sandboxtask/list

Find all sandbox tasks associated with a sha256 (i.e. each time that artifact was sandboxed).

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/sandbox/sandboxtask/list?sha256=5da5a1e3983982a92341953929d4c7726da65fe5125d264dd8932a870f2f154a' -H "Authorization: $API_KEY"

Notification Webhooks

Notification webhooks allow you to receive real-time notifications for events in PolySwarm, such as when sandbox analysis completes.

Create a Notification Webhook

POST /v3/notification/webhook

Body Schema (application/json)

Query Sample

curl -X POST -d '{
  "webhook_uri": "https://example.com/webhook",
  "secret": "your-secret-key",
  "status": "enabled",
  "events": ["sandbox_done"]
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/notification/webhook

Get a Notification Webhook

GET /v3/notification/webhook

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/notification/webhook?id=12345' -H "Authorization: $API_KEY"

Update a Notification Webhook

PUT /v3/notification/webhook

Query Parameters

Body Schema (application/json)

Query Sample

curl -X PUT -d '{
  "webhook_uri": "https://newexample.com/webhook",
  "status": "disabled"
}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/notification/webhook?id=12345

Delete a Notification Webhook

DELETE /v3/notification/webhook

Query Parameters

Query Sample

curl -X DELETE 'https://api.polyswarm.network/v3/notification/webhook?id=12345' -H "Authorization: $API_KEY"

List All Notification Webhooks

GET /v3/notification/webhook/list

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/notification/webhook/list?limit=50' -H "Authorization: $API_KEY"

Test a Notification Webhook

POST /v3/notification/webhook/test

Query Parameters

Query Sample

curl -X POST 'https://api.polyswarm.network/v3/notification/webhook/test?id=12345' -H "Authorization: $API_KEY"

Note: When this endpoint is called, a success response is returned, this is a success for the request, it does not mean the webhook url worked.

Hunting with Yara

Managing Yara Rulesets

Create Ruleset

POST /v3/hunt/rule

Create a new ruleset.

Body Schema (application/json)

Query Sample

curl -X POST -d '{"yara": "\/*\r\n This Yara ruleset is under the GNU-GPLv2 license (http:\/\/www.gnu.org\/licenses\/gpl-2.0.html) and open to any user or organization, as long as you use it under this license.\r\n\r\n*\/\r\n\r\nimport \"pe\"\r\n\r\nrule MirageStrings\r\n{\r\n meta:\r\n description = \"Mirage Identifying Strings\"\r\n author = \"Seth Hardy\"\r\n last_modified = \"2014-06-25\"\r\n \r\n strings:\r\n $ = \"Neo,welcome to the desert of real.\" wide ascii\r\n $ = \"\/result?hl=en&id=%s\"\r\n \r\n condition:\r\n  any of them\r\n}\r\n\r\nrule Mirage\r\n{\r\n meta:\r\n description = \"Mirage\"\r\n author = \"Seth Hardy\"\r\n last_modified = \"2014-06-25\"\r\n \r\n condition:\r\n MirageStrings\r\n}\r\n\r\nrule Mirage_APT\r\n{\r\n meta:\r\n Author = \"Silas Cutler\"\r\n Date = \"yyyy\/mm\/dd\"\r\n Description = \"Malware related to APT campaign\"\r\n Reference  = \"Useful link\"\r\n \r\n strings:\r\n $a1 = \"welcome to the desert of the real\"\r\n $a2 = \"Mirage\"\r\n $b = \"Encoding: gzip\"\r\n $c = \/\\\/[A-Za-z]*\\?hl=en\/\r\n\r\n condition: \r\n (($a1 or $a2) or $b) and $c\r\n}", "name": "test_rule"}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/hunt/rule

View Ruleset

GET /v3/hunt/rule

View the contents of the specified ruleset.

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/rule?id=15862162112430616' -H "Authorization: $API_KEY"

List Rulesets

GET /v3/hunt/rule/list

List all rulesets in your account

Query Parameters

The filters are conjunctive: a ruleset must match every one you send. Note they are spelled with underscores, unlike the hyphenated parameters on the Live Hunt results endpoint. Booleans are sent as 1 / 0.

favorites_only and exclude_favorites are inverses of each other. Sending both is a contradiction and is refused with a 400, not answered with an empty list.

Sorting

sort=active_first returns the rulesets that carry a Live Hunt first, newest first within each block. Omit it and the default order is newest first. active_first is the only value the endpoint accepts — any other value is refused rather than quietly ignored:

{"status": "error", "errors": null, "result": "Invalid sort: only 'active_first' is supported."}

The sort is applied server-side across the whole result set, not per page. An offset obtained under one order is not valid under the other; the endpoint refuses a cursor minted under a different sort.

Read livescan_id, not the position. The active-first rank uses the ruleset's stored hunt link, which is a broader test than the one livescan_id is rendered under. An older ruleset whose Live Hunt was stopped without clearing that link sorts into the leading block while still serializing livescan_id as null. Use the field to decide whether a ruleset is running.

Dedupe by id when paging. The active-first key changes as hunts start and stop. A ruleset whose hunt stops part-way through your walk drops into the idle block and is returned twice; one that starts part-way through moves up and is skipped for the rest of that walk. Starting again from the first page does not avoid this. The id on each row is unique and safe to dedupe with, but it is unordered, so never use it to resume or bound a walk.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/rule/list' -H "Authorization: $API_KEY"

curl -X GET 'https://api.polyswarm.network/v3/hunt/rule/list?status=active&favorites_only=1' -H "Authorization: $API_KEY"

Response Fields

Alongside the ruleset's identity, each row carries its tracking state:

new_results_count is a stored counter that PolySwarm refreshes on a schedule rather than a live count, and there is no per-request window parameter. new_results_counted_at marks when it was last refreshed. A null count means "no answer"; it is not the same as 0.

Update Ruleset

PUT /v3/hunt/rule

Query Parameters

Body Schema (application/json)

Query Sample

curl -X PUT -d '{"yara": "\/*\r\n This Yara ruleset is under the GNU-GPLv2 license (http:\/\/www.gnu.org\/licenses\/gpl-2.0.html) and open to any user or organization, as long as you use it under this license.\r\n\r\n*\/\r\n\r\nimport \"pe\"\r\n\r\nrule MirageStrings\r\n{\r\n meta:\r\n description = \"Mirage Identifying Strings\"\r\n author = \"Seth Hardy\"\r\n last_modified = \"2014-06-25\"\r\n \r\n strings:\r\n $ = \"Neo,welcome to the desert of real.\" wide ascii\r\n $ = \"\/result?hl=en&id=%s\"\r\n \r\n condition:\r\n  any of them\r\n}\r\n\r\nrule Mirage\r\n{\r\n meta:\r\n description = \"Mirage\"\r\n author = \"Seth Hardy\"\r\n last_modified = \"2014-06-25\"\r\n \r\n condition:\r\n MirageStrings\r\n}\r\n\r\nrule Mirage_APT\r\n{\r\n meta:\r\n Author = \"Silas Cutler\"\r\n Date = \"yyyy\/mm\/dd\"\r\n Description = \"Malware related to APT campaign\"\r\n Reference  = \"Useful link\"\r\n \r\n strings:\r\n $a1 = \"welcome to the desert of the real\"\r\n $a2 = \"Mirage\"\r\n $b = \"Encoding: gzip\"\r\n $c = \/\\\/[A-Za-z]*\\?hl=en\/\r\n\r\n condition: \r\n (($a1 or $a2) or $b) and $c\r\n}", "name": "yytest_rule4444"}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/hunt/rule?id=15862162112430616

Favorite Ruleset

PUT /v3/hunt/rule/favorite

Star or unstar a ruleset. The call is idempotent and works while a Live Hunt is running.

Query Parameters

Body Schema (application/json)

id and favorite must be sent in the body. Sending id in the query string is rejected with A valid rule id must be provided. community goes in the query string, and must not be sent in both places at once.

Query Sample

curl -X PUT -d '{"id":"46961337172843885","favorite":1}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" 'https://api.polyswarm.network/v3/hunt/rule/favorite'

Response

{"result": {"id": "46961337172843885", "favorite": true, "favorited_at": "2026-08-25T18:23:56.845109+00:00", "favorites_used": 1, "favorites_limit": 5}, "status": "OK"}

Favorites are shared by your whole team and the number you can hold at once is capped, so the response reports the team's usage against that cap. Starring a ruleset once the budget is spent returns an HTTP 400 carrying a machine-readable code and the same two counters:

{"status": "error", "errors": {"code": "FAVORITE_LIMIT", "favorites_used": 5, "favorites_limit": 5}}

Match on the code rather than on the human-readable message.

Delete Ruleset

DELETE /v3/hunt/rule

Delete the given ruleset.

Query Parameters

Query Sample

curl -X DELETE 'https://api.polyswarm.network/v3/hunt/rule?id=15862162112430616' -H "Authorization: $API_KEY"

Live Hunts

Start Live Hunt

POST /v3/hunt/rule/live

Start a Live Hunt using the given ruleset.

Body Schema (application/json)

Query Sample

curl -X POST -d '{"rule_id":"6992666340481223"}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/hunt/rule/live

Stop Live Hunt

DELETE /v3/hunt/rule/live

Stop the Live Hunt on a given ruleset.

Body Schema (application/json)

Query Sample

curl -X DELETE -d '{"rule_id":"6992666340481223"}' -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/hunt/rule/live

View Live Results of a Live Hunt

GET /v3/hunt/live/list

Query Parameters

There is no default window. Omit since, or send 0, and no time filter is applied at all: the endpoint pages over the whole retained history.

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/live/list?polyscore-upper=0.99' -H "Authorization: $API_KEY"

curl -X GET 'https://api.polyswarm.network/v3/hunt/live/list?livescan_id=72927285313305230' -H "Authorization: $API_KEY"

View a Singular Result

GET /v3/hunt/live

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/live?id=75570120079919313' -H "Authorization: $API_KEY"

Response Fields

Alongside the result's metadata and download link, this endpoint returns the yara strings behind the hit:

Delete Live Result

DELETE /v3/hunt/live/list

Body Schema (application/json)

Query Sample

curl -X DELETE -d '{"result_ids":["66625018770158663"]}'  -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/hunt/live/list

Historical Hunts

Start a Historical Hunt

POST /v3/hunt/historical

start a new Historical Hunt using the provided yara rules or existing ruleset file.

Body Schema (application/json)

Either rule_id or yara is required in the call.

Query Parameters

Query Sample

curl -X POST -d '{"rule_id":"24285974317896172"}'  -H "Content-Type: application/json" -H "Authorization: $API_KEY" https://api.polyswarm.network/v3/hunt/historical

Cancel an Historical Hunt

PUT /v3/hunt/historical

Stop a Historical Hunt. If it's already running, it will stop at the next batch interval.

Query Parameters

Query Sample

curl -X PUT 'https://api.polyswarm.network/v3/hunt/historical?' -H "Authorization: $API_KEY"

List Historical Hunts

GET /v3/hunt/historical/list

List the Historical Hunts in your account.

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/historical/list' -H "Authorization: $API_KEY"

View Historical Hunt Details for a Hunt

GET /v3/hunt/historical

Provides ability to download results as a csv file and see the ruleset contents.

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/historical?id=75570120079919313' -H "Authorization: $API_KEY"

Response Fields

Alongside the hunt's status and results, the response records which ruleset the hunt came from:

source_rule_changed has three states, not two. true and false answer the question; null means the server could not answer it, because the hunt was started from raw Yara or predates provenance tracking. Do not render null as "unchanged" - rule_id is null for those same hunts.

View Historical Hunt Results

GET /v3/hunt/historical/results/list

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/historical/results/list?id=75570120079919313' -H "Authorization: $API_KEY"

View a Singular Historical Hunt Result

GET /v3/hunt/historical/results

Query Parameters

Query Sample

curl -X GET 'https://api.polyswarm.network/v3/hunt/historical/results?id=75570120079919313' -H "Authorization: $API_KEY"

Response Fields

This endpoint returns matched_strings and matched_strings_dropped in the same shape as the Live Hunt singular result above. See Matched Strings.

Delete a Historical Hunt

DELETE /v3/hunt/historical

Query Parameters

Query Sample

curl -X DELETE 'https://api.polyswarm.network/v3/hunt/historical?id=1371741361996923' -H "Authorization: $API_KEY"

Delete Historical Hunt Results

DELETE /v3/hunt/historical/results/live

Body Schema (application/json)

Query Sample

curl -X DELETE -d '{"result_ids":["66625018770158663"]}'  -H "Content-Type: application/json" https://api.polyswarm.network/v3/hunt/historical/results/list -H "Authorization: $API_KEY"

Matched Strings

Hunt results carry the yara strings that made the rule fire, so a result shows why a rule matched rather than only which rule it was. Both the Live Hunt and Historical Hunt singular-result endpoints return the same two fields.

"matched_strings": [{"offset": 69, "identifier": "$u", "length": 9, "data": "test_live", "truncated": false}],
"matched_strings_dropped": 0

data is left exactly as yara rendered it and is deliberately not decoded: a hex string comes back as byte pairs, a text string as ASCII with \xNN escapes, and only yara knows which applies. truncated over-reports at exactly the cap, because nothing in the output distinguishes a match that ended there from one that was cut short.

Matched strings are only on the singular-result endpoints. /v3/hunt/live/list and /v3/hunt/historical/results/list always send null for both fields rather than fetch the evidence for every row. Request the single result to get the strings.

Reading the three states

matched_strings has three states, and collapsing them will give you the wrong answer:

matched_strings_dropped exists so that a shortened list is not mistaken for a complete one — a consumer reading twelve entries would otherwise conclude the rule hit twelve times when it hit thirty-one. A non-null count always means "the list you have is short by this much", and it never accompanies an empty list, because the first string of a match is never withheld.

A null count carries the same ambiguity as the list itself. On a singular-result endpoint it means nothing was withheld; anywhere else it means nothing looked. It is never a promise that the evidence is complete.