> For the complete documentation index, see [llms.txt](https://docs.auditbase.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.auditbase.com/api-access/v-1.1/create-scan.md).

# Create Scan

## Create a New Scan

<mark style="color:green;">`POST`</mark> `/v1.1/scans`

Create a scan which analyzes smart contracts.   Scans can either be created by included the source files or by specifying the blockchain id and the contract address.  There are two types source code analysis,  "ai"  and "codescan".  &#x20;

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <api_key>` |

**Body**

The body is a "params" JSON object with the following keys

| Name                                    | Type                | Description                                                                                      |
| --------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------ |
| name                                    | string              | Scan label                                                                                       |
| source                                  | string              | "upload" for direct file input, "explorer" for blockchain explorer source code retrieval         |
| type                                    | string              | Model used to analyze the source code.  "ai" or "codescan".                                      |
| `files [upload source]`                 | JSON Array of files | \[{"file\_name": "file1.sol", "content": "uint var1; ..."}]                                      |
| chain\_id \[explorer source]            | integer             |                                                                                                  |
| contract\_address \[explorer source]    | string              | The address of a contract with verified source code                                              |
| webhook\_url \[optional]                | string              | URL where you would like the results sent in a post request                                      |
| language \[optional] default="solidity" | string              | The language of the source code.  "solidity" or "cosmos" for ai scan.   "solidity" for codescan. |

**Upload Scan Example**

<pre class="language-python"><code class="lang-python"><strong>file1 = Path('./example.sol').read_text()
</strong>file2 = Path('./example2.sol').read_text()
file3 = Path('./example3.sol').read_text()
    
key = "&#x3C;your auditbase key>"
host = 'https://api.auditbase.com'
route = '/v1.1/scans'
url = host + route
post_data = {
    "params":{
        "source": "upload",
        "name": "scan1",
        "files": [{"file_name": "file1.sol", "content": file1},
        {"file_name": "file2.sol", "content": file2}]
        ,
        "webhook_url": "https://yourwebhook/webhook",
        "type": "ai",
        "language": "solidity",
    },
}

headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {key}',
}

response = requests.post(url, json=post_data, headers=headers)
print("response: ", response.json())

</code></pre>

**Blockchain Explorer Scan Example**. &#x20;

A list of acceptable values for the chain\_id are listed [here](/api-access/v-1.1/supported-blockchains.md).<br>

<pre class="language-python"><code class="lang-python"><strong>key = "&#x3C;your AuditBase key>"
</strong>host = 'https://api.auditbase.com'
route = '/v1.1/scans'
url = host + route

post_data = {
      "params":{
          "source": "explorer",
          "chain_id": 1,
          "contract_address": "0xCC7ed2ab6c3396DdBc4316D2d7C1b59ff9d2091F",
          "webhook_url": "&#x3C;your webhook callback address>",
          "type": "codescan",
      },
}

headers = {
      'Content-Type': 'application/json',
      'Authorization': f'Bearer {key}',
}

response = requests.post(url, json=post_data, headers=headers)
print("response: ", response.json())
</code></pre>

**Response**

**returns ScanPlacement Result Object**

{% tabs %}
{% tab title="200" %}

<pre class="language-json"><code class="lang-json">{
  "success": true,
<strong>  "scan_id": "60188023-0b6f-4994-ba15-3d973efb0711",
</strong>  "webhook_url": "your-specified-callback-url.com"
}
</code></pre>

{% endtab %}

{% tab title="400" %}

```json
{
  "success": "failure",
  "scan_id": "",
  "message": "error reason"
}
```

{% endtab %}
{% endtabs %}

**Webhook Response**

Once a scan completes, AuditBase will callback a webhook with the following data:&#x20;

{% tabs %}
{% tab title="200" %}

````json
{
    "status": "success",
    "scan_id": "d50d67c6-3b5a-4a9e-86e6-e18a19b1efa2",
    "score": 8.2,
    "num_lines": 721,
    "timestamp": 1726804295
    "severity_counts": {
        "high": 0,
        "low": 2, 
        "medium": 1,
     },
     "issues": [
         {
             "count": 1, 
             "description": 'The division cannot overflow, since both the numerator and the denominator are non-negative.', 
             "id": 'd50d67c6-3b5a-4a9e-86e6-e18a19b1efc1', 
             "identifier": 'G013', 
             "severity": 'gas_optimization', 
             "snippet": '```solidity\nFile: tmp/4dba7fd7-4c36-4683-aac7-e69dfeb11e1f/23309182-e8eb-4236-b00c-0e6e622a56bc.sol\n\n74              uint fee = (amount * taxCollected) / 100;\n\n```\n', 
             "title": '`unchecked {}` can be used on the division of two `uints` in order to save gas'
         }
     ]
}
````

{% endtab %}

{% tab title="400" %}

```
{
    "status": "failure",
    "message": "error reason",
    "scan_id": "d50d67c6-3b5a-4a9e-86e6-e18a19b1efc1"
}
```

{% endtab %}
{% endtabs %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.auditbase.com/api-access/v-1.1/create-scan.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.