REST API v1

Horus Secure Analyst API

Integrate vulnerability scanning into your own apps, CI pipelines, and security workflows. Authenticate with a simple Bearer token and get structured findings in seconds.

Get an API key Browse endpoints

Getting started

Create an account

Generate a key

Go to Settings → API Keys and create a key. Copy it immediately — we only show it once.

Settings

Start scanning

Send a POST request with your target URL and Authorization header. Results arrive in 15–60 seconds.

See example

Base URL

https://horussecureanalyst.co.za/api/public/v1

Authentication

Include your key in the Authorization header as a Bearer token.

Authorization: Bearer hsa_live_xxxxxxxxxxxxxxxxxxxxxxxx

Endpoints

POST/scans

Start a scan

Trigger a full vulnerability scan against a target URL you own or are authorized to test. The scan runs synchronously and returns when complete.

Request

curl -X POST https://horussecureanalyst.co.za/api/public/v1/scans \
  -H "Authorization: Bearer hsa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"https://example.com","maxPages":10}'

Response

{
  "scan_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "score": 42,
  "summary": {
    "critical": 0,
    "high": 2,
    "medium": 5,
    "low": 3,
    "info": 1,
    "pages": 8
  },
  "status_url": "/api/public/v1/scans/550e8400-e29b-41d4-a716-446655440000",
  "findings_url": "/api/public/v1/scans/550e8400-e29b-41d4-a716-446655440000/findings"
}

GET/scans/{id}

Get scan status

Retrieve the current status, score, and summary for a scan you initiated.

Request

curl https://horussecureanalyst.co.za/api/public/v1/scans/SCAN_ID \
  -H "Authorization: Bearer hsa_live_YOUR_KEY"

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "target_url": "https://example.com",
  "status": "completed",
  "hackability_score": 42,
  "summary": { ... },
  "created_at": "2025-06-11T12:34:56Z",
  "finished_at": "2025-06-11T12:35:28Z"
}

GET/scans/{id}/findings

List findings

Return paginated findings for a completed scan. Ordered by severity (critical first).

Request

curl "https://horussecureanalyst.co.za/api/public/v1/scans/SCAN_ID/findings?limit=50&offset=0" \
  -H "Authorization: Bearer hsa_live_YOUR_KEY"

Response

{
  "scan_id": "550e8400-e29b-41d4-a716-446655440000",
  "total": 11,
  "limit": 50,
  "offset": 0,
  "findings": [
    {
      "id": "...",
      "category": "headers",
      "severity": "high",
      "title": "Missing Content-Security-Policy header",
      "evidence": "...",
      "recommendation": "Add a CSP header...",
      "target_url": "https://example.com",
      "cvss": 6.5,
      "platform_tags": ["nginx"],
      "created_at": "2025-06-11T12:35:10Z"
    }
  ]
}

Request body parameters

Parameter	Type	Default	Description
target*	string	—	URL to scan. Must be a site you own or have authorization to test.
active	boolean	false	Enable active probes (form fuzzing, path traversal tests). Slower but deeper.
sitemap	boolean	false	Crawl the sitemap for additional pages to scan.
maxPages	integer	10	Maximum pages to scan. Range: 1–25.
aggressiveness	enum	medium	Scan intensity: low, medium, or high.
timeoutMs	integer	10000	Per-request timeout in milliseconds. Range: 2000–60000.
retries	integer	1	Number of retries for failed requests. Range: 0–3.
minSeverity	enum	low	Filter findings below this severity: info, low, medium, high, critical.

Rate limits & fair use

30 scans / hour / key

Each API key is limited to 30 scan requests per hour. Exceeding this returns HTTP 429 with a retry hint.

Authorized targets only

You must only scan systems you own or have explicit written permission to test. Violation may result in key revocation and account suspension.

Error codes

HTTP	Meaning
400	Bad Request — invalid JSON or missing required field.
401	Unauthorized — missing or invalid API key.
404	Not Found — scan ID does not exist or does not belong to you.
429	Too Many Requests — rate limit exceeded.
500	Internal Server Error — scan failed or database error.

All error responses include a JSON body with {"error": "..."}. Use the message to debug before contacting support.