WPReadme Preview API

A free JSON API for parsing and validating WordPress plugin readme.txt files, the same engine behind the in-browser validator. No API key, no registration.

Quickstart

Send the readme.txt contents to an endpoint as JSON ({"readme": "..."}) or as a raw text/plain body:

cURL

curl -s https://wpreadme.ir/api/validate \
  -H "Content-Type: application/json" \
  -d '{"readme": "=== My Plugin ===\nContributors: me\nTags: seo\nStable tag: 1.0.0\nLicense: GPLv2 or later\n\nA plugin.\n\n== Description ==\n\nIt works.\n\n== Changelog ==\n\n= 1.0.0 =\n* Initial release"}'

The response contains a summary (score, passed/failed/warning counts) and one check object per rule, each with a stable id, a category, a status, and a tip showing exactly which line to add when something is missing.

Code samples

The same request from PHP and JavaScript:

PHP

<?php
$readme = file_get_contents('readme.txt');

$ch = curl_init('https://wpreadme.ir/api/validate');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['readme' => $readme]),
    CURLOPT_RETURNTRANSFER => true,
]);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (isset($result['error'])) {
    exit($result['error']['code'] . ': ' . $result['error']['hint'] . PHP_EOL);
}

echo "Score: {$result['summary']['score']}/100" . PHP_EOL;
foreach ($result['checks'] as $check) {
    if ($check['status'] !== 'pass') {
        echo "[{$check['status']}] {$check['label']}" . PHP_EOL;
        echo '    ' . str_replace(PHP_EOL, PHP_EOL . '    ', $check['tip']) . PHP_EOL;
    }
}

JavaScript

const response = await fetch('https://wpreadme.ir/api/validate', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({readme}),
});

if (!response.ok) {
  const {error} = await response.json();
  throw new Error(`${error.code}: ${error.hint ?? error.message}`);
}

const {summary, checks} = await response.json();
console.log(`Score: ${summary.score}/100`);

for (const check of checks.filter((c) => c.status !== 'pass')) {
  console.log(`[${check.status}] ${check.label}`);
  console.log(`    ${check.tip.replaceAll('\n', '\n    ')}`);
}

Both examples print the score followed by every check that needs attention, with its tip. Swap /api/validate for /api/parse to get the structured file contents instead of a validation report.

Endpoints

POST
/api/parse
Parse readme.txt into structured JSON: plugin name, headers, sections, FAQ items, and screenshots.
POST
/api/validate
Validate readme.txt against WordPress.org requirements with per-check statuses, tips, and a 0-100 score.

Machine-readable specification

The full API surface is published as an OpenAPI 3.1 specification (also at /api/openapi.json) with unique operation IDs and typed schemas for every request and response, ready for code generation and LLM function calling. Agent instructions live in llms.txt.

Errors

Every error is JSON with a machine-readable code, message, and resolution hint:

JSON

{
  "error": {
    "code": "missing_readme",
    "message": "Missing required field 'readme'",
    "hint": "The JSON body must look like {"readme": "readme.txt contents"}"
  }
}

Limitations

No authentication, the API is free and open.
No rate limits enforced, please be reasonable.
1 MB maximum body size; WordPress.org caps readme.txt at 10 KB anyway.
POST only; other methods answer 405 with a JSON envelope.

Use it from this site

Prefer point-and-click? Paste your readme.txt into the editor on the homepage and the validator panel runs these same checks live.

The API is free, too

WPReadme Preview and its API are provided free of charge. If they save you time, consider supporting the development and hosting costs.

Support the Project