API Reference - validate.al

Base URL: https://api.validate.al/v1 Format: requests and responses are JSON (Content-Type: application/json).

Authentication

Send your API key in the X-API-Key header. The same key works for email validation and scanning. Get it from the portal (Settings → API Key).

curl -H "X-API-Key: your-api-key" https://api.validate.al/v1/scans

Account endpoints (/auth/me, /auth/settings, /auth/rotate-api-key, two-factor setup) take a JWT instead, sent as Authorization: Bearer <token>. You get the token from /auth/verify-email (after confirming your address) or /auth/login. /validate_email and /me/quota accept either.

Endpoints

Area	Endpoint	Purpose
Email validation	`POST /validate_email`	Check one email address.
Scanning	`POST /request-scan`	Request a new scan.
Scanning	`GET /scans`	List your scans.
Scanning	`GET /scans/{id}`	Get one scan and its status.
Scanning	`GET /scans/{id}/report`	Get a scan’s full report.
Scanning	`DELETE /scans/{id}`	Delete a finished scan and its report.
Account	`GET /me/quota`	Your plan and what is left today.
Account	`POST /auth/rotate-api-key`	Replace your API key.
Account	`POST /auth/register`	Create an account; emails a confirmation link.
Account	`POST /auth/verify-email`	Confirm the address with the emailed token; signs in.
Account	`POST /auth/resend-verification`	Send the confirmation link again.
Account	`POST /auth/login`	Sign in (returns a JWT).
Account	`GET /auth/me`	Current user info.
Account	`PUT /auth/settings`	Update display name.
Account	`POST /auth/totp/setup`	Start two-factor authentication setup.
Account	`POST /auth/totp/verify`	Confirm two-factor setup with a code.
Health	`GET /health`	API health. No key needed.
Health	`GET /healthz`	Email validator health. No key needed; answers `OK` as plain text.

Errors

Errors use standard HTTP status codes with a JSON body. Reaching a daily limit gives 429 with a Retry-After header; see Plans and limits. Scanning and account endpoints return {"detail": "message"}; email validation returns {"detail": {"error": "message"}}. See Email validation errors for what each email status means.