Skip to content

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
Start a scan, then read its report
request10 lines
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"
  1. POST/scanswaiting
  2. GET/scans/<scan id>waiting
  3. GET/scans/<scan id>/reportwaiting
responseNot started

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.

bashAuthorization: BearerAn illustration: the answers are written into the page, with numbers from the report of one of our test pages. This view never calls the service.

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 same API, with your key and from your account’s quota
  • 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.

  1. Make a key on your account page. It begins arb_ and its secret is shown once.
  2. Send it in the Authorization header of every request.
  3. 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: 401 and WWW-Authenticate: Bearer.
  • Never put the key in code that runs in a browser. The API is for servers and command-line tools.
every request
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
http13 lines

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.

  1. Make a key on your account page.
  2. Add the server to your assistant’s configuration: the /mcp endpoint on this site, with the key in the Authorization header.
  3. 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://rules is an index, and arablyzer://rules/en/<id> and arablyzer://rules/ar/<id> explain a rule in its language.
  • The /mcp endpoint has no sessions: each request stands alone, and answers in JSON.
mcpServers
1{2  "mcpServers": {3    "arablyzer": {4      "type": "http",5      "url": "https://arablyzer.com/mcp",6      "headers": { "Authorization": "Bearer arb_…" }7    }8  }9}
json9 lines

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:

  1. It scans the pages your workflow names, with your key and from your account’s quota.
  2. It waits for the scan, writes the score and the worst problems into the job summary, and fails the step at fail_on: critical, serious or none.
  3. It writes a SARIF file per page, so the findings appear in “Code scanning” on GitHub.
  • fail_on is critical, serious or none (the default). lang is the language of the summary and of the SARIF messages, ar or en.
  • Give urls for 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 with github/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:

  1. It checks the open page when you press “Check this page”.
  2. It shows the page’s score and its worst problems, and the score shows on its icon.
  3. 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: activeTab and storage, 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.

MethodPathWhat it does
POST/api/v1/scansStarts 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/scansYour 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}/reportThe scan’s report. Answers 409 until it has finished.
GET/api/v1/toolsThe tools: which run on a page and which run in the browser.
POST/api/v1/tools/{slug}/runsRuns one tool on a page, its rules alone. Read the result like any scan.
GET/api/v1/rulesThe 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.jsonThe 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.limit names 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-After says 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-Limit and X-Scans-Remaining.
  • Each key has a budget of requests per minute, reads included. Every answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. At a limit the answer is 429 with Retry-After in 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 to DELETE /api/reports/{id} to delete the scan and its report.
  • Where the service has accounts off, every route answers 503 with the code accounts_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.

  • 2keys per account, at most
  • 120requests a minute per key, reads included
  • reusedThe same page within ten minutes returns the same scan and takes no second one from the quota

The numbers come from the service’s settings, as they stand unless its operator changes them. Your account page reads your own.