Grammar Checker API | Proofademic Documentation

Correct grammar, spelling, and punctuation and receive the corrected text plus a complete word-level diff.

POST /api/grammar/correct/

Correct grammar, spelling, and punctuation. The correction is minimal-change: voice, meaning, language, and paragraph structure are preserved, and text that is already clean comes back unchanged. Returns the corrected text plus a complete word-level diff.

Authentication: X-API-Key header with grammar_checker scope

Request Parameters

Parameter	Type	Required	Description
`content`	string	Yes	Text to correct. Sent exactly as submitted — diff offsets in the response refer to this text
`target_variant`	string	No	English variant for corrections: `auto` (default, preserves the input's variant), `en-US`, `en-GB`, `en-CA`, `en-AU`, `en-IN`. Only applies to English text

Limits

Limit	Value
Minimum length	5 words
Maximum length	10,000 words
Maximum characters	75,000

Words are counted script-aware: whitespace-separated words for most languages, one word per character for CJK scripts.

Pricing

1 credit per word. The charge uses the API's own script-aware word count, returned as input_words in the response. If the correction fails, the credits are refunded automatically.

Idempotency

Corrections are billed per word, so retrying a request that already succeeded would charge again. To make retries safe, send an Idempotency-Key header (any string up to 255 characters, e.g. a UUID):

Repeating the same key with the same text within 5 minutes returns the original response — nothing is re-processed and nothing is charged.
Repeating the same key with different text is rejected with 409 idempotency_key_reuse.

curl -X POST https://developer-portal.proofademic.ai/api/grammar/correct/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: 9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d" \
  -d '{ "content": "..." }'

Example

Request

curl -X POST https://developer-portal.proofademic.ai/api/grammar/correct/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": "This are a sample sentence with some grammar mistake inside of it."
  }'

Response (200 OK)

{
  "status": "success",
  "corrected_text": "This is a sample sentence with some grammar mistakes inside of it.",
  "diff": [
    { "type": "replace", "original": "are", "corrected": "is", "start": 5, "end": 8 },
    { "type": "replace", "original": "mistake", "corrected": "mistakes", "start": 45, "end": 52 }
  ],
  "issues": [
    { "category": "grammar", "severity": "suggestion", "message": "Grammar corrections applied." }
  ],
  "edits_count": 2,
  "changed": true,
  "input_words": 12,
  "input_chars": 66,
  "word_count": 12,
  "execution_time": 1.8,
  "credits_remaining": 1988,
  "user": {
    "id": 12345
  }
}

Response Fields

Field	Type	Description
`status`	string	Always `"success"` for a completed correction
`corrected_text`	string	The corrected text
`diff[]`	array	Complete word-level diff — one operation per change, never truncated
`issues[]`	array	High-level issue notes (`category`, `severity`, `message`)
`edits_count`	integer	Number of corrections applied — always equals the diff length
`changed`	boolean	`false` means the text was already clean (`diff` is empty and `corrected_text` equals the input)
`input_words`	integer	The API's script-aware word count — the amount charged
`input_chars`	integer	Character count of the submitted text
`word_count`	integer	Credits charged for this request
`execution_time`	float	Processing time in seconds
`credits_remaining`	integer	Credit balance after this request
`user.id`	integer	Your user ID

Diff Operations

Each entry in diff[] describes one change:

Field	Type	Description
`type`	string	`replace`, `insert`, or `delete`
`original`	string	The text being replaced or deleted (empty for insertions)
`corrected`	string	The replacement text (empty for deletions)
`start` / `end`	integer	Character offsets into your text exactly as you submitted it

Because the diff is complete and the offsets refer to your original text, you can render a track-changes view directly: walk the original text, strike through each original, and insert each corrected in its place.

Errors

Status	Code	Meaning
`400`	`min_words_not_met`	Under the 5-word minimum — `details` carries `limit` and `actual`
`400`	`max_words_exceeded`	Over the 10,000-word limit — `details` carries `limit` and `actual`
`400`	`invalid_payload`	Missing or malformed `content`, or over 75,000 characters
`400`	`invalid_idempotency_key`	`Idempotency-Key` header longer than 255 characters
`403`	`insufficient_credits`	Not enough credits — `details` carries `credits` and `required`
`409`	`idempotency_key_reuse`	The `Idempotency-Key` was already used with different text
`503`	`service_unavailable`	Correction temporarily unavailable — retry after the `Retry-After` header when present
`503`	`service_error`	Correction failed — credits were refunded

See Error Handling for the general error format.

Grammar Checker

On this page