API Documentation

Skannr REST API v1

Base URL

https://api.skannr.app/api/v1/

Authentication

All endpoints (except login and register) require a bearer token in the Authorization header:

Authorization: Bearer <token>

Tokens are obtained via the login endpoint and can be refreshed using the refresh endpoint. Access tokens expire after 15 minutes; refresh tokens expire after 7 days.

Authentication

POST/auth/login

Authenticate with email and password. Returns access and refresh tokens.

POST/auth/register

Create a new account with name, email, and password.

POST/auth/token/refresh

Exchange a refresh token for a new access token.

POST/auth/mfa/setup

Generate a TOTP secret and QR code for MFA setup.

POST/auth/mfa/enable

Enable MFA by verifying a TOTP code.

DELETE/auth/mfa

Disable MFA (requires password confirmation).

Targets

GET/targets

List all scan targets for the authenticated user.

POST/targets

Add a new target (IP, domain, or CIDR range).

GET/targets/:id

Get details for a specific target.

PUT/targets/:id

Update target configuration (label, scan profile, interval).

DELETE/targets/:id

Delete a target and its associated data.

Scans

GET/scans

List all scans across all targets.

GET/scans/:id

Get scan details including status and progress.

GET/scans/:id/results

Get port scan results for a completed scan.

GET/scans/:id/summary

Get per-host summary of open, filtered, and closed ports.

POST/targets/:id/scan

Trigger an on-demand scan for a specific target.

POST/scans/trigger-all

Trigger scans for all enabled targets.

Alerts

GET/alerts

List all alerts (new ports, closed ports, TLS changes).

PUT/alerts/:id/acknowledge

Acknowledge an alert.

PUT/alerts/:id/resolve

Mark an alert as resolved.

Billing

GET/billing/status

Get current subscription status and plan details.

POST/billing/checkout

Create a Stripe Checkout session for a new subscription.

POST/billing/portal

Generate a Stripe Customer Portal link for managing billing.

POST/billing/change-plan

Upgrade or downgrade the current subscription plan.

Score & Achievements

GET/score

Get the security score with level, XP, and category breakdown.

GET/streak

Get current and best scan streak data.

GET/achievements

List all achievements with earned status and timestamps.

Rate Limits

API requests are rate-limited per account based on your subscription plan. Rate limit headers are included in every response:

X-RateLimit-Limit — maximum requests per window.
X-RateLimit-Remaining — requests remaining in the current window.
X-RateLimit-Reset — Unix timestamp when the window resets.

Errors

All errors return a JSON object with a message field. HTTP status codes follow standard conventions: 400 for bad requests, 401 for unauthorized, 403 for forbidden, 404 for not found, and 429 for rate-limited.