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

# Pentest API

Upload pentest reports and manage their vulnerabilities programmatically using the Pentest API.

Use the Pentest API to send penetration test (pentest) reports and their vulnerabilities to Sprinto from your own tools. The API supports the same actions as the **Pentest** page under **Data Library > Vulnerabilities**: upload a report, add vulnerabilities, upload a retest report, close vulnerabilities, and edit a pentest.

Use this API to automate pentest tracking from your pentest vendor's platform, CI/CD pipelines, or internal tools.

***

#### How it works

A typical integration:

1. Uploads the pentest report. The response returns the `pentest_pk`.
2. Adds the vulnerabilities from the report to the pentest.
3. Closes each vulnerability after it is fixed.
4. Uploads the updated report after a retest.

Sprinto evaluates the related checks in the same way as for changes made in the app.

***

#### Before you begin

Before you use this API, make sure you have:

* The base URL for your Sprinto region
* An API token that belongs to a user with the **Admin** role

**Base URL**

<table><thead><tr><th width="180">Region</th><th>Base URL</th></tr></thead><tbody><tr><td>United States</td><td><code>https://app.sprinto.com</code></td></tr><tr><td>Europe</td><td><code>https://eu.sprinto.com</code></td></tr><tr><td>India</td><td><code>https://in.sprinto.com</code></td></tr><tr><td>Australia</td><td><code>https://au.sprinto.com</code></td></tr></tbody></table>

The examples on this page use the United States URL. Replace it with the URL for your region.

To generate an API token:

1. Log in to Sprinto.
2. Go to **Settings > Developer API**.
3. Generate a new API token.
4. Copy and securely store the token.

{% hint style="info" %}
**Note**

Keep your API token secure. Treat it like a password and never commit it to source control.
{% endhint %}

***

#### Authentication

**Header**

```
api-token: <your-api-token>
```

**Guidelines**

* Keep tokens secure
* Use HTTPS only
* Use a token of an Admin user

***

#### Endpoints

<table><thead><tr><th width="100">Method</th><th width="360">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td>POST</td><td><code>/api/v1/pentests</code></td><td>Upload a pentest report</td></tr><tr><td>GET</td><td><code>/api/v1/pentests</code></td><td>List pentests</td></tr><tr><td>PATCH</td><td><code>/api/v1/pentests/{pentest_pk}</code></td><td>Edit a pentest</td></tr><tr><td>POST</td><td><code>/api/v1/pentests/{pentest_pk}/vulnerabilities</code></td><td>Add vulnerabilities</td></tr><tr><td>GET</td><td><code>/api/v1/pentests/{pentest_pk}/vulnerabilities</code></td><td>List vulnerabilities of a pentest</td></tr><tr><td>POST</td><td><code>/api/v1/pentests/{pentest_pk}/reports</code></td><td>Upload an updated report (retest)</td></tr><tr><td>POST</td><td><code>/api/v1/pentests/vulnerabilities/{vulnerability_pk}/close</code></td><td>Close a vulnerability</td></tr></tbody></table>

### Upload a pentest report

Creates a pentest and attaches the report file. You can also add the vulnerabilities from the report in the same request.

Send the report in one of two ways:

* As a file, in a `multipart/form-data` request
* As a link, in an `application/json` request with `file_url`. Sprinto downloads the file from the link.

#### Endpoint

```
POST /api/v1/pentests
```

#### Body parameters

<table><thead><tr><th width="170">Parameter</th><th width="100">Type</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>Yes</td><td>Name of the pentest, such as <code>Q3 2026 external pentest</code>.</td></tr><tr><td>file</td><td>file</td><td>Conditional</td><td>The pentest report. Multipart requests only. Send either <code>file</code> or <code>file_url</code>.</td></tr><tr><td>file_url</td><td>string</td><td>Conditional</td><td>A public <code>https</code> link to the pentest report. JSON requests only. Send either <code>file</code> or <code>file_url</code>.</td></tr><tr><td>report_issue_date</td><td>string</td><td>No</td><td>Date the report was issued, in <code>YYYY-MM-DD</code> format. Cannot be in the future. Defaults to today.</td></tr><tr><td>zone_pks</td><td>array</td><td>No</td><td>Zones to add the pentest to. Leave it out if you do not use zones.</td></tr><tr><td>vulnerabilities</td><td>array</td><td>No</td><td>Open vulnerabilities from the report. See Vulnerability object.</td></tr></tbody></table>

