# Submissions API — Upload Files & URLs to Spectra Analyze

> Submit files and URLs to Spectra Analyze via REST API. POST /api/submit/file/ and /api/submit/url/ endpoints with tags, metadata, and analysis options.

## 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: ``, ``, ``, ``, ``, ``, ``.                                        |
| `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.                                                                  |

## 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.|

**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**.**


#### `analysis` dictionary structure (file and URL submissions)

```json
{
  "local_only": boolean
  "rl_dynamic_analysis": {
    "platform": Platforms,
    "geolocation": Geolocations,
    "locale": Locales
    "sample_name": string
    "internet_simulation": boolean
    "timeout": integer
  },
  "rl_auxiliary_analysis": boolean,
  "cloud": boolean,
  "cape": boolean,
  "cisco_secure_malware_analytics": {
    "profile": string
  },
  "cuckoo": boolean,
  "fireeye": {
    "profile": string
  },
  "joe": {
    "profile": string
  },
  "vmray_tcbase": boolean
}
```

All fields are optional. 

If `local-only` is set to `true`, the file is analyzed exclusively on the appliance. The sample is **not** sent to any configured integrations, sandboxes, or Spectra Intelligence services.  

Other analysis profiles are defined in **Administration → Integrations → Profiles**. If omitted or empty, automatic profile selection is applied. To exclude a service, omit it. For more information on ReversingLabs Cloud Sandbox configuration parameters, refer to the [Analysis Service Integrations](../dynamic-analysis.md#reversinglabs-cloud-sandbox) chapter.

#### 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`

#### `metadata` dictionary structure (file submissions)

```json
{
    "source_address": "string"
    "file_dir": "string",
    "file_origin_link": "string",
    "hostname": "string",
    "filter_name": "string",
    "source_tag": "string",
    "additional_data": "{"key": "value"}"
}
```

### Response format

```json
{
  "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.             |

---

## 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.         |
