Specoria API, MCP and GitHub Action

What the API does

• POST https://app.specoria.com/v1/scan runs the same free test as specoria.com on one website and returns the result as JSON: score 0-100, level, critical blockers and every check with its status and weight.
• The scan reads public pages on the given domain only, over https, and never follows a redirect to another domain. Marketplace pages and excluded domains are refused.
• The request is synchronous. Page reading has a 20-second budget, so allow a client timeout of at least 60 seconds.
• If the same domain was scanned in the last 6 hours, the stored result is returned without visiting the site again ("cached": true).
• The API is versioned under /v1. New fields may be added to a response; existing fields won’t change meaning within v1.

API keys

• Create a key in the Specoria panel: Team and profile → API keys. Project admins and commercial approvers can create and revoke keys; up to 10 active keys per organization.
• The key is shown once. We store only its SHA-256 hash and the first 12 characters for display.
• Send it as a header: Authorization: Bearer spk_…, never in a URL. The API doesn’t allow browser (CORS) calls, so keep the key on a server or in CI secrets.
• A key belongs to your organization and only sees your organization’s projects. It stops working when it is revoked or when the person who created it leaves the team.

Limits

• Per key: 60 scans per hour and 500 scans per day; MCP read tools: 300 requests per hour.
• All keys of one organization together: 60 scans per hour and 500 scans per day (more keys don’t raise the limit).
• Cached results count towards the limit; invalid requests (bad URL, marketplace, excluded domain) don’t.
• Over the limit you get HTTP 429 with a Retry-After header. Successful responses carry X-RateLimit-Limit and X-RateLimit-Remaining for the hourly window.
• The API has its own share of the service’s daily scan capacity: 100 new scans per day across all API users (cached results don’t count), so it never uses up the free test on our site. When the share or the overall capacity is used up you get HTTP 503 "busy".

Request

Example

curl -sS --max-time 90 -X POST https://app.specoria.com/v1/scan \
  -H "Authorization: Bearer $SPECORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","lang":"en"}'

Response

On success: {"success": true, "data": {…}}. The fields of data:

{
  "success": true,
  "data": {
    "api_version": "v1",
    "model_version": "v2.4",
    "domain": "specoria.com",
    "scanned_at": "2026-10-08T14:02:48.579Z",
    "cached": false,
    "score": 75,
    "level": "partial",
    "insufficient": false,
    "blockers": [],
    "checks": [
      {
        "id": "bots_search",
        "status": "pass",
        "weight": 8,
        "…": "…"
      },
      {
        "id": "waf_access",
        "status": "pass",
        "weight": 8,
        "…": "…"
      },
      {
        "id": "no_js",
        "status": "na",
        "weight": 5,
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Abbreviated example built from our own free-test result for specoria.com, scanned 2026-10-08 (full JSON on the method page). How the free test works

Errors

{"success": false, "error": "…", "message": "…"}

MCP server for your projects

POST https://app.specoria.com/v1/mcp speaks MCP over Streamable HTTP (stateless, JSON responses) with the same key and limits. Tools:

Client configuration (for clients that accept a URL and headers)

{
  "mcpServers": {
    "specoria": {
      "type": "http",
      "url": "https://app.specoria.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${SPECORIA_API_KEY}"
      }
    }
  }
}

GitHub Action

A small action (action.yml plus one JavaScript file, Node.js built-ins only) calls /v1/scan, writes a summary table to the job and fails the step when the score is below min-score.

- uses: <owner>/<repo>/integrations/github-action@<ref>
  with:
    url: https://example.com
    api-key: ${{ secrets.SPECORIA_API_KEY }}
    min-score: 70

• Inputs: url, api-key, min-score (default 0), fail-on-blockers, lang, share. Outputs: score, level, blockers, passed, share-url.
• A missing score (too little measured) fails the step, because there is nothing to compare.
• It isn’t listed on the GitHub Marketplace yet. Write to contact@specoria.com and we’ll send you the action files to put in your repository.

What the API doesn’t do

• No deep audit, agent simulation, AI visibility or ChatGPT Shopping measurement: those stay in the panel and plans.
• No AI model is called during an API scan.
• No writes: it never changes your store or your project, and there are no webhooks.
• No browser calls (CORS) and no keys in URLs.

Questions

contact@specoria.com