# Related Domains API (TCA-0408) — Spectra Intelligence

> Use TCA-0408 to override URL classifications within your organization and manage existing overrides in Spectra Intelligence.

The Network Reputation User Override service enables URL classification overrides and override removals. Any URL can be overridden to malicious, suspicious, or known, and any URL classification override can be removed. Users can make up to a total of 100 overrides and override removals in a single request. Overrides are visible to all users within the same organization. The service also supports listing existing overrides.

## URL User Override Query

This query sends network data to be overridden, and returns a list of network locations that were successfully overridden along with a list of invalid network locations and a list of network locations for which the override was successfully removed. All the parameters must be passed in the request body (either as JSON or XML).

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

### Request

```
POST /api/networking/user_override/v1/query/{post_format}
```

- `post_format`
  - allows choosing between XML and JSON format in the POST payload

#### Request body

``` json
{
  "rl": {
    "query": {
      "user_override": {
        "override_network_locations": [
          {
            "network_location": "string",
            "type": "string",
            "TTL": "string",
            "classification": "string",
            "threat_level": "string",
            "categories": [
              "string"
            ]
          }
        ],
        "remove_overrides": [
          {
            "network_location": "string",
            "type": "string"
          }
        ]
      },
      "response_format": "string"
    }
  }
}
```

- `override_network_locations`
  - List of network locations that the user wants to override
  - Optional
- `network_location`
  - Network location that the user wants to override.
  - Required
- `type`
  - Type of URI that was listed in the `network_location` parameter. Supported types: `url`.
  - Required
- `TTL`
  - Specifies the duration (in seconds) for which an override is valid. It defines the lifespan of the override before it expires and needs to be reassessed or renewed. In case the TTL is not set, there will be no expiration.
  - Optional
- `classification`
  - Classification assigned to the URI in `network_location`. Allowed types correspond to the ReversingLabs classification scheme: `malicious`, `suspicious`, `known`, `unknown`.
  - Required
- `threat_level`
  - Malware severity indicator for suspicious and malicious URIs, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). In case the value is not set, default values will be assigned based on the classification of the URI. For known URIs, the allowed value is `0`. If the value is not set, the default value is `0`. For suspicious and malicious URIs, the allowed values are `1`, `2`, `3`, `4`, or `5`. If the value is not set, the default value is `5`. For unknown URIs, setting the value is not allowed, and the value will default to `None`.
  - Optional
- `categories`
  - List of categories that the URI in question belongs to. List items are strings. The strings are arbitrary values.
  - Optional
- `remove_overrides`
  - List of network locations that the user wants to remove overrides from. Items in this list are objects. An object must contain two fields: `network_location` and `type`. These fields take in the same types of values as their equivalents in the `override_network_locations` parameter.
  - Optional
- `response_format`
  - Allows choosing between XML and JSON format for the response. Default is `xml`.
  - Optional

The request body of the query **must** contain the `override_network_locations` field or the `remove_overrides` field or **both**.

### Response

```json
{
  "rl": {
    "user_override": {
      "created_overrides": [],
      "removed_overrides": []
    }
  }
}
```

`rl.user_override.created_overrides[]` and `rl.user_override.removed_overrides[]`

```json
{
  "network_location": "string",
  "type": "string",
  "ttl": 0,
  "classification": "string",
  "categories": [
    "string"
  ],
  "reason": "string",
  "threat_level": 0
}
```

- `created_overrides`
  - List of network locations for which overrides were created.
- `network_location`
  - The overridden URI.
- `type`
  - Type of URI that was listed in the `network_location` parameter.
- `TTL`
  - Duration (in seconds) specified by the user for which an override is valid. It defines the lifespan of the override before it expires and needs to be reassessed or renewed. In case the TTL is not set, there will be no expiration.
- `classification`
  - Classification that the user listed in the request.
- `threat_level`
  - Malware severity indicator for suspicious and malicious URIs, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). In case the value is not set, default values will be assigned based on the classification of the URI. For known URIs, the allowed value is `0`. If the value is not set, the default value is `0`. For suspicious and malicious URIs, the allowed values are `1`, `2`, `3`, `4`, or `5`. If the value is not set, the default value is `5`. For unknown URIs, setting the value is not allowed, and the value will default to `None`.
