API Commons OpenLint API

A small, OpenAPI-first HTTP API from API Commons — lint API artifacts, list the built-in rulesets and supported formats, and validate a ruleset, all over HTTP. It runs the OpenLint engine (@openlint/* packages), the same engine as the openlint CLI, so the API, CLI and the validator all agree.

The API defines itself with OpenAPI (openapi.yaml) and serves it at GET /openapi.yaml — so it's lintable by OpenLint, too.

Run

npm install
npm start              # http://localhost:8080  (PORT to override)

With Docker:

docker build -t common-openlint-api .
docker run -p 8080:8080 common-openlint-api

Endpoints

Method	Path	Description
POST	/lint	Lint an artifact ({ content, format?, ruleset? }) → diagnostics + counts
GET	/rulesets	The built-in rulesets (spectral:oas, :asyncapi, :arazzo) and their rules
POST	/rulesets/validate	Structurally validate a ruleset (alias, object, or YAML/JSON string)
GET	/formats	Supported artifact formats
GET	/openapi.yaml	This API's OpenAPI definition
GET	/health	Health check

Example

curl -s -X POST http://localhost:8080/lint \
  -H 'content-type: application/json' \
  -d '{"format":"openapi","content":"openapi: \"3.0.3\"\ninfo: {title: T, version: \"1\"}\npaths: {}\n"}'

{ "total": 3, "counts": { "error": 0, "warn": 3, "info": 0, "hint": 0 },
  "diagnostics": [ { "code": "oas3-api-servers", "severity": "warn", "message": "..." } ] }

ruleset accepts a built-in alias ("spectral:oas", "spectral:asyncapi", "spectral:arazzo"), or a full ruleset definition object (data form) that may extends the built-ins — the OpenLint ruleset format.

Part of the API Commons governance tooling

This API is the HTTP surface other tools can build on. Related: common-openlint-validator (browser playground, validator.apicommons.org), common-openlint-mcp (AI), common-openlint-pipeline (CI), and the OpenLint engine and CLI. Rules are catalogued at apicommons.org/rules.

---

A project of API Evangelist, maintained openly under API Commons. Apache-2.0.