REST API

API Documentation

Integrate WMSS audits into your workflow. Launch analyses, retrieve results, and compare sites programmatically.

Introduction

The WMSS REST API lets you launch website audits, poll for results, and retrieve site data programmatically. All requests and responses use JSON. The API is available on the Enterprise plan.

Base URL

https://wmss.io/api

Response format

All responses are JSON. Successful responses return the resource directly or wrapped in a {data, meta} envelope for lists.

Authentication

Authenticate every request by including your API key in the Authorization header as a Bearer token.

Header

Authorization: Bearer wmss_your_api_key_here

API keys are managed from your account. Sign in and go to API Keys to generate one.

Error response (invalid key)

401 Unauthorized 
{
    "errors": [
        {
            "code": "unauthorized",
            "message": "Invalid or missing API key."
        }
    ]
}

Errors

The API uses standard HTTP status codes. Error responses always include an error code and a human-readable message.

Error response shape 
{
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}
Code Meaning
400Bad Request — invalid parameters or malformed JSON.
401Unauthorized — missing or invalid API key.
403Forbidden — your plan does not include API access.
404Not Found — the requested resource does not exist.
429Too Many Requests — rate limit exceeded. Retry after the delay indicated in the Retry-After header.
500Internal Server Error — something went wrong on our end.
POST /api/analyze

Start a new website analysis. Returns immediately with a pending analysis object.

Request body

Parameter Type Required Description
url string Yes The full URL of the website to analyze (must include https://).
tier string No "free" (frontend only) or "paid" (frontend + backend). Defaults to "free".

Example request

curl -X POST https://wmss.io/api/analyze \
  -H "Authorization: Bearer wmss_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "tier": "free"}'

Example response — 202 Accepted

{
    "id": "01HQ3X...",
    "url": "https://example.com",
    "tier": "free",
    "status": "pending",
    "created_at": "2026-03-12T10:30:00+00:00"
}
GET /api/analysis/{id}

Retrieve a single analysis by ID. Includes check results when the analysis is completed.

Path parameters

Parameter Type Description
id string (UUID) The analysis UUID returned by POST /api/analyze.

Example request

curl https://wmss.io/api/analysis/01HQ3X... \
  -H "Authorization: Bearer wmss_your_api_key"

Example response — while running

{
    "id": "01HQ3X...",
    "url": "https://example.com",
    "status": "running",
    "cms": "wordpress",
    "cms_version": "6.4.2",
    "overall_score": null,
    "scores": null,
    "check_results": []
}

Example response — when completed

{
    "id": "01HQ3X...",
    "url": "https://example.com",
    "status": "completed",
    "cms": "wordpress",
    "cms_version": "6.4.2",
    "overall_score": 72,
    "scores": {
        "performance": 65,
        "security": 80,
        "seo": 75,
        "accessibility": 60,
        "best_practices": 82
    },
    "check_results": [
        {
            "check": "HttpSecurityHeadersCheck",
            "category": "security",
            "score": 20,
            "severity": "major",
            "passed": false,
            "data": {
                "missing": ["content-security-policy", "permissions-policy"],
                "present": ["strict-transport-security", "x-frame-options", "x-content-type-options", "referrer-policy"]
            }
        }
    ],
    "created_at": "2026-03-12T10:30:00+00:00",
    "completed_at": "2026-03-12T10:31:12+00:00"
}
GET /api/analysis/{id}/progress

Poll the real-time progress of a running analysis.

Poll this endpoint every 2-3 seconds while status is "running". Stop when status becomes "completed" or "failed".

Example request

curl https://wmss.io/api/analysis/01HQ3X.../progress \
  -H "Authorization: Bearer wmss_your_api_key"

Example response

{
    "status": "running",
    "checks_total": 20,
    "checks_done": 14,
    "cms": "wordpress",
    "current_check": "FontOptimizationCheck"
}
GET /api/sites

List all sites belonging to your organization.

Example request

curl https://wmss.io/api/sites \
  -H "Authorization: Bearer wmss_your_api_key"

Example response

{
    "data": [
        {
            "id": "01HQ4Y...",
            "url": "https://client-a.com",
            "cms": "wordpress",
            "last_analyzed_at": "2026-03-11T14:20:00+00:00",
            "latest_score": 85,
            "active": true
        },
        {
            "id": "01HQ5Z...",
            "url": "https://client-b.com",
            "cms": "magento2",
            "last_analyzed_at": "2026-03-10T09:15:00+00:00",
            "latest_score": 62,
            "active": true
        }
    ],
    "meta": {
        "total": 2,
        "page": 1,
        "per_page": 25
    }
}
GET /api/sites/{id}/audits

List all audits for a specific site, ordered by date descending.

Path parameters

Parameter Type Description
id string (UUID) The site UUID.

Example request

curl https://wmss.io/api/sites/01HQ4Y.../audits \
  -H "Authorization: Bearer wmss_your_api_key"

Example response

{
    "data": [
        {
            "id": "01HQ6A...",
            "url": "https://client-a.com",
            "status": "completed",
            "tier": "free",
            "overall_score": 85,
            "created_at": "2026-03-11T14:20:00+00:00",
            "completed_at": "2026-03-11T14:21:05+00:00"
        },
        {
            "id": "01HQ2B...",
            "url": "https://client-a.com",
            "status": "completed",
            "tier": "paid",
            "overall_score": 78,
            "created_at": "2026-03-05T10:00:00+00:00",
            "completed_at": "2026-03-05T10:02:30+00:00"
        }
    ],
    "meta": {
        "total": 2,
        "page": 1,
        "per_page": 25
    }
}
GET /api/compare

Compare scores across multiple sites. Requires 1 to 10 site IDs.

Query parameters

Parameter Type Required Description
siteIds[] string[] Yes Array of site UUIDs to compare (1 to 10).

Example request

curl "https://wmss.io/api/compare?siteIds[]=01HQ4Y...&siteIds[]=01HQ5Z..." \
  -H "Authorization: Bearer wmss_your_api_key"

Example response

{
    "sites": [
        {
            "id": "01HQ4Y...",
            "url": "https://client-a.com",
            "overall_score": 85,
            "scores": {
                "performance": 80,
                "security": 90,
                "seo": 85,
                "accessibility": 78,
                "best_practices": 92
            }
        },
        {
            "id": "01HQ5Z...",
            "url": "https://client-b.com",
            "overall_score": 62,
            "scores": {
                "performance": 55,
                "security": 70,
                "seo": 60,
                "accessibility": 50,
                "best_practices": 75
            }
        }
    ]
}