- `categories`
  - List of categories that the requested URI belongs to.
- `removed_overrides`
  - List of network locations from which overrides were removed, along with their type.
- `invalid_network_locations`
  - List of invalid network locations.

## List User URL Overrides Query

This query returns the list of overrides that the user has made.

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

### Request

```
GET /api/networking/user_override/v1/query/list_overrides?[format=xml|json]&next_network_location={next page SHA1}
```

#### Query parameters

- **next_network_location**: SHA1 hash of the next network location in the response. In case the response has reached the maximum number of entries for a single response (1000), paging is used.
- **format**: response format (JSON/XML)

### Response format

```json
{
  "rl": {
    "user_override": {
      "next_network_location": "string",
      "network_locations": []
    }
  }
}
```

-----------------------------------------------------------------------

`rl.user_override.network_locations[]`

```json
{
  "network_location": "string",
  "type": "string",
  "classification": "string"
}
```

- `network_location`
  - Network location (URI) that is overridden.
- `type`
  - Type of network location. Currently, only URLs are supported.
- `classification`
  - Classification assigned to the URI in `network_location`. Allowed types correspond to the ReversingLabs classification scheme: `malicious`, `suspicious`, `known`, `unknown`.
- `expiration_time`
  - The specific time and date when the override will expire, calculated based on the TTL value provided. If the TTL is not set, the expiration_time will indicate no expiration.
- `threat_level`
  - Malware severity indicator for suspicious and malicious URIs, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). In case the value is not set, default values will be assigned based on the classification of the URI. For known URIs, the allowed value is `0`. If the value is not set, the default value is `0`. For suspicious and malicious URIs, the allowed values are `1`, `2`, `3`, `4`, or `5`. If the value is not set, the default value is `5`. For unknown URIs, setting the value is not allowed, and the value will default to `None`.

-----------------------------------------------------------------------

## Examples

### Example 1

This request assigns an override to two network locations, and removes an existing override from a third network location. One of the new overrides is invalid.

Request:

```
/api/networking/user_override/v1/query/json
```

``` json
{
  "rl": {
    "query": {
      "user_override": {
        "override_network_locations": [
          {
            "network_location": "https://location-example.com",
            "type": "url",
            "classification": "malicious",
            "categories": [
              "phishing"
            ]
          },
          {
            "network_location": "http://test.com",
            "type": "url",
            "classification": "suspicious"
          }
        ],
        "remove_overrides": [
          {
            "network_location": "https://example.com",
            "type": "url"
          }
        ]
      },
      "response_format": "json"
    }
  }
}
```

Response:

``` json
{
  "rl": {
    "user_override": {
      "created_overrides": [
        {
          "network_location": "https://location-example.com",
          "type": "url",
          "classification": "malicious",
          "categories": [
            "phishing"
          ]
        }
      ],
      "removed_overrides": [
        {
          "network_location": "https://example.com",
          "type": "url"
        }
      ],
      "invalid_network_locations": [
        "http://test.com"
      ]
    }
  }
}
```

### Example 2

This request returns a list of overrides by the user.

Request:

```
/api/networking/user_override/v1/query/list_overrides?format=json
```

Response:

``` json
{
  "rl": {
    "user_override": {
      "network_locations": [
        {
          "network_location": "https://location-example.com",
          "type": "url",
          "classification": "malicious"
        }
      ],
      "next_network_location": "9865c7ecda437034e1513cc43ae9a1f6f334bb7f"
    }
  }
}
```

### Example 3

This request returns a list of overrides by the user, in paginated form.

Request:

```
/api/networking/user_override/v1/query/list_overrides?next_network_location=9865c7ecda437034e1513cc43ae9a1f6f334bb7f&format=json
```

Response:

``` json
{
  "rl": {
    "user_override": {
      "network_locations": [
        {
          "network_location": "https://location-example.com",
          "type": "url",
          "classification": "malicious"
        }
      ],
      "next_network_location": null
    }
  }
}
```

## 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 |
| :--- | :---------- |
| 413  | The request contained more than the maximum allowed amount of network locations (100). |
