The API and the MCP server
Everything the site does, from scanning a page and reading its report to running a single tool, is available from your code over a plain REST API, and from an AI assistant through an MCP server.
- Address
https://arablyzer.com/api/v1- Specification
- OpenAPI 3.1, built from the routes’ own definitions
- Quota
- Every scan comes out of your account’s own quota: the API has no second one
1curl -sS -X POST https://arablyzer.com/api/v1/scans \2 -H "Authorization: Bearer $ARABLYZER_API_KEY" \3 -H "Content-Type: application/json" \4 -d '{"url": "https://example.com/"}'56# the answer: { "data": { "id": "<scan id>", "state": "queued", … } }7curl -sS https://arablyzer.com/api/v1/scans/<scan id> \8 -H "Authorization: Bearer $ARABLYZER_API_KEY"9curl -sS https://arablyzer.com/api/v1/scans/<scan id>/report \10 -H "Authorization: Bearer $ARABLYZER_API_KEY"
1const base = 'https://arablyzer.com/api/v1'2const headers = {3 Authorization: `Bearer ${process.env.ARABLYZER_API_KEY}`,4 'Content-Type': 'application/json',5}67const started = await fetch(`${base}/scans`, {8 method: 'POST',9 headers,10 body: JSON.stringify({ url: 'https://example.com/' }),11}).then((r) => r.json())1213let scan = started.data14while (scan.state === 'queued' || scan.state === 'running') {15 await new Promise((resolve) => setTimeout(resolve, 3000))16 const next = await fetch(`${base}/scans/${scan.id}`, { headers })17 scan = (await next.json()).data18}1920const answer = await fetch(`${base}/scans/${scan.id}/report`, { headers })21const { data: report } = await answer.json()22console.log(report.score.overall, report.summary.bySeverity)
- POST
/scanswaiting - GET
/scans/<scan id>waiting - GET
/scans/<scan id>/reportwaiting
Press “Run the example” to see the three requests and their answers in order.
An answer is always { "data": … }, and an error { "error": { "code", "message" } }. The report is the same report the site shows and the command line prints, in the JSON schema the specification documents.
Four ways in, one key
All of them use the same API with your key, so every limit and every restriction applies. Choose your way in to see its path and its setup.
- The JSON reportThe same schema the site shows
- A summary in the chatThe score and the worst problems first
- A job summary and a SARIF fileFindings appear in Code scanning
- The score on the extension’s iconAnd the page’s worst problems
Plain REST, and one shape of answer
Scan a page, read its report, run a single tool and read the rule library. The report is the same report the site shows.
- Make a key on your account page. It begins
arb_and its secret is shown once. - Send it in the
Authorizationheader of every request. - Start a scan, ask for its state until it ends, then read its report. A scan takes about half a minute.
- The key alone opens the API. The sign-in cookie does not.
- A key that is invalid, revoked or missing gets the same answer:
401andWWW-Authenticate: Bearer. - Never put the key in code that runs in a browser. The API is for servers and command-line tools.
1Authorization: Bearer arb_…23# every answer4{ "data": … }56# every error7{ "error": { "code": "rate_limited", "message": "…" } }89# with each scan10X-Scans-Limit, X-Scans-Remaining1112# with every answer13RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
The MCP server for AI assistants
It lets an AI assistant such as Claude scan a page, read its report and explain a rule, from inside the conversation.
- Make a key on your account page.
- Add the server to your assistant’s configuration: the
/mcpendpoint on this site, with the key in theAuthorizationheader. - Ask the assistant to scan a page: it uses
scan_page, waits for it to end, and answers with the score, the counts and the worst problems first.
scan_pageScans a page, waits for it, and answers with the score, the counts and the worst problems first.get_reportThe summary of a scan started earlier.run_toolRuns one tool on a page.list_toolsLists the tools, filtered by a word.
- The rule library is resources:
arablyzer://rulesis an index, andarablyzer://rules/en/<id>andarablyzer://rules/ar/<id>explain a rule in its language. - The
/mcpendpoint has no sessions: each request stands alone, and answers in JSON.
1{2 "mcpServers": {3 "arablyzer": {4 "type": "http",5 "url": "https://arablyzer.com/mcp",6 "headers": { "Authorization": "Bearer arb_…" }7 }8 }9}
The GitHub Action is not published yet
The action cannot be added to your workflow today. Until it is published, your CI can scan through the same REST API with your key. This is what the action does:
- It scans the pages your workflow names, with your key and from your account’s quota.
- It waits for the scan, writes the score and the worst problems into the job summary, and fails the step at
fail_on:critical,seriousornone. - It writes a SARIF file per page, so the findings appear in “Code scanning” on GitHub.
fail_oniscritical,seriousornone(the default).langis the language of the summary and of the SARIF messages,aroren.- Give
urlsfor several pages (up to ten). Each page takes one scan from your account’s quota, and the same page within ten minutes takes none. - A SARIF file per page is written to the folder
sarif_dir, and uploaded withgithub/codeql-action/upload-sarif. Each rule in it points to its page on this site. - Your key is a repository secret, and the action never prints it in the log.
The Chrome extension is not published yet
The extension cannot be installed today. Until it is published, check any page here on the site by pasting its address. This is what the extension does:
- It checks the open page when you press “Check this page”.
- It shows the page’s score and its worst problems, and the score shows on its icon.
- It uses the API with the key you put in its settings; without one it opens the site’s scan page for you.
- Few permissions:
activeTabandstorage, and permission to reach the Arablyzer service alone. No background process runs, and no script is injected into pages. - No analytics and no remote code. The service is sent the address of the page you check, and nothing else.
Endpoints
All under /api/v1. Lists take limit (up to 100) and cursor, and answer meta.nextCursor when there is more.
The document is built from the same definitions the routes check against, and carries the report’s whole schema. Use it to generate a client in your language or to import the API into your tool.
| Method | Path | What it does |
|---|---|---|
| POST | /api/v1/scans | Starts a scan of a page (url, and optionally engines). If your account scanned the same page less than ten minutes ago, that scan is returned with reused: true and no quota is used. |
| GET | /api/v1/scans | Your account’s scans, newest first. |
| GET | /api/v1/scans/{id} | A scan’s state: queued, running, complete, partial or failed. |
| GET | /api/v1/scans/{id}/report | The scan’s report. Answers 409 until it has finished. |
| GET | /api/v1/tools | The tools: which run on a page and which run in the browser. |
| POST | /api/v1/tools/{slug}/runs | Runs one tool on a page, its rules alone. Read the result like any scan. |
| GET | /api/v1/rules | The rule library. |
| GET | /api/v1/rules/{ruleId} | A rule with its explanation in Arabic and English: why it matters, how to fix it, how it is detected. |
| GET | /api/v1/openapi.json | The OpenAPI 3.1 document. No key needed. |
Every error has a stable code to build on
Every error has a stable code to build on and a message in English to read. details carries what is needed, such as why an address was refused.
invalid_request400The request is not what the route takes: a body that is not JSON, or a field missing or extra.invalid_url400The address cannot be scanned: not a URL, a scheme other than http and https, too long, with credentials, or a port that is not allowed.
HTTP/1.1 400{ "error": { "code": "invalid_request", "message": "…"} }
unauthorized401A key that is missing, invalid or revoked.
HTTP/1.1 401WWW-Authenticate: Bearer{ "error": { "code": "unauthorized", "message": "…"} }
plan_limit403The account’s plan allows no more (details.limitnames the limit).
HTTP/1.1 403{ "error": { "code": "plan_limit", "message": "…", "details": { "limit": "…" }} }
not_found404No scan, tool or rule has this id.
HTTP/1.1 404{ "error": { "code": "not_found", "message": "…"} }
report_not_ready409The scan has no report yet, or never will because it failed (details.state).
HTTP/1.1 409{ "error": { "code": "report_not_ready", "message": "…", "details": { "state": "running" }} }
blocked_target422An address scans never reach: private, internal, or a name that does not resolve.
HTTP/1.1 422{ "error": { "code": "blocked_target", "message": "…"} }
rate_limited429A limit was reached: the scan quota, the request budget, or the limit on the scanned site.Retry-Aftersays when.
HTTP/1.1 429Retry-After: <seconds>{ "error": { "code": "rate_limited", "message": "…"} }
accounts_off503Accounts are off in this service, so there is no API.unavailable503The service is unavailable right now.
HTTP/1.1 503{ "error": { "code": "accounts_off", "message": "…"} }
Limits and repeats
- A scan comes out of your account’s own scan quota (the bucket the site draws on) and there is no second one. The operator may give the API a smaller share of it. Every scan answer carries
X-Scans-LimitandX-Scans-Remaining. - Each key has a budget of requests per minute, reads included. Every answer carries
RateLimit-Limit,RateLimit-RemainingandRateLimit-Reset. At a limit the answer is429withRetry-Afterin seconds. - Reads (a scan’s state, a report, tools, rules) cost no scan from the quota.
- The answer that creates a scan carries a
deleteToken, once: send it toDELETE /api/reports/{id}to delete the scan and its report. - Where the service has accounts off, every route answers
503with the codeaccounts_off.
The key comes from your account, and its secret is shown once
It begins arb_ and only its hash is kept, so if you lose it, make another. Keep it as an environment variable, never in code, and revoke it whenever you like.
The numbers come from the service’s settings, as they stand unless its operator changes them. Your account page reads your own.