PolySwarm Rest API v3

Rest API Endpoints for interacting with version 3 of 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 [email protected]

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.

Authentication

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

Locate the api_key for the User/Team from here

HTTP Header	Value
Authorization	`API Key`

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)

Parameter	Type	Required	Description
`artifact_name`	string	true	URL value to be scanned.
`artifact_type`	string	true	Defines the type, should be `URL`.
`scan_config`	string	false	Allows additional time for the scan, default if not provided, `default`, `more-time`, `most-time`.
`url-file`	string	false	Path of the file containing a single line of the URL to be scanned.
`community`	string	true	Name of the Community. Simplest to use `default` for the public community, or `private` for your Private Community.
`preprocessing`	object	false	Set to `{"type": "qrcode"}` if the URL is inside a QR Code image.

Query Sample

curl -X POST -d '{
  "artifact_name": "https://www.google.com",
  "artifact_type": "URL",
  "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

Parameter	Type	Required	Description
`id`	string	true	`artifact_id` that has been returned by the first `POST` command.

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)

Parameter	Type	Required	Description
`artifact_name`	string	true	Path of the File to be scanned.
`artifact_type`	string	true	Defines the type, should be `FILE`.
`preprocessing`	object	false	Preprocessing settings to be applied to the artifact. See schema table bellow.
`scan_config`	string	false	Allows additional time for the scan, default if not provided, `default`, `more-time`, `most-time`.
`community`	string	true	Name of the Community. Simplest to use `default` for the public community, or `private` for your Private Community.

Body / Preprocessing Schema (application/json)

Parameter	Type	Required	Description
`type`	string	true	Either `zip` or `qrcode`, the first mean the file is a zip that the server has to decompress to then scan the content (only one file inside allowed). "qrcode" means the file is a QR Code image with a URL as payload, and you want to scan the URL, not the actual file (artifact_type has to be "URL").
`password`	string	false	Use this password to decompress the zip file.

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

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

Parameter	Type	Required	Description
`id`	string	true	`artifact_id` that has been returned by the first `POST` command.

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}

Query Parameters

Parameter	Type	Required	Description
`hash-type`	string	false	Hash type to be searched on, default is `autodetect`.
`scan-config`	string	false	Configuration template to use, provides more time for the results to be returned, `default`, `more-time`, `most-time`.
`community`	string	true	Name of the Community. Simplest to use `default` for the public community, or `private` for your Private Community.

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.

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

Parameter	Type	Required	Description
`hash-type`	string	false	Hash type to be searched on, default is `autodetect`.
`destination`	string	false	Local Path where to store the downloaded files.
`community`	string	true	Name of the Community. Simplest to use `default` for the public community, or `private` for your Private Community.

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

Parameter	Type	Required	Description
`instance_id`	integer	true	`instance_id` of the item to download, often provided in the output of a previous query.

Query Sample

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

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)

Parameter	Type	Required	Description
`format`	string	true	pdf, html or zip.
`type`	string	true	`scan`, `sandbox`, or `sandbox_zip`.
`template_metadata`	object	false	Choose what to include in the report or zip file, separated by commas. When choosing a PDF or HTML report the options are: analysis, detections, droppedFiles, extractedConfig, fileMetadata, network, summary. If not included in body, the default is all items. EXAMPLE: `{"includes":["summary"]}`. When choosing a Sandbox ZIP file there are two optional values in the `template_metadata`, `zip_report_ids` and `sandbox_artifact_type`. The `zip_report_ids` are the ID's of the other reports already created to include in the zip file. The `sandbox_artifact_type` are a list of sandbox artifacts to include from: `report`,`raw_report`,`screenshot`,`recording`,`dropped_file`,`memory_dump`,`pcap` and `jarm`.
`instance_id`	integer	true	Required if generating a scanning report, this is the `artifact_id`.
`sandbox_task_id`	integer	true	Required if generating a sandboxing report or sandbox zip, this is the `sandbox_id`.

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

Parameter	Type	Required	Description
`id`	integer	true	`id` returned from the previous POST command.

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 PRESIGNEDAWS_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)

