# 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.

Source: https://fileverity.com/en/docs/grammar

`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.

**Request: cURL**

```bash
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: JavaScript**

```javascript
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();
```

**Request: Python**

```python
import os
import uuid
import 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

**200 OK**

```json
{
  "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. |

> **Note.** 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:

**Build the corrected text: JavaScript**

```javascript
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("");
```

**Build the corrected text: Python**

```python
corrected = text
for 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_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](https://fileverity.com/en/docs/security.md#retention). 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](https://fileverity.com/en/docs/security.md).

## 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. |

> **Note.** Send an `Idempotency-Key` so that retrying after a timeout does not bill twice. See [Idempotency](https://fileverity.com/en/docs/idempotency.md).

