Docs · v1

API reference

The endpoints the Aetos SEO WordPress plugin (and aetosseo.com) call to talk to our Cloudflare Worker. v1 stable. Last updated 2026-08-10.

Base URLhttps://aetos-api.sa7fy-af.workers.dev

Principles

Public-first

Public endpoints are designed to be called without a session token. Authenticated admin endpoints live under /admin/* and require a bearer token (not documented publicly).

Signed where it matters

License check responses carry a server-side Ed25519 signature. The plugin refuses to honor an unsigned response. This is the authoritative gate; local checks are defense-in-depth.

Stable URLs

Versioning is in the path (/v1/). We will never break a v1 endpoint contract. New shape goes to /v2/.

Conservative status codes

200 = success, 400 = validation failure, 401 = auth failure (admin endpoints), 404 = unknown resource, 429 = rate limited, 500 = server error. No 2xx-with-error-in-body anti-pattern.

Strict CORS

Public endpoints accept POST from aetosseo.com and from licensed plugin sites. No wildcard origin.

Endpoints

Health

GET/healthzPublic

Worker liveness probe. Returns 200 + timestamp when the database is reachable.

Response

{ "ok": true, "time": 1716200000000 }

Public — License (called by the WP plugin)

POST/v1/license/checkPublic · plugin sends license key + domain in body

Plugin liveness check. Returns a server-signed Ed25519 response with the license tier, expiry, and a nonce. Plugin verifies the signature before honoring the response.

Request body

{ "license_key": "AETOS-XXXX-XXXX-XXXX", "domain": "example.com", "plugin_version": "4.0.15" }

Response

{ "ok": true, "tier": "pro", "status": "active", "expires_at": 1747756800000, "nonce": "...", "signature": "..." }

GET/v1/dl?license=AETOS-...Public · license key required

Versioned ZIP download. The Worker resolves the manifest entry for the current version and streams the KV-stored ZIP. If the User-Agent embeds a literal "{LICENSE_KEY}" placeholder, the Worker substitutes the real key in the headers (legacy updater recovery path).

Response

Binary ZIP stream + Content-Disposition header

Public — Newsletter

POST/v1/newsletter/subscribePublic

Subscribe to the weekly SEO and AI search research newsletter. If the Worker has RESEND_API_KEY set, the response is "pending_confirmation" and a confirmation email is sent. Otherwise (legacy fallback) the response is "subscribed" immediately.

Request body

{ "email": "you@example.com", "locale": "en", "source_label": "blog" }

Response

{ "ok": true, "status": "pending_confirmation" }  // or "subscribed", "already_subscribed", "resubscribed"

GET/v1/newsletter/confirm?token=...Public · token from confirmation email

Confirms a pending subscription. Redirects to /newsletter/confirmed/ (or /ar/newsletter/confirmed/) on success. Returns a 404 HTML page on invalid/used token.

Response

302 Location: https://aetosseo.com/newsletter/confirmed/

Public — Orders

POST/v1/orders/createPublic

Creates a pending order for a Pro or Agency tier. Returns an order ID + payment instructions URL. Includes server-side honeypot for spam (silent reject if the hidden "website" field is filled).

Request body

{ "tier": "pro", "domain": "example.com", "email": "you@example.com", "country": "EG", "method": "bank_usd" }

Response

{ "ok": true, "order_id": "AET-...", "amount_cents": 7900, "currency": "USD" }

Error shape

Every error response uses the same shape. error is a stable, machine-readable code (no localized strings). detail is human-readable and may be omitted in production.

{ "ok": false, "error": "validation_failed", "issues": [ ... ] }

Authentication

Public endpoints require no token. The license check and the plugin ZIP download both authenticate the requester by the license key in the body or query string — the Worker never accepts a license that fails Ed25519 round-trip verification or whose tuple HMAC is invalid. See the security policy for the full threat model.

Found a discrepancy? Email us — we update this page on every patch release.