Developer Docs

API Reference

Integrate SecurePulse security scanning directly into your CI/CD pipeline, dashboard, or application with our REST API.

Version v2.1.0  ·  REST  ·  JSON  ·  HTTPS Only
Getting Started

Authentication

The SecurePulse API uses API keys for authentication. All requests must be made over HTTPS and include your API key in the Authorization header.

You can generate and manage API keys from your dashboard under Account → API Keys. Treat your API keys like passwords — never commit them to version control.

AUTHORIZATION HEADER 
Authorization: Bearer sp_live_your_api_key_here
CURL EXAMPLE 
curl -X GET https://api.securepulse.io/v2/scans \
  -H "Authorization: Bearer sp_live_your_api_key" \
  -H "Content-Type: application/json"
ℹ️ API keys prefixed with sp_live_ affect production data. Use sp_test_ keys for development — test scans run against our sandbox environment and don't count toward your quota.
Base URL

Base URL

All API requests are made to the following base URL. The API is versioned; current stable version is v2.

BASE URL 
https://api.securepulse.io/v2/

All responses are in JSON format. Timestamps are in ISO 8601 format (UTC). The API supports gzip compression — include Accept-Encoding: gzip in your headers for faster responses.

Rate Limits

Rate limits

Requests are rate limited per API key. Exceeding limits returns a 429 Too Many Requests response. Rate limit headers are included in every response.

Free
10/hr
scans per hour
Pro
100/hr
scans per hour
Team
500/hr
scans per hour
Enterprise
∞
custom limits
RATE LIMIT HEADERS 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705348800
Retry-After: 3600  # only on 429 responses
Errors

Error handling

The API uses standard HTTP status codes. Error responses include a JSON body with error, message, and optional details fields.

ERROR RESPONSE 
{
  "error": "invalid_url",
  "message": "The provided URL is not reachable or invalid.",
  "status": 422,
  "request_id": "req_01HX7K9M2P3Q4R5S6T7U8V9W"
}
Endpoints

Initiate a scan

POST /v2/scans

Initiates a new security scan. The scan runs asynchronously — use the returned scan_id to poll for status and retrieve the report.

ParameterTypeRequiredDescription
url string required The target URL to scan. Must be a valid HTTPS URL.
scan_type string optional One of: quick, full, headers_only. Default: full
webhook_url string optional URL to POST results to when scan completes.
label string optional Custom label for the scan (max 100 chars).
REQUEST 
curl -X POST https://api.securepulse.io/v2/scans \
  -H "Authorization: Bearer sp_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "scan_type": "full",
    "webhook_url": "https://yourapp.com/webhook/scans"
  }'
RESPONSE 202 ACCEPTED 
{
  "scan_id": "scan_01HX7K9M2P3Q4R5S6T7U8V9W",
  "status": "queued",
  "url": "https://example.com",
  "scan_type": "full",
  "created_at": "2025-01-15T10:30:00Z",
  "estimated_duration": 45  // seconds
}

Get scan status

GET /v2/scans/{scan_id}/status

Poll this endpoint to track scan progress. Status values: queued → running → complete or failed.

RESPONSE 200 OK 
{
  "scan_id": "scan_01HX7K9M2P3Q4R5S6T7U8V9W",
  "status": "running",
  "progress": 67,  // percent
  "current_check": "Security Headers",
  "started_at": "2025-01-15T10:30:05Z"
}

Get scan report

GET /v2/scans/{scan_id}/report

Retrieve the full vulnerability report for a completed scan. Returns 409 if scan is still running.

RESPONSE 200 OK 
{
  "scan_id": "scan_01HX7K9M2P3Q4R5S6T7U8V9W",
  "url": "https://example.com",
  "score": 74,
  "grade": "B",
  "completed_at": "2025-01-15T10:30:52Z",
  "summary": {
    "critical": 0,
    "high": 2,
    "medium": 3,
    "low": 1,
    "pass": 18
  },
  "findings": [
    {
      "id": "content-security-policy",
      "severity": "high",
      "title": "Content Security Policy Missing",
      "status": "fail",
      "fix_url": "https://securepulse.io/security-solutions/?issue=content-security-policy"
    }
  ]
}
Account

Webhooks

Configure webhooks to receive real-time notifications when scans complete or when critical vulnerabilities are detected on monitored sites.

Webhook payloads are signed using HMAC-SHA256 with your webhook secret. Verify the signature by checking the X-SecurePulse-Signature header.

SIGNATURE VERIFICATION (NODE.JS) 
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return `sha256=${expected}` === signature;
}

SDKs & libraries

Official SecurePulse SDKs are available for popular languages. Community SDKs are listed in our GitHub organization.

🟢
Node.js
npm install @securepulse/sdk
🐍
Python
pip install securepulse
🐘
PHP
composer require securepulse/sdk
💎
Ruby
gem install securepulse