Agency plan

API Reference

Integrate ScanYour.Site into your workflow. Trigger scans programmatically, pull results, and monitor domains — all via REST.

Base URL: https://scanyour.site

Authentication

All API requests require a valid API key passed in the x-api-key header. Generate your key from the dashboard under Settings → API Keys.

$ curl https://scanyour.site/api/v1/scans \
-H "x-api-key: sys_your_api_key_here"

API access requires a Pro or Agency plan. Requests with a free plan key return 403 Forbidden.

Endpoints

GET/api/v1/scans

List all scans for your account.

Response

{
  "scans": [
    {
      "id": "clx1...",
      "domain": "example.com",
      "status": "completed",
      "progress": 100,
      "createdAt": "2024-01-15T10:00:00Z",
      "completedAt": "2024-01-15T10:01:02Z",
      "reportUrl": "https://scanyour.site/dashboard/scans/clx1..."
    }
  ]
}

POST/api/v1/scans

Create and enqueue a new scan.

Request body

{
  "domain": "example.com"
}

Response

{
  "scanId": "clx1...",
  "status": "queued"
}

GET/api/v1/scans/:id

Get a scan result by ID. Poll until status is completed.

Response

{
  "scan": {
    "id": "clx1...",
    "domain": "example.com",
    "status": "completed",
    "progress": 100,
    "createdAt": "2024-01-15T10:00:00Z",
    "completedAt": "2024-01-15T10:01:02Z",
    "reportUrl": "https://scanyour.site/dashboard/scans/clx1...",
    "results": {
      "riskScore": 42,
      "findings": [
        {
          "id": "uuid",
          "title": "Missing Strict-Transport-Security header",
          "severity": "medium",
          "category": "Headers",
          "description": "...",
          "remediation": "..."
        }
      ],
      "sslExpiresAt": "2025-03-01T00:00:00Z"
    }
  }
}

GET/api/v1/domains

List monitored domains with their latest scan score.

Response

{
  "domains": [
    {
      "id": "dom1...",
      "url": "example.com",
      "verified": true,
      "lastScan": {
        "id": "clx1...",
        "completedAt": "2024-01-15T10:01:02Z",
        "score": 58,
        "findingsTotal": 12
      }
    }
  ]
}

Quickstart

Trigger a scan and wait for results in three steps.

1 — Create a scan

$ curl -X POST https://scanyour.site/api/v1/scans \
  -H "x-api-key: sys_your_key" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

2 — Poll until completed

# Poll every 5s until status === "completed"
curl https://scanyour.site/api/v1/scans/{scanId} \
  -H "x-api-key: sys_your_key"

3 — Read results

{
  "scan": {
    "status": "completed",
    "results": {
      "riskScore": 42,        // 0 = worst, 100 = best
      "findings": [...],      // array of issues with severity + remediation
      "sslExpiresAt": "..."   // ISO date or null
    }
  }
}

Status codes

200OKRequest succeeded.

201CreatedScan created and queued.

400Bad RequestInvalid domain or payload.

401UnauthorizedMissing or invalid API key.

403ForbiddenPlan does not include API access.

404Not FoundScan not found or does not belong to your account.

500Server ErrorSomething went wrong on our end.