# ThinkReasonLearn API > Pretrained, explainable prediction models (judges) you can call from code or a coding agent. Each model scores an input and returns the reasons: what pulled the score up or down. Use them in a generate → score → improve loop. About $0.01 a call, a few seconds each. Base URL: https://api.thinkreasonlearn.com/v1. Auth: `Authorization: Bearer $TRL_API_KEY` (create a key at https://api.thinkreasonlearn.com/console/keys). Models marked "On OpenRouter" below can also be called there under the same id. Full reference for every model (description, input and output fields, price, quality, limits, a curl example) in one file: https://api.thinkreasonlearn.com/llms-full.txt. Each model page also has a markdown version: add `.md` to its URL. ## Call a model - OpenAI-compatible: `POST /v1/chat/completions` with the model id as `model`. Put the input in the user message: plain text, or a JSON object of the model's input; images as `image_url` parts. The prediction comes back as JSON in `choices[0].message.content`. - Native: `POST /v1/predict` with `{"model": "", "input": {...}}`. The model's own fields come back in `output`. - Every prediction also carries `common`, the same for every model: `{level, level_index, levels, chance, chance_is, base_chance, outcome}`. `levels` run lowest first and `level_index` counts from 0 at the lowest. `chance` is the number to quote, next to `base_chance`. Over chat completions it is a `common` key in the reply JSON. - Catalog: `GET /v1/models` (public, no key). Each model has `input_schema` and `output_schema` (JSON Schema) and `display`: which output fields hold the level, the chance and the base rate. One model: `GET /v1/models/`. - OpenAPI 3.1: `GET /openapi.json`. ## Improve a text `POST /v1/improve` with `{"model": "", "input": {...}, "rounds": 2}` runs the loop for you: score the text, have a writer rewrite only what pulled the score down (keeping the facts and the voice), score the rewrite, and keep the best of up to `rounds` rounds (1 to 3, default 2). A rewrite that scores the same or lower is never returned as better: `improved` is false and `text` is your original. Returns `{text, improved, before, after, changes, rounds}`; `before` and `after` hold the score, the level and the model's full output with its reasons. Text models only: `improve_fields` in `GET /v1/models` names the input field it rewrites (pick another with `"field"`). Price: each score at the model's price, plus $0.01 to $0.05 for each rewrite. Two rounds on a $0.01 model cost about $0.05 and take 10 to 20 s. ## Build a decision from your data Train your own explainable decision model from labelled examples, then call it like a catalog model. Any key that can call models can build. 1. `POST /v1/decisions` with `{"task": "Will this cold email get a reply?", "outcomes": ["no reply", "replied"], "rows": [{"text": "...", "outcome": "replied"}, ...]}`. Optional: `name`, `case_noun` (what one row is, e.g. "email"), `max_usd` and `checks`: up to 20 yes/no questions of your own (each up to 300 characters, starting with a word like Does, Is or Has and ending with "?"), for example `["Does the email have a personalised subject line?"]`. They are asked next to the checks written for you and weighed like them. Rules: `task` up to 2,000 characters; exactly 2 different `outcomes`, the negative one first; 20 to 2,000 `rows`, each `text` up to 4,000 characters and each `outcome` one of the two, with at least 5 rows of each. Answers 202 with `{decision, job}`. 2. Follow the build with `GET /v1/jobs/?after=&wait=10`. It returns `{status, events, next, error?, cost_usd}`; `status` is queued, running, succeeded, failed or cancelled. Events are numbered (`seq`): pass the `next` you got as `after` and you never miss or repeat one. `wait` (0 to 20 s) holds the request until a new event arrives or the status changes. Event types include `profiled`, `check_written`, `answers`, `fitted` and, at the end, `done` (with the metrics) or `failed`. A build takes about a minute for small sets. `DELETE /v1/jobs/` cancels it. 3. `GET /v1/decisions/` shows the decision: `status` (building, ready or failed), `metrics` (`auc` and where it comes from, `auc_source`: cross-validated on small sets, held out from 100 rows up; `n_train`, `n_test`, `base_rate`, `level_rates`, `checks_written`, `checks_used`) `version` (the live one's number), and the `checks` it asks, `[{id, text, source}]` (`source` is `customer` for yours, `written` for the rest), plus `customer_checks`, `[{text, used, note?}]`: each of your checks and whether the decision uses it (`false` when it didn't help tell the outcomes apart, `null` until it is built). It also says how much feedback came in since the last build (`feedback_since_build`, `corrections_since_build`) and `retrain_suggested: true` from 10 corrections. `GET /v1/decisions` lists yours; `DELETE /v1/decisions/` deletes one with its rows and feedback. 4. `POST /v1/decisions//predict` with `{"input": {"text": "..."}}` answers like `POST /v1/predict` does for a catalog model: `output` with `level`, `probability`, `level_rate`, `base_rate`, `pulled_up`, `pulled_down`, `intercept`, `rest_effect` and `warnings`, plus `common`. Its `id` is the prediction id, and `call` is the outcome it calls: the positive one when `common.chance` is 0.5 or more. 5. `POST /v1/decisions//feedback` with `{"prediction_id": "...", "input": {"text": "..."}, "right": false}` records whether a call was right, and becomes a training row for the next retrain: "right" keeps the call, "wrong" flips it, and `"outcome"` (when you know what really happened) wins. Send the `input` you predicted on: predictions don't keep it, so feedback without it can't train. Without `prediction_id` it is matched to your latest prediction on the same text. The answer's `train_outcome` is what it trains as, or null. Free. 6. `POST /v1/decisions//retrain` (optional `max_usd`) trains a new version on your rows plus the feedback, priced like a build; follow its job like a build's. It is measured on the same held-out rows as the live version and goes live only if its AUC is not worse (within 0.01). Otherwise, and always for decisions built from fewer than 100 rows (no held-out rows to compare on), it is kept as a version that is not live, with the reason. `GET /v1/decisions//versions` lists every version (`number`, `live`, `metrics`, `not_promoted_reason`); `POST /v1/decisions//versions//promote` makes one live, an older one included (a rollback). Free. 7. To score a whole list at once, `POST /v1/decisions//batch` with `{"inputs": [{"text": "..."}, ...]}` (1 to 10,000 inputs, each up to 4,000 characters, 10,000,000 characters in all; optional `max_usd`). It answers 202 with a job: follow it with `GET /v1/jobs/` like a build (`progress` counts `scored`, `failed`, `skipped` and `pending` rows) and cancel it with `DELETE`. Download with `GET /v1/jobs//results` (JSON) or `?format=csv`: one row per input, in order, with `index`, `status` (scored, failed, skipped or pending), `probability`, `level`, `level_rate`, the top 3 `reasons_up` and `reasons_down`, or `error`. Each scored row costs $0.01, failed rows nothing. Every row (or `max_usd`) is held up front; rows past what `max_usd` covers are skipped. A cancelled job is charged for the rows it scored before the cancel. At most 2 run at once per organization; `GET /v1/decisions//batch` lists them. Price: a build is charged for what it uses, at least $0.01, when it finishes. `max_usd` (default 0.50, 0.05 to 5) is held while it runs and caps the price; a failed or cancelled build costs nothing. A retrain is priced the same way. At most 2 builds or retrains run at once per organization. Each prediction costs $0.01. ## Webhooks Get told when a build, retrain or bulk job ends instead of polling. `POST /v1/webhooks` with `{"url": "https://...", "events": ["job.succeeded", "job.failed", "job.cancelled", "decision.version_promoted"]}` (events optional: all by default) answers 201 with the endpoint and its signing `secret`, shown only this once. We POST JSON events `{id, object: "event", type, created, data}`; a job's `data` is `{job: {id, kind, status, decision_id, cost_usd}}`, never your rows. Verify each call: the `TRL-Signature` header is `t=,v1=`, where v1 is HMAC-SHA256 of `"."` with your secret; compare in constant time and refuse a t more than 5 minutes old. Answer 2xx within 10 s. Failures are retried for about 24 hours (8 attempts); an endpoint that fails all that time with no success is disabled (`POST /v1/webhooks//enable` turns it back on). Delivery is at least once: dedupe on the event `id`. Also `GET /v1/webhooks`, `DELETE /v1/webhooks/`, `POST /v1/webhooks//test` (sends a `webhook.test` event now) and `GET /v1/webhooks//deliveries`. URLs must be public https. ## Models - [LinkedIn Viral Post Predictor](https://api.thinkreasonlearn.com/models/think-reason-learn/linkedin-viral-post-predictor.md): `think-reason-learn/linkedin-viral-post-predictor`. Predicts whether a LinkedIn post will be a hit or go viral, and explains what pulled the score up or down. Returns level, hit and viral rate at that level vs base rate, what pulled the score up or down. $0.01 per call. On OpenRouter. Works with /v1/improve. - [LinkedIn Viral Post Predictor (with account)](https://api.thinkreasonlearn.com/models/think-reason-learn/linkedin-viral-post-predictor-with-account.md): `think-reason-learn/linkedin-viral-post-predictor-with-account`. Scores a LinkedIn post against the author's own account and audience, and shows what the account changes. Returns level, hit and viral rate at that level vs base rate, what pulled the score up or down. $0.01 per call. Works with /v1/improve. - [GitHub PR Merge Predictor](https://api.thinkreasonlearn.com/models/think-reason-learn/github-pr-merge-predictor.md): `think-reason-learn/github-pr-merge-predictor`. Predicts whether a pull request from an outside contributor will be merged, and explains what pulled the score up or down. Returns verdict, merge probability vs base rate, what pulled the score up or down. $0.01 per call. - [GitHub Contributor Rating](https://api.thinkreasonlearn.com/models/think-reason-learn/github-contributor-rating.md): `think-reason-learn/github-contributor-rating`. Rates how likely a GitHub user's pull requests to other people's repos are to be merged, from their public track record. Returns rating, merge probability vs base rate, reasons, the profile it read. $0.01 per call. - [Show HN Launch Predictor](https://api.thinkreasonlearn.com/models/think-reason-learn/show-hn-launch-predictor.md): `think-reason-learn/show-hn-launch-predictor`. Predicts whether a Show HN post will reach 100+ points on Hacker News, and explains what pulled the score up or down. Returns outlook, hit rate at that outlook vs base rate, what pulled the score up or down. $0.01 per call. On OpenRouter. Works with /v1/improve. ## Coming soon - `think-reason-learn/ai-slop-design-detector`: Scores a web page design for craft and tells you what makes it look AI-generated, with the fixes that matter most. - `think-reason-learn/x-quote-reply-predictor`: Predicts how much conversation a post on X will start: quotes, replies and reach. ## Posts - [Posts on thinkreasonlearn.com](https://thinkreasonlearn.com/research): what the models learn, how we test them, and what the data says. ## Console - [Sign up](https://api.thinkreasonlearn.com/sign-up): add credits and create an API key. - [Model catalog](https://api.thinkreasonlearn.com/models) ThinkReasonLearn is a decision harness for predictions by Vela Research and the University of Oxford: plain-language checks answered by a language model, combined by a trained, auditable scorer. https://thinkreasonlearn.com