ConvictionRead

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.

Experimental research, not investment advice. Experimental research and education, not investment advice. Grades are the output of an automated, experimental model, not recommendations. Full disclaimer.

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": 0.61,
  "factors": { "quality": 0.7, "valuation": 0.4, "momentum": 0.6, "health": 0.8 }
}
  • 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..1 scores from the same nightly run shown on /grade.
  • as_of is the snapshot date of the underlying run; grades update nightly, not in real time.

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 the engine itself, see /acquire.