Parameter	Type	Required	Description
`template_name`	string	true	Name for the template.
`is_default`	boolean	false	If `true` this template will be the default template for the team.
`primary_color`	string	false	Six-character hex color code.
`footer_text`	string	false	Text to be displayed in the footer of each page. Up to 100 characters are allowed.
`last_page_text`	string	false	Text to be displayed on the last page. Up to 1000 characters are allowed.
`includes`	string	false	Array list of sections to include in the report. Can be one or more of: "analysis", "detections", "droppedFiles", "extractedConfig", "fileMetadata", "network", "summary".

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

Parameter	Type	Required	Description
`id`	integer	true	`id` value of the template.

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

Parameter	Type	Required	Description
`id`	integer	true	`id` value of the template.

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

Parameter	Type	Required	Description
`id`	integer	true	`id` value of the template.

Body Schema (application/json)

Parameter	Type	Required	Description
`template_name`	string	true	Name for the template.
`is_default`	boolean	false	If `true` this template will be the default template for the team.
`primary_color`	string	false	Six-character hex color code.
`footer_text`	string	false	Text to be displayed in the footer of each page. Up to 100 characters are allowed.
`last_page_text`	string	false	Text to be displayed on the last page. Up to 1000 characters are allowed.
`includes`	string	false	Array list of sections to include in the report. Can be one or more of: "summary", "detections", "fileMetadata", "network", "droppedFiles", "extractedConfig", "analysis".

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

Parameter	Type	Required	Description
`id`	integer	true	`id` value of the template

Body Parameters

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

Header Parameters

Parameter	Required	Description
`Content-Type`	true	Either `image/png` or `image/jpeg`

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

Parameter	Type	Required	Description
`id`	integer	true	`id` value of the template.

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

Parameter	Type	Required	Description
`id`	integer	true	`id` value of the template.

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

Searching

Hash Searching

GET /v3/search/hash/sha256

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

Query Parameters

Parameter	Type	Required	Description
`hash`	string	true	Hash (sha256,md5 or sha1) value to be searched.
`community`	string	true	Name of the Community. Simplest to use `default` for the public community, or `private` for your Private Community.
`hash-type`	string	false	Hash type to be searched on, default is `autodetect`.

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

Parameter	Type	Required	Description
`hash`	string	true	Hash (sha256,md5 or sha1) value to be searched.
`community`	string	true	Name of the Community. Simplest to use `default` for the public community, or `private` for your Private Community.

Query Sample

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

URL Searching

GET /v3/search/url

Query Parameters

Parameter	Type	Required	Description
`url`	string	true	URL value to be searched.
`community`	string	true	Name of the Community. Simplest to use `default` for the public community, or `private` for your Private Community.

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 build out the metadata query, see this page.

Query Parameters

Parameter	Type	Required	Description
`query`	string	true	Metadata query to search on.
`include`	string	false	Metadata field to include in results.
`exclude`	string	false	Metadata field to exclude in results.
`community`	string	true	Name of the Community. Simplest to use `default` for the public community, or `private` for your Private Community.

Query Sample

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

IOC Searching

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

Parameter	Type	Required	Description
`community`	string	true	Name of the Community. Simplest to use `default` for the public community, or `private` for your Private Community.

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

Parameter	Type	Required	Description
`community`	string	true	Name of the Community. Simplest to use `default` for the public community, or `private` for your Private Community.
`imphash`	string	false	imphash to see related hashes.
`domain`	string	false	domain to see related hashes.
`ttp`	string	false	MITRE ttp to see related hashes.
`ip`	string	false	IP to see related hashes.

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 artifact_id 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)

Parameter	Type	Required	Description
`artifact_name`	string	true	Path to File of the artifact to be sandboxed or URL string.
`artifact_type`	string	true	Defines the type, `FILE` to Sandbox a file, `URL` to Sandbox a URL.
`preprocessing`	object	false	Preprocessing settings to be applied to the artifact. See schema table bellow.
`provider_slug`	string	true	Name of the sandbox to detonate on. For URL Sandboxing only Triage is Supported.
`community`	string	true	Name of the Community. Simplest to use `default` for the public community, or `private` for your Private Community.
`vm_slug`	string	true	Slug name for the sandbox vm to use, for URL Sandboxing only Windows 10 on Triage is Supported.
`browser`	string	false	Optional value to choose the browser for URL detonation, only `edge` supported.

