SiteHalo
Sign InGet Started
Back to Home

API Documentation

SiteHalo provides a REST API to manage sites, trigger scans, retrieve reports, and handle billing. All endpoints require authentication via session cookies (NextAuth.js).

Authentication

All API endpoints (except webhooks) require a valid session cookie obtained by signing in via /auth/signin or registering at /auth/signup. Unauthenticated requests receive a 401 status.

Sites API

GET/api/sites

List all monitored sites for the authenticated user's organization.

Response
[
  {
    "id": "cuid...",
    "name": "My Website",
    "url": "https://example.com",
    "status": "ACTIVE",
    "checkInterval": 86400,
    "healthScore": 87,
    "lastScanAt": "2026-07-19T12:00:00.000Z",
    "createdAt": "2026-07-01T00:00:00.000Z"
  }
]
POST/api/sites

Add a new site to monitor. Subject to plan limits.

Request Body
{
  "name": "My Website",
  "url": "https://example.com",
  "checkInterval": 86400  // optional, default: daily
}
Response
{
  "id": "cuid...",
  "name": "My Website",
  "url": "https://example.com",
  "status": "ACTIVE",
  "healthScore": null,
  "createdAt": "2026-07-19T12:00:00.000Z"
}
GET/api/sites/:id

Get details for a specific site, including recent scans.

Response
{
  "id": "cuid...",
  "name": "My Website",
  "url": "https://example.com",
  "status": "ACTIVE",
  "scans": [...]
}
DELETE/api/sites/:id

Remove a site and all associated scans and reports.

Response
{ "success": true }

Scans API

GET/api/scans

List all scans for the authenticated user's organization.

Response
[
  {
    "id": "cuid...",
    "siteId": "cuid...",
    "status": "COMPLETED",
    "summary": { "SEO": 85, "PERFORMANCE": 72, ... },
    "createdAt": "2026-07-19T12:00:00.000Z",
    "completedAt": "2026-07-19T12:00:30.000Z"
  }
]
POST/api/scans/trigger

Trigger a new scan for a specific site.

Request Body
{
  "siteId": "cuid..."
}
Response
{
  "id": "cuid...",
  "status": "COMPLETED",
  "summary": { "SEO": 85, "PERFORMANCE": 72, ... },
  "results": [
    {
      "dimension": "SEO",
      "score": 85,
      "status": "PASS",
      "issues": [...]
    }
  ]
}
GET/api/scans/:id

Get full details for a scan, including all dimension results.

Response
{
  "id": "cuid...",
  "status": "COMPLETED",
  "results": [
    {
      "dimension": "SSL",
      "score": 100,
      "status": "PASS",
      "issues": []
    },
    ...
  ]
}

Reports API

GET/api/reports

List all generated reports for the authenticated user's organization.

Response
[
  {
    "id": "cuid...",
    "scanId": "cuid...",
    "title": "Site Health Report: My Website",
    "status": "READY",
    "createdAt": "2026-07-19T12:00:30.000Z"
  }
]
GET/api/reports/:id

Get the full AI-generated report with recommendations.

Response
{
  "id": "cuid...",
  "title": "Site Health Report: My Website",
  "summary": "Overall score: 82% ...",
  "fullReport": "# Site Health Report ...",
  "status": "READY"
}

Billing API

GET/api/billing

Get current subscription details and site usage for the authenticated organization.

Response
{
  "plan": { "name": "Starter", "price": 49, "sites": 1 },
  "status": "ACTIVE",
  "currentPeriodStart": "2026-07-01T00:00:00.000Z",
  "currentPeriodEnd": "2026-08-01T00:00:00.000Z",
  "cancelAtPeriodEnd": false,
  "siteUsage": { "current": 1, "max": 1 }
}
POST/api/stripe/checkout

Create a Stripe Checkout session to subscribe to a plan.

Request Body
{
  "planId": "PRO"
}
Response
{
  "url": "https://checkout.stripe.com/..."
}
POST/api/stripe/portal

Create a Stripe Customer Portal session to manage billing.

Response
{
  "url": "https://billing.stripe.com/..."
}

Need help? Contact us or visit the SiteHalo homepage.