{% hint style="info" %}
**Note**

1. In a multipart request, send `zone_pks` and `vulnerabilities` as JSON text, such as `zone_pks=["<zone-pk>"]`.
2. Do not send `file` and `file_url` in the same request.
   {% endhint %}

**Example request**

{% tabs %}
{% tab title="cURL (file)" %}

```bash
curl --request POST 'https://app.sprinto.com/api/v1/pentests' \
--header 'api-token: your-api-token' \
--form 'name=Q3 2026 external pentest' \
--form 'report_issue_date=2026-09-30' \
--form 'vulnerabilities=[{"description":"SQL injection on /login","severity":"HIGH"},{"description":"Missing HSTS header","severity":"LOW"}]' \
--form 'file=@/path/to/report.pdf'
```

{% endtab %}

{% tab title="cURL (file\_url)" %}

```bash
curl --request POST 'https://app.sprinto.com/api/v1/pentests' \
--header 'api-token: your-api-token' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Q3 2026 external pentest",
  "report_issue_date": "2026-09-30",
  "file_url": "https://files.example.com/reports/q3-pentest.pdf",
  "vulnerabilities": [
    { "description": "SQL injection on /login", "severity": "HIGH" }
  ]
}'
```

{% endtab %}

{% tab title="Node.js (Axios)" %}

```js
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const data = new FormData();
data.append('name', 'Q3 2026 external pentest');
data.append('report_issue_date', '2026-09-30');
data.append('vulnerabilities', JSON.stringify([
  { description: 'SQL injection on /login', severity: 'HIGH' }
]));
data.append('file', fs.createReadStream('/path/to/report.pdf'));

axios.post('https://app.sprinto.com/api/v1/pentests', data, {
  headers: {
    'api-token': 'your-api-token',
    ...data.getHeaders()
  }
})
.then(res => console.log(res.data))
.catch(err => console.error(err.response ? err.response.data : err));
```

{% endtab %}

{% tab title="Python" %}

```python
import json
import requests

url = 'https://app.sprinto.com/api/v1/pentests'

headers = {
    'api-token': 'your-api-token'
}

files = {
    'file': ('report.pdf', open('/path/to/report.pdf', 'rb'), 'application/pdf')
}

data = {
    'name': 'Q3 2026 external pentest',
    'report_issue_date': '2026-09-30',
    'vulnerabilities': json.dumps([
        {'description': 'SQL injection on /login', 'severity': 'HIGH'}
    ])
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())
```

{% endtab %}
{% endtabs %}

**Example response (201 Created)**

```json
{
  "success": true,
  "pentest_pk": "<pentest-pk>",
  "pentest_report_pk": "<pentest-report-pk>",
  "vulnerabilities": [
    {
      "pk": "<vulnerability-pk>",
      "description": "SQL injection on /login",
      "severity": "HIGH",
      "state": "OPEN",
      "closure_reason": null,
      "closure_date": null,
      "created_at": "2026-10-08T16:28:31.990Z"
    }
  ]
}
```

Store the `pentest_pk`. The other endpoints need it.

### Add vulnerabilities

Adds open vulnerabilities to the latest report of a pentest.

#### Endpoint

```
POST /api/v1/pentests/{pentest_pk}/vulnerabilities
```

#### Body parameters

<table><thead><tr><th width="170">Parameter</th><th width="100">Type</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td>vulnerabilities</td><td>array</td><td>Yes</td><td>One or more vulnerabilities. See Vulnerability object.</td></tr></tbody></table>

**Example request**

