spotlight-api

Work with Spotlight over HTTP — defined, of course, with OpenAPI.

spotlight-api is a small, OpenAPI-first HTTP service over the Spotlight engine. Lint an API artifact, list the built-in rulesets and supported formats, or validate a ruleset — all over a simple JSON API that runs the same @spotlight-rules engine as the CLI, VS Code extension, and browser validator, so every surface agrees. The API defines itself with OpenAPI and serves it at /openapi.yaml, so it's lintable by Spotlight too.

Run

npm install && npm start          # http://localhost:8080
# or
docker build -t spotlight-api . && docker run -p 8080:8080 spotlight-api

Endpoints

Method	Path	Description
POST	/lint	Lint an artifact ({ content, format?, ruleset? }) → diagnostics + counts
GET	/rulesets	Built-in rulesets and their rules
POST	/rulesets/validate	Structurally validate a ruleset
GET	/formats	Supported artifact formats
GET	/openapi.yaml	This API's OpenAPI definition

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

A ruleset may be a built-in alias (spotlight:oas) or a full ruleset definition that extends the built-ins — the spotlight-spec format.