> For the complete documentation index, see [llms.txt](https://docs.adsecure.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adsecure.com/docs/threat-intelligence/lookup.md).

# Lookup

This is the main endpoint of the Threat Intelligence service. It allows you to fetch the `risk` of a URL, along with more detailed information on the violations that occurred.

## Intelligence provided

### Risk

The `risk` is a single number from `0` to `5`, where `0` is risk-free and `5` represents a very severe risk of the domain incurring in a violation. It is computed based on the violation map included in the response and a [violation weight map](/docs/threat-intelligence/violation-weight-map.md). Each violation has an associated `weight` that will determine its importance in computing the `risk`. The violation weight map can either be the [default](/docs/threat-intelligence/violation-weight-map.md#default-violation-weight-map) provided by AdSecure or be [user-defined](/docs/threat-intelligence/violation-weight-map.md#setting-a-custom-violation-weight-map).

### Violation map

AdSecure also provides you with the list of all the violations that occurred on this URL. For each of those violations, we include:

* `login`: the name of the violation
* `lastDetected`: the time when it was last detected
* `probability`: the probability of the violation occurring on this URL directly, or further down the redirection chain. If the probability is `0.8`, we estimate that the violation has a 80% risk of occurring

> The `violations` array may be empty. In this case, the domain is known to us but no violations were recorded. This is the safest response possible.

For further information on what the violations mean, see the [full list of violations](/docs/detections.md).

### Metadata

* `lastAnalysed`: the time when this domain was last analysed
* `expireTime`: the time when AdSecure will compute again the data for this domain

## Request shape

You need to be [authenticated](/docs/threat-intelligence/authentication.md) to use this method.

**Method:** `POST`

**Path:** `/lookup`

**Body:**

```json
{
  "url": "https://example.com/url"
}
```

**cURL:**

```bash
curl --request POST \
  -H "Content-Type: application/json" \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{"url":"https://example.com/url"}' \
  -v  https://api.adsecure.com/threat-intelligence/v1/lookup
```

## Response shape

```json
{
  "risk": 2,
  "lastAnalysed": "2019-10-04T13:59:10Z",
  "violations": [
    {
      "login": "ssl-non-compliant",
      "lastDetected": "2019-04-04T13:59:10Z",
      "probability": 0.83
    },
    {
      "login": "ransomware",
      "lastDetected": "2019-04-04T13:59:10Z",
      "probability": 0.2
    }
  ],
  "expireTime": "2019-10-04T15:22:08Z"
}
```

## Response status codes

| Status code | Meaning                                                                                                                                                                                                                                                          |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200         | Successful request, response payload with mentioned shape will be attached.                                                                                                                                                                                      |
| 202         | Successful request, but the requested URL is still being processed. Another request will have to be made to access the result. Currently the processing time is of a few seconds. Please consider either a delay or exponential backoff for your implementation. |
| 204         | Successful request, the URL was not found in our database, no body will be attached. A full analysis on your part is needed for this URL to be added to our database.                                                                                            |

## Troubleshooting

| Status code | Error message | Solution                                                                    |
| ----------- | ------------- | --------------------------------------------------------------------------- |
| 400         | Bad Request   | The body of the request is not a valid JSON format.                         |
| 401         | Unauthorized  | Either the `Authorization` header is not sent or it has an incorrect value. |
| 403         | Forbidden     | API key doesn't have the correct permissions for the endpoint.              |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.adsecure.com/docs/threat-intelligence/lookup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.