```bash
curl --request POST 'https://app.sprinto.com/api/v1/pentests/<pentest-pk>/vulnerabilities' \
--header 'api-token: your-api-token' \
--header 'Content-Type: application/json' \
--data '{
  "vulnerabilities": [
    { "description": "Outdated jQuery library", "severity": "MODERATE" }
  ]
}'
```

**Example response (201 Created)**

```json
{
  "success": true,
  "vulnerabilities": [
    {
      "pk": "<vulnerability-pk>",
      "description": "Outdated jQuery library",
      "severity": "MODERATE",
      "state": "OPEN",
      "closure_reason": null,
      "closure_date": null,
      "created_at": "2026-10-08T16:29:11.472Z"
    }
  ]
}
```

### Upload an updated report (retest)

Adds a new report to an existing pentest after a retest. This endpoint accepts the same `file` or `file_url` as Upload a pentest report and an optional `vulnerabilities` list.

{% hint style="warning" %}
**Important**

This endpoint closes all vulnerabilities that are still open on the previous report, with the reason `WRONG_ADDITION`. Include the vulnerabilities that are still open after the retest in `vulnerabilities` so that they remain open on the new report. Vulnerabilities that you closed earlier do not change.
{% endhint %}

#### Endpoint

```
POST /api/v1/pentests/{pentest_pk}/reports
```

**Example request**

```bash
curl --request POST 'https://app.sprinto.com/api/v1/pentests/<pentest-pk>/reports' \
--header 'api-token: your-api-token' \
--form 'vulnerabilities=[{"description":"Missing HSTS header","severity":"LOW"}]' \
--form 'file=@/path/to/retest-report.pdf'
```

**Example response (201 Created)**

```json
{
  "success": true,
  "pentest_report_pk": "<pentest-report-pk>",
  "vulnerabilities": [
    {
      "pk": "<vulnerability-pk>",
      "description": "Missing HSTS header",
      "severity": "LOW",
      "state": "OPEN",
      "closure_reason": null,
      "closure_date": null,
      "created_at": "2026-10-08T16:29:31.381Z"
    }
  ]
}
```

### Close a vulnerability

Closes an open vulnerability.

#### Endpoint

```
POST /api/v1/pentests/vulnerabilities/{vulnerability_pk}/close
```

#### Body parameters

<table><thead><tr><th width="170">Parameter</th><th width="100">Type</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td>closure_reason</td><td>string</td><td>Yes</td><td>One of:<br><code>RESOLVED</code>: the vulnerability is fixed<br><code>WRONG_ADDITION</code>: the vulnerability was added by mistake<br><code>NOT_APPLICABLE</code>: the vulnerability does not apply and will not be fixed</td></tr><tr><td>closure_date</td><td>string</td><td>Yes</td><td>Date the vulnerability was closed, in <code>YYYY-MM-DD</code> format. Must be between the report issue date of the pentest and today.</td></tr></tbody></table>

**Example request**

```bash
curl --request POST 'https://app.sprinto.com/api/v1/pentests/vulnerabilities/<vulnerability-pk>/close' \
--header 'api-token: your-api-token' \
--header 'Content-Type: application/json' \
--data '{ "closure_reason": "RESOLVED", "closure_date": "2026-10-08" }'
```

**Example response (200 OK)**

```json
{
  "success": true,
  "vulnerability": {
    "pk": "<vulnerability-pk>",
    "description": "SQL injection on /login",
    "severity": "HIGH",
    "state": "CLOSED",
    "closure_reason": "RESOLVED",
    "closure_date": "2026-10-08T00:00:00.000Z",
    "created_at": "2026-10-08T16:28:31.990Z"
  }
}
```

### Edit a pentest

Updates the name or zones of a pentest. Send at least one field. Fields that you leave out keep their current values.

#### Endpoint

```
PATCH /api/v1/pentests/{pentest_pk}
```

#### Body parameters

<table><thead><tr><th width="170">Parameter</th><th width="100">Type</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>No</td><td>New name of the pentest.</td></tr><tr><td>zone_pks</td><td>array</td><td>No</td><td>Full list of zones for the pentest. Replaces the current list.</td></tr></tbody></table>

