AI spec review
An LLM design review of an OpenAPI spec — the inconsistencies and anti-patterns that lint rules can't catch, as severity-tagged, fixable findings.
Spectral linting catches mechanical issues — a missing operationId, an undocumented response. AI spec review catches the design-judgement issues that rules can't express: naming that drifts across endpoints, response shapes that don't match their siblings, a mutating operation with no auth, inconsistent pagination, REST anti-patterns. It reads the whole spec the way a reviewer would.
It runs on your connected LLM provider (the same bring-your-own-key the other AI features use).
What you get
Run a review and Spec0 returns a list of findings, each with:
- a severity — critical, warning, or suggestion;
- the location — the JSON path and operationId it applies to;
- a plain-English summary of the issue; and
- a concrete suggested fix.
Findings render as a checklist on the API detail page, so you can work through them.
Running a review
Open an API in the dashboard and click Run AI Review on the detail page. Reviews are cached per spec version: the result is keyed by the spec's content hash, so:
- re-opening the page loads the latest cached review instantly;
- re-running on an unchanged spec returns the cached result rather than spending tokens;
- a new publish (new content) invalidates the cache, so the next review reflects the new spec.
Availability
AI spec review is a plan-gated feature (it requires a plan that includes AI_SPEC_CRITIC; free-tier orgs get a paywall). Like the other AI features it routes to your own provider key first, falling back to Spec0-hosted capacity where available — see AI features for the routing and cost-attribution model.
How it relates to linting
Use both: Spectral rulesets enforce your hard, mechanical standards in CI (and gate publishes via spec0 lint); AI spec review is an on-demand design critique for the judgement calls rules can't encode. The lint score is also what the get_api_health MCP tool reports to agents.
See also
- AI features — the provider connection and where calls go.
- Governance — Spectral rulesets and the lint score.
spec0 lint— linting from the CLI.