> 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 %}