Fileverity API docs
Grammar checks
Check plain text for spelling, grammar, punctuation and word-choice errors with POST /text/grammar. Request and response fields, categories, offsets, limits and billing.
POST /text/grammar checks one text with grammar-1. It returns every suggested correction with its position in the text, a category and a short explanation. It is synchronous: the result is in the response.
It works for English, Spanish, French and Arabic. Save a text of 20 words or more as essay.txt to run the examples.
curl https://api.fileverity.com/v1/text/grammar \ -H "Authorization: Bearer $FILEVERITY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 2c7d1c1e-3b0f-4c0a-9a53-2d1c9d6b7e21" \ -d "$(jq -Rs '{text: ., language: "en"}' essay.txt)"import { readFile } from "node:fs/promises";import { randomUUID } from "node:crypto"; const response = await fetch("https://api.fileverity.com/v1/text/grammar", { method: "POST", headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Content-Type": "application/json", "Idempotency-Key": randomUUID(), }, body: JSON.stringify({ text: await readFile("essay.txt", "utf8"), language: "en" }),});const check = await response.json();import osimport uuidimport requests response = requests.post( "https://api.fileverity.com/v1/text/grammar", headers={ "Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"], "Idempotency-Key": str(uuid.uuid4()), }, json={"text": open("essay.txt", encoding="utf-8").read(), "language": "en"},)check = response.json()Request body
| Field | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Plain text of at least 20 words and at most 30,000 characters. |
model | string | No | Default grammar-1. Accepts the model ID or its snapshot ID grammar-1-2026-11-16. |
language | string or null | No | ISO 639-1 code: en, es, fr, ar. Detected automatically when omitted; send it when the text mixes languages. |
Unknown fields are rejected with invalid_parameter. A text in another language, or whose language cannot be recognized, returns unsupported_language.
Response
{ "id": "tgr_8Hk2pQ4vN9sL1xR7cW3mY6zB", "object": "text.grammar", "created": 1794787200, "model": "grammar-1-2026-11-16", "livemode": true, "language": "en", "words": 412, "edits": [ { "start": 118, "end": 125, "original": "recieve", "replacement": "receive", "category": "spelling", "message": "The word is spelled receive." }, { "start": 402, "end": 414, "original": "has went", "replacement": "has gone", "category": "grammar", "message": "The past participle of go is gone." }, { "start": 1170, "end": 1175, "original": "Their", "replacement": "They're", "category": "word", "message": "They're is the contraction of they are." }, { "start": 1788, "end": 1789, "original": ",", "replacement": ";", "category": "punctuation", "message": "Two complete sentences are joined with a comma." } ], "counts": { "spelling": 1, "grammar": 1, "punctuation": 1, "word": 1, "style": 0 }, "version": "2026.11-g1", "usage": { "characters": 2412, "billed_units": 1, "credits": 1 }}| Field | Type | Description |
|---|---|---|
id | string | Check ID, prefixed tgr_. |
object | string | Always text.grammar. |
created | integer | Unix timestamp. |
model | string | Snapshot that produced the result. |
livemode | boolean | false for test keys. |
language | string | The language used: the one you sent, or the detected one. |
words | integer | Words in the text. |
edits | array | Suggested corrections in text order. Each has start, end (exclusive), original, replacement, category and message. Edits never overlap. |
counts | object | Number of edits per category: spelling, grammar, punctuation, word, style. |
version | string | Version of the proofreading method. Compare results only within one version. |
usage | object | characters evaluated, billed_units charged and credits charged. |
Suggestions come from a language model. They can be wrong or unnecessary, especially for names, technical terms and deliberate style, so show them to a person as suggestions rather than applying them silently. Arabic checking is new and still being evaluated.
Categories
| `category` | Meaning |
|---|---|
spelling | A misspelled word. |
grammar | Agreement, tense, articles, prepositions, word order and similar. |
punctuation | Punctuation and capitalization. |
word | A wrong or confused word. |
style | A readability suggestion rather than an error. Only a few are returned, and only where a sentence is clearly hard to read. |
Applying the edits
start and end are offsets into the text you submitted, counted in Unicode code points, not bytes and not UTF-16 units. original is the text between them. To build the corrected text, replace each range with replacement, working from the last edit to the first so earlier offsets stay valid, or split the text into code points first:
const points = Array.from(text);const out = [];let at = 0;for (const edit of check.edits) { out.push(points.slice(at, edit.start).join(""), edit.replacement); at = edit.end;}out.push(points.slice(at).join(""));const corrected = out.join("");corrected = textfor edit in reversed(check["edits"]): corrected = corrected[: edit["start"]] + edit["replacement"] + corrected[edit["end"] :]Python strings already index by code point.
Billing
- A grammar check costs 1 credit per 5,000 characters, counted in Unicode code points. Each request is rounded up to whole units, with a minimum of one unit.
usage.billed_unitsis the number of units charged andusage.creditsthe credits charged. Example: 2,412 characters bill 1 units, 1 credits.- Requests rejected before evaluation are not charged: invalid parameters, text that is too short or too long, unsupported languages and similar. A check that fails inside the service (
service_unavailable) is released and not charged. - Not enough credits return
insufficient_balance(402). Through the API, grammar checks are open to workspaces that have purchased credits and always use credits; on the website and in the Console they are part of the Pro plan.
What is stored
The text is sent to a language model through Vercel AI Gateway for the duration of the check. A copy of the text is kept encrypted for up to 3 years to train and evaluate Fileverity's detection models; see Data retention and security. Fileverity keeps the result (the edits with their short original and replacement fragments, counts and usage) for 7 days, so the Console can show it and usage can be billed and audited. A retried request with the same Idempotency-Key gets the saved result for 24 hours. Grammar checks are synchronous: they do not appear in GET /analyses and do not send webhook events. Test keys record nothing. See Data retention and security.
Errors
| Code | Status | Cause |
|---|---|---|
text_too_short | 400 | Fewer than 20 words. |
text_too_long | 413 | More than 30,000 characters. Split the text into several requests. |
unsupported_language | 400 | The text is not in English, Spanish, French or Arabic, or its language could not be recognized. Send language to choose one. |
unsupported_media_type | 415 | The body is not sent as application/json. |
invalid_json, missing_parameter, invalid_parameter | 400 | The body is not a JSON object, text is missing, a field has the wrong type or an unknown field was sent. |
model_not_found | 404 | The model is unknown. |
plan_required | 403 | The workspace has not purchased credits yet. Buy a credit pack in the Console. |
insufficient_balance | 402 | The balance cannot cover the request. |
spend_limit_reached | 402 | The key reached its monthly spend limit. |
idempotency_mismatch, idempotency_in_progress | 409 | The Idempotency-Key was used with a different body, or its first request is still running. |
service_unavailable, analysis_failed | 503, 502 | The grammar service is temporarily unavailable. Not charged; retry. service_unavailable carries a retry-after header. |
Send an Idempotency-Key so that retrying after a timeout does not bill twice. See Idempotency.