Skip to content

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.

View as MarkdownUpdated 2026-11-16

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)"

Request body

FieldTypeRequiredDescription
textstringYesPlain text of at least 20 words and at most 30,000 characters.
modelstringNoDefault grammar-1. Accepts the model ID or its snapshot ID grammar-1-2026-11-16.
languagestring or nullNoISO 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  }}
FieldTypeDescription
idstringCheck ID, prefixed tgr_.
objectstringAlways text.grammar.
createdintegerUnix timestamp.
modelstringSnapshot that produced the result.
livemodebooleanfalse for test keys.
languagestringThe language used: the one you sent, or the detected one.
wordsintegerWords in the text.
editsarraySuggested corrections in text order. Each has start, end (exclusive), original, replacement, category and message. Edits never overlap.
countsobjectNumber of edits per category: spelling, grammar, punctuation, word, style.
versionstringVersion of the proofreading method. Compare results only within one version.
usageobjectcharacters 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
spellingA misspelled word.
grammarAgreement, tense, articles, prepositions, word order and similar.
punctuationPunctuation and capitalization.
wordA wrong or confused word.
styleA 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("");

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_units is the number of units charged and usage.credits the 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

CodeStatusCause
text_too_short400Fewer than 20 words.
text_too_long413More than 30,000 characters. Split the text into several requests.
unsupported_language400The text is not in English, Spanish, French or Arabic, or its language could not be recognized. Send language to choose one.
unsupported_media_type415The body is not sent as application/json.
invalid_json, missing_parameter, invalid_parameter400The body is not a JSON object, text is missing, a field has the wrong type or an unknown field was sent.
model_not_found404The model is unknown.
plan_required403The workspace has not purchased credits yet. Buy a credit pack in the Console.
insufficient_balance402The balance cannot cover the request.
spend_limit_reached402The key reached its monthly spend limit.
idempotency_mismatch, idempotency_in_progress409The Idempotency-Key was used with a different body, or its first request is still running.
service_unavailable, analysis_failed503, 502The 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.