**Example request**

```bash
curl --request PATCH 'https://app.sprinto.com/api/v1/pentests/<pentest-pk>' \
--header 'api-token: your-api-token' \
--header 'Content-Type: application/json' \
--data '{ "name": "Q3 2026 external pentest (final)" }'
```

**Example response (200 OK)**

```json
{
  "success": true,
  "pentest": {
    "pk": "<pentest-pk>",
    "name": "Q3 2026 external pentest (final)",
    "report_issue_date": "2026-09-30T00:00:00.000Z",
    "zone_pks": [],
    "created_at": "2026-10-08T16:28:31.917Z"
  }
}
```

### List pentests

Returns all pentests in your organization. The open and closed vulnerability counts come from the latest report of each pentest.

#### Endpoint

```
GET /api/v1/pentests
```

**Example request**

```bash
curl --request GET 'https://app.sprinto.com/api/v1/pentests' \
--header 'api-token: your-api-token'
```

**Example response (200 OK)**

```json
{
  "success": true,
  "pentests": [
    {
      "pk": "<pentest-pk>",
      "name": "Q3 2026 external pentest",
      "report_issue_date": "2026-09-30T00:00:00.000Z",
      "zone_pks": [],
      "created_at": "2026-10-08T16:28:31.917Z",
      "latest_report_pk": "<pentest-report-pk>",
      "open_vulnerabilities": 2,
      "closed_vulnerabilities": 1
    }
  ]
}
```

### List vulnerabilities of a pentest

Returns the vulnerabilities on the latest report of a pentest. Use this endpoint to find the `vulnerability_pk` to close a vulnerability. If the pentest has no report, `pentest_report_pk` is `null` and the list is empty.

#### Endpoint

```
GET /api/v1/pentests/{pentest_pk}/vulnerabilities
```

#### Query parameters

<table><thead><tr><th width="170">Parameter</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td>state</td><td>No</td><td><code>OPEN</code> or <code>CLOSED</code>. Returns both if you leave it out.</td></tr></tbody></table>

**Example request**

```bash
curl --request GET 'https://app.sprinto.com/api/v1/pentests/<pentest-pk>/vulnerabilities?state=OPEN' \
--header 'api-token: your-api-token'
```

**Example response (200 OK)**

```json
{
  "success": true,
  "pentest_report_pk": "<pentest-report-pk>",
  "vulnerabilities": [
    {
      "pk": "<vulnerability-pk>",
      "description": "Missing HSTS header",
      "severity": "LOW",
      "state": "OPEN",
      "closure_reason": null,
      "closure_date": null,
      "created_at": "2026-10-08T16:28:31.990Z"
    }
  ]
}
```

***

#### Vulnerability object

**Request fields**

<table><thead><tr><th width="150">Field</th><th width="100">Type</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td>description</td><td>string</td><td>Yes</td><td>Details of the vulnerability, such as <code>SQL injection on /login</code> or a CVE reference.</td></tr><tr><td>severity</td><td>string</td><td>Yes</td><td>One of <code>CRITICAL</code>, <code>HIGH</code>, <code>MODERATE</code>, <code>LOW</code>, or <code>INFORMATIONAL</code>. Not case-sensitive.</td></tr></tbody></table>

{% hint style="info" %}
**Note**

If your pentest vendor uses other severity names, map them before you send the request. For example, send `MODERATE` for "Medium".
{% endhint %}

**Response fields**

<table><thead><tr><th width="150">Field</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>pk</td><td>string</td><td>Unique identifier of the vulnerability</td></tr><tr><td>description</td><td>string</td><td>Details of the vulnerability</td></tr><tr><td>severity</td><td>string</td><td>Severity of the vulnerability</td></tr><tr><td>state</td><td>string</td><td><code>OPEN</code> or <code>CLOSED</code></td></tr><tr><td>closure_reason</td><td>string / null</td><td>Reason the vulnerability was closed</td></tr><tr><td>closure_date</td><td>string / null</td><td>Date the vulnerability was closed</td></tr><tr><td>created_at</td><td>string</td><td>Date and time the vulnerability was added</td></tr></tbody></table>

