Why?

LLM agents are increasingly calling APIs via tool-use. But most OpenAPI specs were written for human developers, not AI:

• Missing descriptions — the agent doesn't know when to call the endpoint
• No error responses — the agent can't handle failures gracefully
• Vague parameters — the agent guesses wrong values
• No schema types — the agent sends malformed requests

ai-api-lint scores your spec from 0–100 and tells you exactly what to fix, organized by 7 categories across 30+ rules. It can even auto-fix the most common problems.

Real-World Example

We ran ai-api-lint on a production commerce API (1,083 operations):

Score: 71.2 / Fair
4,195 findings (1,058 errors, 2,570 warnings, 567 info)

Top issues:
  AI042  No 4xx error response          1,058 ops
  AI013  No usage hint in description   1,045 ops
  AI034  Request body no description      449 ops

After --fix: 71.2 → 85+ (Good), with 3,500+ issues auto-resolved.

Install

pip install ai-api-lint

# Optional: YAML support
pip install ai-api-lint[yaml]

Quick Start

# Analyze your spec
ai-api-lint openapi.json

# Output example:
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#
#  POST /users  •  createUser
#   ✗ AI042  No 4xx client error response defined.
#   ⚠ AI034  Request body has no 'description'.
#   ⚠ AI014  Parameter 'name' has no description.
#
#  Overall Score: 71.2 / Fair
#  42 operations, 156 findings (12 errors, 98 warnings, 46 info)

Usage

Lint

# Basic
ai-api-lint openapi.json

# JSON output (for CI/CD pipelines)
ai-api-lint openapi.json --format json

# Fail CI if score is below threshold
ai-api-lint openapi.json --min-score 70

# Filter by severity
ai-api-lint openapi.json --severity warning   # errors + warnings only
ai-api-lint openapi.json --severity error     # errors only

# List all available rules
ai-api-lint --list-rules

Auto-Fix

The --fix flag automatically resolves common issues in your spec:

# Fix and show results (stdout)
ai-api-lint openapi.json --fix

# Save the fixed spec to a new file
ai-api-lint openapi.json --fix --output fixed.json

# Only apply safe fixes (Level 1 — no guessing)
ai-api-lint openapi.json --fix --level 1

# Preview what would be fixed, without modifying anything
ai-api-lint openapi.json --fix --dry-run

Fix Levels

Level 1 is always safe — it never changes existing data, only fills in gaps. Level 2 makes educated guesses based on patterns. Review the output before committing.

14 Built-in Fixers

Ordered by typical impact (number of issues resolved):

HTML Report

Generate a self-contained, single-file HTML report — no external dependencies, easy to share with your team:

# Generate report
ai-api-lint openapi.json --format html --output report.html

# Generate report with fix results included
ai-api-lint openapi.json --fix --format html --output report.html

# Open in browser
open report.html

What's in the report:

Features:

• Dark/light theme (auto-detects prefers-color-scheme)
• Print-friendly CSS
• Zero external dependencies (all CSS/SVG inline)

Rules

30+ rules across 7 categories, each with a severity level:

Scoring

Score = 100 - (total_penalty / operation_count)

Penalties:  ERROR = 20,  WARNING = 8,  INFO = 2

Grades:  ≥90 Excellent  |  ≥75 Good  |  ≥60 Fair  |  ≥40 Poor  |  <40 Critical

CI/CD Integration

# GitHub Actions example
- name: Lint API spec
  run: |
    pip install ai-api-lint
    ai-api-lint openapi.json --min-score 75 --severity warning

Exit codes:

• 0 — all clear (no errors or warnings)
• 1 — warnings found
• 2 — errors found or score below --min-score
• 3 — spec loading failed

Development

git clone https://github.com/SonAIengine/ai-api-lint.git
cd ai-api-lint
poetry install --with dev

# Test
poetry run pytest tests/ -v

# Lint
poetry run ruff check .
poetry run ruff format --check .

License

MIT