Body / Preprocessing Schema (application/json)

Parameter	Type	Required	Description
`type`	string	true	Either `zip` or `qrcode`, the first mean the file is a zip that the server has to decompress to then sandbox the content (only one file inside allowed). "qrcode" means the file is a QR Code image with a URL as payload, and you want to sandbox the URL, not the actual file (artifact_type has to be "URL").
`password`	string	false	Use this password to decompress the zip file.

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

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/instance

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

Query Parameters

Parameter	Type	Required	Description
`id`	string	true	`artifact_id` that has been returned by the first `POST` command.

Query Sample

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

Sandboxes have multiple returned statuses, these are listed below.

Status	What is it for?
`Success`	Finished processing correctly.
`Started`	Sandbox session has started.
`Collecting Data`	Sandbox session has been successful and data is being collected.
`Failed`	Sandbox session has failed, this can be due to many reasons.
`Pending`	Sandbox session is queued up and ready to start.
`Timed out`	Sandbox session has timed out and quota has not been reimbursed.
`Delayed`	Sandbox session has been delayed and will start soon.
`Failed with Quota Reimbursement`	Finished processing but failed, quota will be reimbursed.
`Timed out with Quota Reimbursement`	Delayed in the queue for too long, got timed out and then reimbursement.

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)

Parameter	Type	Required	Description
`artifact_id`	integer	true	`artifact_id` value for the artifact.
`provider_slug`	string	true	Sandbox provider name.
`vm_slug`	string	false	Slug name for the sandbox vm to use.

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

Parameter	Type	Required	Description
`community`	string	true	Name of the Community. Simplest to use `default` for the public community, or `private` for your Private Community.
`sandbox_task_id`	integer	true	sandbox task id value.

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

Parameter	Type	Required	Description
`community`	string	true	Name of the Community. Simplest to use `default` for the public community, or `private` for your Private Community.
`sha256`	string	true	Hash value to lookup.
`sandbox`	string	true	Name of the Sandbox, e.g. `cape`, `triage`.

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

Parameter	Type	Required	Description
`community`	string	true	Name of the Community. Simplest to use `default` for the public community, or `private` for your Private Community.
`sandbox`	string	false	Name of the sandbox to search on.
`start-date`	string	false	Start date to search.
`end-date`	string	false	End date to search.

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

Parameter	Type	Required	Description
`sha256`	string	true	Hash value to find related tasks.
`sandbox`	string	false	Sandbox name to search.
`start-date`	string	false	Start date for the search.
`end-date`	string	false	End date for the search.
`status`	string	false	Status of the sandbox task i.e. `PENDING`.

Query Sample

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

Hunting with Yara

Managing Yara Rulesets

Create Ruleset

POST /v3/hunt/rule

Create a new ruleset.

Body Schema (application/json)

Parameter	Type	Required	Description
`yara`	string	true	Yara values, escape the items.
`name`	string	true	Name of the ruleset.
`description`	string	false	Description for the ruleset.

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

Parameter	Type	Required	Description
`id`	integer	true	`ruleset id` value to view the contents.

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 Sample

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

Update Ruleset

PUT /v3/hunt/rule

Query Parameters

Parameter	Type	Required	Description
`id`	integer	true	`ruleset_id` that needs to be updated.

Body Schema (application/json)

Parameter	Type	Required	Description
`name`	string	false	New updated name for the ruleset.
`file`	string	false	New updated yara values, escaped.
`description`	string	false	New updated description.

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

Delete Ruleset

DELETE /v3/hunt/rule

Delete the given ruleset.

Query Parameters

Parameter	Type	Required	Description
`id`	integer	true	`ruleset_id` value to delete.

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)

Parameter	Type	Required	Description
`rule_id`	integer	true	`rule_id` of the ruleset to start a live hunt.

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)

