Submissions API

Submitting a File

POST /api/submit/file/

This endpoint allows users to submit a single file to the appliance for analysis using static and (optionally) dynamic services. Only one file can be submitted per request.

Request parameters

NAME	REQUIRED	TYPE	DESCRIPTION
file	Yes	file (binary)	The file to be uploaded for analysis. Only one file is allowed per request.
filename	No	string	Custom filename to assign. If omitted, the SHA1 or original filename is used.
tags	No	string (CSV)	Comma-separated user tags (case-sensitive). Spaces and underscores are distinct.
comment	No	string (HTML)	Visible in the UI. Supports: <p>, <br>, <a>, <strong>, <b>, <em>, <i>.
archive_password	No	string	Password for ZIP file. Archive must contain exactly one file. Only the extracted file is analyzed.
analysis	No	object (JSON)	Optional dictionary that defines which analyses are triggered. If omitted, automatic rules from Administration > Integrations apply.
metadata	No	object (JSON)	Optional metadata about file origin, connector, or source.

analysis dictionary structure

{
  "rl_dynamic_analysis": {
    "platform": "windows11",
    "geolocation": "us",
    "locale": "en-US"
  },
  "rl_auxiliary_analysis": true,
  "cloud": true,
  "cape": true,
  "cuckoo": false,
  "vmray_tcbase": true,
  "cisco_secure_malware_analytics": {
    "profile": "default"
  },
  "fireeye": {
    "profile": "some_profile"
  },
  "joe": {
    "profile": "linux"
  }
}

All fields are optional. Profiles are defined in Administration → Integrations → Profiles. If omitted or empty, automatic profile selection is applied. To exclude a service, omit it.

Supported values

• platform: windows7, windows10, windows11, macos_11, linux
• geolocation: us, uk, in, br, de, jp, sg, it, es, fr, tor
• locale: en-US, en-GB, pt-BR, de-DE, ja-JP, it-IT, es-ES, fr-FR

Response format

{
  "code": 201,
  "message": "Done.",
  "detail": {
    "id": 1,
    "sha1": "0000000000000000000000000000000000000000",
    "user": 1,
    "created": "2020-20-20T20:20:20.000000Z",
    "filename": "some_archive.zip"
  }
}

Response fields

FIELD NAME	DESCRIPTION
code	Status response code (e.g., 201).
message	Descriptive response message.
detail	Object with metadata about the submission.

detail fields:

FIELD NAME	DESCRIPTION
id	Submission task ID.
sha1	SHA1 hash of the uploaded or extracted file.
user	Internal user ID of the submitter.
created	UTC timestamp of submission creation.
filename	Final name assigned to the file.

---

Submitting a URL

POST /api/submit/url/

This endpoint allows users to submit a single URL for crawling and analysis. The downloaded content is analyzed as a ZIP archive.

Request parameters

NAME	REQUIRED	TYPE	DESCRIPTION
url	Yes	string	The URL to be crawled and analyzed. Must use HTTP or HTTPS.
crawler	No	string	Defines crawler behavior: local (private) or cloud (Spectra Intelligence). Defaults to local.
analysis	No	object (JSON)	Optional dictionary to trigger specific analyses. See file endpoint for structure.

analysis dictionary structure

{
  "rl_dynamic_analysis": {
    "platform": "windows11",
    "geolocation": "us",
    "locale": "en-US"
  },
  "rl_auxiliary_analysis": true,
  "cloud": true,
  "cape": true,
  "cuckoo": false,
  "vmray_tcbase": true,
  "cisco_secure_malware_analytics": {
    "profile": "default"
  },
  "fireeye": {
    "profile": "some_profile"
  },
  "joe": {
    "profile": "linux"
  }
}

All fields are optional. Profiles are defined in Administration → Integrations → Profiles. If omitted or empty, automatic profile selection is applied. To exclude a service, omit it.

Supported values

• platform: windows7, windows10, windows11, macos_11, linux
• geolocation: us, uk, in, br, de, jp, sg, it, es, fr, tor
• locale: en-US, en-GB, pt-BR, de-DE, ja-JP, it-IT, es-ES, fr-FR

note

If rl_dynamic_analysis is specified in analysis, the URL is also sent to Network Analysis, and the downloaded archive is sent to static and dynamic file analysis.

Response format

{
  "code": 201,
  "message": "Done.",
  "detail": {
    "id": 1,
    "sha1": "0000000000000000000000000000000000000000",
    "user": 1,
    "created": "2020-20-20T20:20:20.000000Z",
    "filename": "some_archive.zip"
  }
}

Response fields

FIELD NAME	DESCRIPTION
code	Status response code.
message	Informative message.
detail	Object with submission metadata.

detail fields:

FIELD NAME	DESCRIPTION
id	Submission ID.
sha1	SHA1 hash of the downloaded archive.
user	Submitter's internal user ID.
created	UTC timestamp of submission.
filename	Name of the archive.

---

Response Status Codes

CODE	DESCRIPTION
201	Submission accepted and queued for analysis.
400	Bad request. Validation error or missing/invalid parameters.
403	Authentication failed or token missing.
405	Appliance is in maintenance mode. Uploads disabled.
413	File or download exceeds configured size limits.
429	Too many submissions. Resource limits (RAM, queue, quota) exceeded.
503	Appliance disk usage too high. Uploads temporarily blocked.