Clara

API Agent-Readiness Analyzer -- 48 checks across 8 pillars that answer one question:

Can an AI agent reliably use this API?

AI agents are calling APIs at scale. Most APIs aren't ready for them. Clara analyzes your OpenAPI spec and tells you exactly what's broken, what to fix first, and how to fix it.

Quick Start

# Analyze an API spec
npx @sterlingchin/clara analyze ./openapi.yaml

# Scan a whole project for OpenAPI specs
npx @sterlingchin/clara scan .

# Generate a remediation plan with fix prompts
npx @sterlingchin/clara remediate ./openapi.yaml

No install required. Just npx and go.

What You Get

==================================================================
  Clara - AI Agent API Readiness Analyzer
==================================================================

  API: Fleet Logistics API v1.0.0

  OVERALL SCORE

    [████████████████████░░░░░░░░░] 72%

    AI Agent Ready

  PILLAR SCORES

    ██████████  100%  Discoverability
    █████████░   92%  Metadata
    ████████░░   85%  Predictability
    ███████░░░   70%  Errors

  PRIORITY FIXES

    #1 [CRITICAL] error schema defined
       ERR_002 | 8 endpoints affected
       Fix: Define structured error schema with code and message

    #2 [HIGH] 4xx responses documented
       ERR_001 | 6 endpoints affected
       Fix: Document 400, 401, 403, 404 responses

The 8 Pillars

Clara evaluates your API across 8 pillars of agent-readiness:

Pillar	Checks	What It Measures
Metadata	6	operationIds, summaries, descriptions, tags
Errors	12	Error schemas, codes, messages, retry guidance
Introspection	8	Parameter types, required fields, enums, examples
Naming	6	Consistent casing, RESTful paths, HTTP semantics
Predictability	6	Response schemas, pagination, date formats
Documentation	6	Auth docs, rate limits, external links
Performance	4	Response times, caching, rate limit headers
Discoverability	4	OpenAPI version, server URLs, contact info

Total: 48 static checks + 4 live probe checks.

Scoring

Each check is weighted by severity:

Severity	Weight	Meaning
Critical	4x	Agent cannot function without this
High	2x	Agent will struggle significantly
Medium	1x	Agent experience degraded
Low	0.5x	Nice to have for agent reliability

AI Agent Ready = Score >= 70% with zero critical failures.

CLI Commands

Command	Description
clara analyze <spec>	Run all checks against an OpenAPI spec
clara scan <dir>	Find and analyze all OpenAPI specs in a directory
clara docs <spec>	Generate AI-ready documentation from a spec
clara remediate <spec>	Generate a prioritized fix plan with code prompts
clara setup	Install Clara as a Claude Code /clara slash command

Common Options

# Verbose output with per-endpoint details
clara analyze ./openapi.yaml --verbose

# Export reports (JSON, Markdown, CSV)
clara analyze ./openapi.yaml -o report.json -o report.md

# Live probing against a running API
clara analyze ./openapi.yaml --probe --base-url https://api.example.com

# With auth
clara analyze ./openapi.yaml --probe --base-url https://api.example.com \
  --auth "Authorization: Bearer your-token"

Claude Code Integration

Clara ships as a Claude Code slash command. Install it once and use /clara in any session:

# Install for current project
npx @sterlingchin/clara setup

# Install globally (all projects)
npx @sterlingchin/clara setup --global

Then type /clara inside Claude Code.

For a full Postman agent workflow, see the postman-claude-code-commands repo, which includes the Postman Agent file for Claude Code.

Postman Integration

Clara diagnoses. Postman treats.

Clara identifies what's broken in your API spec. Postman Agent Mode and the Postman MCP Server can then fix the issues directly, using Clara's output as the remediation blueprint.

Install

# Use without installing (recommended)
npx @sterlingchin/clara analyze ./spec.yaml

# Install globally
npm install -g @sterlingchin/clara

# Install in project
npm install --save-dev @sterlingchin/clara

CI/CD

# .github/workflows/clara.yml
name: API Quality Check
on: [push, pull_request]
jobs:
  clara:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npx @sterlingchin/clara analyze ./openapi.yaml --quiet

Exit code 0 = AI-ready. Exit code 1 = not ready. Exit code 2 = error.

License

Apache 2.0

Built for Postman by Sterling Chin.