API Documentation
The Wallace Web Workers optimization engine is available as a REST API. Register a site to receive an API key, then use it to trigger runs and retrieve reports.
Authentication
All authenticated endpoints require a Bearer token in the Authorization header. Your API key is generated when you register a site and shown once.
Authorization: Bearer wwwk_your_api_key_here
Base URL
https://wallacewebworkers.com/api/v1
Endpoints
/api/v1/sitesNo auth requiredRegister a new site
Creates a site record and returns a one-time API key. Save the key — it is not stored in plaintext.
{
"name": "Acme Plumbing",
"url": "https://acmeplumbing.com",
"pageCount": 8,
"tier": "PRO",
"ownerName": "John Acme",
"ownerEmail": "john@acmeplumbing.com",
"businessDescription": "Residential plumbing in Nashville, TN",
"targetLocation": "Nashville, TN",
"targetKeywords": ["plumber Nashville", "emergency plumbing", "water heater repair"]
}{
"ok": true,
"data": {
"site": { "id": "...", "name": "Acme Plumbing", ... },
"apiKey": "wwwk_...",
"message": "Site registered. Save your API key — it will not be shown again."
}
}/api/v1/sites/:idGet site details
Returns the site record and metadata.
{ "ok": true, "data": { "id": "...", "name": "...", ... } }/api/v1/sites/:idUpdate site settings
Update any site field: page count, tier, keywords, etc.
{
"pageCount": 12,
"tier": "ENTERPRISE",
"targetKeywords": ["new keyword"]
}{ "ok": true, "data": { "id": "...", ... } }/api/v1/sites/:id/analyzeTrigger a manual optimization run
Starts a full optimization pipeline asynchronously. Returns immediately with a run ID.
{
"ok": true,
"data": {
"runId": "...",
"status": "RUNNING",
"message": "Optimization run started. Poll GET /api/v1/reports to check progress."
}
}/api/v1/sites/:id/reportsList optimization reports
Returns paginated list of all runs and their reports for a site.
{
"ok": true,
"data": {
"runs": [ { "id": "...", "status": "COMPLETED", "report": { ... } } ],
"limit": 20,
"offset": 0
}
}/api/v1/sites/:id/vitalsLatest Core Web Vitals
Returns the most recent PageSpeed Insights snapshot for the site.
{
"ok": true,
"data": {
"performanceScore": 87,
"lcp": 1820,
"cls": 0.04,
"fcp": 980,
...
}
}/api/v1/reports/:idGet a single report (JSON)
Returns the full report including all module results, scores, changes, and recommendations.
{
"ok": true,
"data": {
"id": "...",
"geoScore": 74,
"seoScore": 81,
"performanceScore": 87,
"summary": "...",
"changesMade": [...],
"recommendations": [...],
"geoOptimization": { ... },
...
}
}/api/v1/reports/:id/pdfExport report as PDF
Returns a PDF binary of the full report. Content-Disposition is set to attachment.
[PDF binary — application/pdf]
Error Format
All errors return a consistent JSON structure:
{
"ok": false,
"error": "Description of what went wrong"
}