# URL Submission API (TCA-0404) — Spectra Intelligence

> Submit URLs to TCA-0404 for analysis including content download, screenshots, and dynamic analysis in Spectra Intelligence.

This service provides comprehensive analysis of submitted URLs through advanced web intelligence gathering and threat detection capabilities. The analysis combines static file analysis, dynamic behavioral assessment, network infrastructure mapping, and visual documentation to deliver complete threat intelligence.

The service supports three analysis workflows controlled by the optional `analysis_type` parameter:

- **(parameter omitted)**: Downloads content from the submitted URL and from URLs found on that page. This is the most comprehensive analysis mode.
- **`light`**: Downloads only the content from the submitted URL, skipping any linked content.
- **`fileless`**: Skips downloading content entirely, focusing only on URL reputation and infrastructure analysis.

### Key Functionalities

- Downloads and analyzes up to 50 samples per analysis (each up to 100 MB), with files processed through the ReversingLabs threat detection pipeline
- Captures and analyzes the Document Object Model (DOM) to identify malicious JavaScript, hidden content, and dynamic page elements
- Takes screenshots of analyzed pages for visual threat assessment and evidence collection
- Resolves serving IP addresses, DNS records, and SSL/TLS certificate details for comprehensive infrastructure analysis
- Gathers domain registration and ownership data to support attribution and threat actor profiling
- Executes URLs in controlled sandbox environments to observe runtime behavior and detect evasive threats
- Follows and documents complete redirection paths while analyzing each step in the chain
- Files are downloaded only from the submitted URL, no recursion (crawl depth = 1) e.g. if a user submitted the following URL: `http://www.example.com/freshcontent`, only that URL will be crawled and `http://www.example.com/freshcontent/newest` will not

### Report Availability

The report about the performed analysis and reputation information for the downloaded samples can be retrieved via the TCA-0403 URL Threat Intelligence service, along with a list of samples that were downloaded from the submitted URL.

Reports become available before file analysis finishes. However, if you requested file downloads (default or `light` workflow), keep in mind that downloaded samples might take around 30 minutes from submission to have updated classification and metadata. When the processing is completed, the TCA-0403 URL Analysis Notification service will publish an alert and the analysis report will contain the latest data.

Querying the TCA-0403 `/report` endpoint before the analysis is complete may return mixed data: the `last_analysis` object will be populated with new information, while the `statistics` object may still show old classification data. Within 10 minutes from submission, the `/downloaded_files` endpoint returns a list of downloaded samples, but their metadata and classifications will be populated with information obtained during previous URL analyses.

### Privacy and Data Handling

All submitted URLs and downloaded files are treated as public data and accessible to all Spectra Intelligence users.

For other queries (such as retrieving threat intelligence without submitting for analysis), information may be shared with third-party reputation sources as part of the lookup process. For comprehensive privacy considerations and best practices when using networking APIs, see [Privacy & Data Sharing](/General/SecurityAndAccessControl/Privacy#urls).

## Analyze URL Query

This query requests an analysis of the submitted URL. Only one URL can be submitted per request. Submitting the same URL consecutively does not initiate new analyses until the first analysis has completed.

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/network-threat-intelligence/post/apinetworkingurlv1analyzequerypost_format" />

### Request

```
POST /api/networking/url/v1/analyze/query/{format}
```

Path parameters:

- `format`
  - Defines the format of the request body (XML or JSON)
  - Required

#### Request body

```json
{
  "rl": {
    "query": {
      "url": "string",
      "response_format": "string",
      "analysis_type": "string"
    }
  }
}
```

- `url`
  - Specifies the URL for which the analysis will be started. Provide the full URL of a website including the protocol (`https://www.example.org`). Only `http` and `https` protocols are supported. If the protocol is missing from the submitted URL, `http` will be automatically prepended to the URL. Note that URL normalization is performed during request submission, so duplicate and empty elements in the URL may be automatically removed or converted.
  - Required
- `response_format`
  - An optional parameter that allows choosing the response format. Supported values are `xml` and `json`; the default is `xml`.
  - Optional
- `analysis_type`
  - Controls content download. By default, the service downloads content from the submitted URL and from URLs found on that page. Use `light` to download only the content from the submitted URL. Use `fileless` to skip downloading content entirely.
  - Optional

### Response

The response includes the submitted URL in a normalized format, information about the status of the analysis, and the `analysis_id` that can be further used to get a list of samples downloaded during that specific analysis.

``` json
{
  "rl": {
    "requested_url": "string",
    "status": "string",
    "analysis_id": "string"
  }
}
```

- `requested_url`
  - The submitted URL in normalized format.
- `status`
  - Indicates the status of the analysis job for the requested URL. Returns **started** when the analysis job has been successfully initiated. No other status indicators are currently supported.
- `analysis_id`
  - A 16 character string identifying the current analysis.

### Examples

This example is for analyzing the URL *https://www.myabandonware.com* using JSON as the POST payload format, and requesting that the response is in JSON as well. For faster analysis, it is set to perform the analysis without downloading any content.

#### Request

`/api/networking/url/v1/analyze/query/json`

``` json
{
  "rl": {
    "query": {
      "url": "https://www.myabandonware.com",
      "response_format": "json",
      "analysis_type": "fileless"
    }
  }
}
```

#### Response

``` json
{
  "rl": {
    "requested_url": "https://myabandonware.com/",
    "status": "started",
    "analysis_id": "159134594237612a"
  }
}
```

## Custom Response Status Codes

This API implements custom response status codes. Find a complete list of possible HTTP response codes and their descriptions in the [General](../../index.md#response-status-codes) section of the documentation.

| CODE | DESCRIPTION |
| :--- | :---------- |
| 403  | The server understood the request, but is refusing to fulfill it. A possible cause may be that the URL that was sent to analysis is already being analyzed. In this case, the API will also return an "Analysis in progress" message. |
