Score a spec via API

Paste a spec, get a grade. Elva’s scoring engine runs as a public HTTP API at https://api.getelva.ai so you can score any OpenAPI document straight from your terminal, with no account and no key.

List the check catalog

GET /api/review/checks returns the full set of checks the engine runs, so you can see exactly what your spec is graded against before you submit anything. Each entry carries an id, category, name, description, severity, and weight.

 
  curl https://api.getelva.ai/api/review/checks

The response is a flat array. A single element looks like this:

 
  {
    "id": "design-method-semantics",
    "category": "Design",
    "name": "HTTP Method Semantics & Idempotency",
    "description": "GET has no requestBody; PUT/DELETE are idempotent; PATCH is partial; POST is non-idempotent unless protected by Idempotency-Key.",
    "severity": "high",
    "weight": 9
  }

Score a spec

POST /api/review takes your OpenAPI document and hands back category scores, a full per-check breakdown, and an overall grade. You can send the spec two ways, and the engine handles both transparently.

 
  curl -X POST https://api.getelva.ai/api/review \
    -H "Content-Type: text/plain" \
    --data-binary @openapi.yaml

 
  curl -X POST https://api.getelva.ai/api/review \
    -H "Content-Type: application/json" \
    --data-binary @openapi.json

What comes back

A successful call returns one object with four top-level fields. scores breaks the result out by the four weighted categories, checks lists every individual check result, and overallScore / overallGrade roll it all up.

 
  {
    "scores": {
      "Design": { "percentage": 82, "grade": "B" },
      "DeveloperExperience": { "percentage": 74, "grade": "C" },
      "AIReadiness": { "percentage": 66, "grade": "C" },
      "Security": { "percentage": 90, "grade": "A" }
    },
    "checks": [
      {
        "category": "AIReadiness",
        "id": "ai-op-ids",
        "status": "Pass",
        "comments": "All operations expose descriptive operationIds.",
        "weight": 9
      }
    ],
    "overallScore": 79,
    "overallGrade": "B"
  }

Each check reports status as Pass, Partial, or Fail, scored 1.0, 0.5, and 0.0 respectively and multiplied by its weight. Category percentages are weighted pass ratios; the overall score is the category-weighted average (Design 40, Developer Experience 35, AI Readiness 15, Security 10). Grades follow: A ≥ 88, B ≥ 76, C ≥ 64, D ≥ 50, otherwise F.

Response fields

Error responses

The endpoint fails fast and tells you why. Both errors return a JSON body with a single error field.