← Back to Home

API Documentation

Integrate IsSafeSite vulnerability scanning into your workflow with our REST API.

Authentication

All API requests require a Bearer token. Generate an API key from Dashboard → Settings → API Keys.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://issafesite.com/api/v1/scan

Unauthenticated requests return 401. Invalid or expired keys return 403.

Base URL

https://issafesite.com/api/v1

Rate Limits

API requests are rate limited per plan:

PlanScans / monthAPI requests / min
Free310
Pro10060
EnterpriseUnlimited300

Endpoints

POST
/api/v1/scan

Create a new vulnerability scan

Request Body

FieldTypeDescription
urlrequiredstringTarget URL to scan (e.g. https://example.com)
depthstringScan depth: QUICK, STANDARD (default), DEEP

Example

curl -X POST https://issafesite.com/api/v1/scan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "depth": "STANDARD"}'

Response 202 Accepted

{
  "id": "clx1abc...",
  "url": "https://example.com",
  "domain": "example.com",
  "depth": "STANDARD",
  "status": "PENDING",
  "statusUrl": "/api/v1/scan/clx1abc...",
  "createdAt": "2026-04-23T12:00:00Z"
}
GET
/api/v1/scan

List all scans with pagination

Query Parameters

FieldTypeDescription
pagenumberPage number (default: 1)
limitnumberResults per page (default: 20, max: 50)

Example

curl https://issafesite.com/api/v1/scan?page=1&limit=10 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "data": [
    {
      "id": "clx1abc...",
      "targetUrl": "https://example.com",
      "targetDomain": "example.com",
      "depth": "STANDARD",
      "status": "COMPLETED",
      "overallScore": 72,
      "grade": "C",
      "securityScore": 65,
      "seoScore": 80,
      "trafficScore": 75,
      "findingsCount": 8,
      "createdAt": "2026-04-23T12:00:00Z",
      "completedAt": "2026-04-23T12:01:30Z"
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 42, "pages": 5 }
}
GET
/api/v1/report

List PDF reports with optional scan filter

Query Parameters

FieldTypeDescription
scanIdstringFilter reports by scan ID
pagenumberPage number (default: 1)
limitnumberResults per page (default: 20, max: 50)

Example

curl https://issafesite.com/api/v1/report?scanId=clx1abc \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "data": [
    {
      "id": "rpt_xyz...",
      "title": "Security Report — example.com",
      "version": 1,
      "pdfSize": 245760,
      "format": "PDF",
      "createdAt": "2026-04-23T12:02:00Z",
      "scan": {
        "targetUrl": "https://example.com",
        "targetDomain": "example.com",
        "overallScore": 72,
        "grade": "C"
      },
      "downloadUrl": "/api/report/rpt_xyz.../pdf"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 3, "pages": 1 }
}

Error Responses

All errors return a JSON body with an error field:

{ "error": "Description of the error" }
CodeMeaning
400Bad request — missing or invalid parameters
401Unauthorized — missing API key
403Forbidden — invalid or expired API key
429Rate limit exceeded or plan quota reached
500Internal server error

Quick Start

JavaScript / Node.js

const API_KEY = "your_api_key";
const BASE = "https://issafesite.com/api/v1";

// Create a scan
const res = await fetch(BASE + "/scan", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com" }),
});

const scan = await res.json();
console.log(scan.id, scan.status);

Python

import requests

API_KEY = "your_api_key"
BASE = "https://issafesite.com/api/v1"

# Create a scan
res = requests.post(
    f"{BASE}/scan",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"url": "https://example.com", "depth": "DEEP"},
)

scan = res.json()
print(scan["id"], scan["status"])

Support

Need help? Reach out at support@issafesite.com or open an issue on GitHub.