Docs

Grade API

The endpoint behind /grade, documented for the curious. It is a demo surface, not a product API: no key, no SLA, a shared daily cap, and the contract can change without notice.

Request

POST /api/grade
Content-Type: application/json

{ "ticker": "AAPL", "email": "you@example.com" }

ticker: required; a US equity symbol. Normalized to uppercase.
email: required and must be valid. It is recorded as a demand signal and nothing else (privacy).

Response (200)

{
  "ticker": "AAPL",
  "found": true,
  "experimental": true,
  "disclaimer": "...",
  "grade": "B-",
  "as_of": "2026-06-12",
  "composite": 59,
  "factors": { "quality": 70, "valuation": 40, "momentum": 55, "health": 60 }
}

found: false (still 200) means the ticker is not in the graded universe; no grade fields are present.
grade is a letter grade; composite and the four factors are 0–100 scores from the same nightly run shown on /grade.
as_of is the common UTC score-snapshot date for the composite and factor scores. It is not a separate publication date or the fiscal date of the underlying fundamentals. Grades update nightly, not in real time. Missing scores or dates remain unknown, rather than zero or a guessed date.

Errors

400 bad_request: invalid JSON, missing or invalid email, or missing ticker. The detail field says which.
405 method_not_allowed: anything but POST.
429 daily_limit: the shared daily cap is exhausted; try again tomorrow.

Error bodies are { "error": "<code>", "detail": "<human message>" }.

Limits and framing

This endpoint exists so the demo on /grade works and so anyone can sanity-check a grade without scraping the site. It shares one hard daily cap across all callers, has no authentication, no versioning, and no uptime promise. If you want to understand the system, see How it works.