Parameter	Type	Required	Description
`rule_id`	integer	true	`rule_id` of the ruleset to stop a live hunt/

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

Parameter	Type	Required	Description
`since`	integer	false	Time value (in seconds) for how far back to request results (default `1440`).
`rule-name`	integer	false	Name of the ruleset being used in the hunt.
`family`	string	false	Filter results based on the family name.
`community`	string	false	Filter results based community.
`polyscore-lower`	string	false	Polyscore lower bound for the hunt results.
`polyscore-upper`	string	false	Polyscore upper bound for the hunt results.

Query Sample

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

View a Singular Result

GET /v3/hunt/live

Query Parameters

Parameter	Type	Required	Description
`id`	integer	true	Provide the result id value.

Query Sample

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

Delete Live Result

DELETE /v3/hunt/live/list

Body Schema (application/json)

Parameter	Type	Required	Description
`result_ids`	integer	true	List of `ruleset_ids` for the live hunt results to be deleted.

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)

Parameter	Type	Required	Description
`rule_id`	integer	true	`rule_id` of the ruleset to start a historical hunt.
`yara`	string	true	Path of the yara file to start a historical hunt.

Either rule_id or yara is required in the call.

Query Parameters

Parameter	Type	Required	Description
`name`	string	false	Name of the ruleset to start an historical hunt.

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

Parameter	Type	Required	Description
`id`	integer	true	id of the historical hunt to stop.

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

Parameter	Type	Required	Description
`since`	integer	false	Value in seconds to look for Historical Hunts.

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

Parameter	Type	Required	Description
`id`	integer	true	historical hunt id to view details.

Query Sample

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

View Historical Hunt Results

GET /v3/hunt/historical/results/list

Query Parameters

Parameter	Type	Required	Description
`id`	integer	true	Historical hunt id.
`rule-name`	integer	false	Ruleset name to filter results.
`family`	integer	false	Family name to filter results.
`community`	string	false	Filter results based community.
`polyscore-lower`	integer	false	Polyscore lower bound for the results.
`polyscore-upper`	integer	false	Polyscore upper bound for the results.

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

Parameter	Type	Required	Description
`id`	integer	true	`result_id` value to view single result.

Query Sample

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

Delete a Historical Hunt

DELETE /v3/hunt/historical

Query Parameters

Parameter	Type	Required	Description
`id`	integer	true	hunt id of the historical hunt to delete it.

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)

Parameter	Type	Required	Description
`result_ids`	integer	true	`ruleset_id` of the historical hunt to delete results from it.

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"

PolySwarm Rest API v3

Getting Started

Using the API

Authentication

Retrieve account information

Account details

Account features and quotas

Pagination and Offset Handling

Key Points on Pagination:

Example Initial Request

Example Subsequent Request

Hash Search and Collision Handling

Artifact Lookup

Scanning Artifacts

URL Scanning

File Scanning

Rescanning Artifacts

Downloading

Download an Artifact

Download via id

Reporting

Downloading Reports

Report Templates

List templates

Create a template

Delete a templates

Get template details

Update a template

Upload template logo

Delete template logo

Download template logo

Searching

Hash Searching

View Scan History

URL Searching

Metadata Searching

IOC Searching

Search for Associated IOCs

Search for Associated Hashes

Sandboxing

List Sandboxes

Sandboxing a File/URL

Sandboxing an Existing Artifact

Lookup Sandbox Task

Lookup Latest Sandbox Task

Download Sandbox Artifact

List my Sandbox Tasks

Search Sandbox Tasks

Hunting with Yara

Managing Yara Rulesets

Create Ruleset

View Ruleset

List Rulesets

Update Ruleset

Delete Ruleset

Live Hunts

Start Live Hunt

Stop Live Hunt

View Live Results of a Live Hunt

View a Singular Result

Delete Live Result

Historical Hunts

Start a Historical Hunt

Cancel an Historical Hunt

List Historical Hunts

View Historical Hunt Details for a Hunt

View Historical Hunt Results

View a Singular Historical Hunt Result

Delete a Historical Hunt

Delete Historical Hunt Results

Articles in This Section

PolySwarm UI

Hunting

Emerging Threats