***

#### Error handling

All error responses have this format:

```json
{
  "success": false,
  "errors": [
    {
      "key": "vulnerabilities.0.severity",
      "messages": ["Invalid enum value. Expected 'LOW' | 'MODERATE' | 'HIGH' | 'CRITICAL' | 'INFORMATIONAL', received 'MEDIUM'"]
    }
  ]
}
```

`key` names the request field that caused the error, when there is one.

**400 Bad Request**

* Missing or invalid parameters
* Report issue date in the future
* File is not a PDF or ZIP
* `file_url` cannot be downloaded, or points to a private or internal address
* Zone not found
* Closure date out of range
* Vulnerability already closed

**401 Unauthorized**

* Missing or invalid API token

**403 Forbidden**

* API token does not belong to an Admin user

**404 Not Found**

* Pentest or vulnerability not found in your organization

**413 Payload Too Large**

* Report file is larger than 50 MB

**500 Internal Server Error**

* Unexpected error. Sprinto saves no changes from the failed request. Retry later.

***

#### Supported file types

<table><thead><tr><th width="144">Category</th><th>Extensions</th></tr></thead><tbody><tr><td>Documents</td><td>.pdf</td></tr><tr><td>Archives</td><td>.zip</td></tr></tbody></table>

If the report has multiple files, add them to one ZIP file. Sprinto checks the file content, so a file that is not a PDF or ZIP fails even if its name ends in `.pdf`.

**Limits**

* Maximum report file size: 50 MB
* `file_url` must be a public `https` link that Sprinto can download within 30 seconds
* Links that resolve to private or internal network addresses are not supported
* Maximum JSON request size: 500 KB. Split large vulnerability lists across multiple requests.

***

#### Checks in Sprinto

The API updates the same checks as the app:

* **Periodic VAPT report needs to be uploaded**: evaluated when you upload a report
* **VAPT vulnerability should be resolved**: created for each open vulnerability, and passes when you close the vulnerability

***

#### Troubleshooting

<table><thead><tr><th width="200">Issue</th><th width="200">Cause</th><th>Resolution</th></tr></thead><tbody><tr><td>401 Unauthorized</td><td>Missing or invalid token</td><td>Send the token in the <code>api-token</code> header, not <code>api-key</code></td></tr><tr><td>403 Forbidden</td><td>Token of a non-Admin user</td><td>Use a token of an Admin user</td></tr><tr><td>The report must be a PDF or ZIP file</td><td>Unsupported or damaged file</td><td>Upload a valid PDF or ZIP file</td></tr><tr><td>Could not download file_url</td><td>Link is not reachable, or the server returned an error status</td><td>Use a public HTTPS link that returns the file directly</td></tr><tr><td>file_url needs sign-in</td><td>Link returns 401 or 403</td><td>Use a link that does not need sign-in, such as a pre-signed URL</td></tr><tr><td>file_url points to a private or internal address</td><td>Link resolves to a private network address</td><td>Host the report on a public HTTPS URL</td></tr><tr><td>closure_date must be between the report issue date and today</td><td>Closure date out of range</td><td>Use a date from the pentest's report issue date through today</td></tr><tr><td>report_issue_date cannot be in the future</td><td>Issue date after today</td><td>Use the date the report was issued</td></tr><tr><td>This pentest has no report yet</td><td>Pentest without a report</td><td>Upload a report before you add vulnerabilities</td></tr><tr><td>Vulnerabilities closed after a retest</td><td>The retest endpoint closes open vulnerabilities on the previous report</td><td>Include the vulnerabilities that are still open in the retest request</td></tr><tr><td>Check status not updated</td><td>Processing delay</td><td>Refresh after a few seconds</td></tr></tbody></table>

***


---

# 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.sprinto.com/api-reference/pentest-api.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.
