Proofread

POST /v1/proofread — Analyze Tamil text for grammar, spelling, and style issues.

Overview

Property	Value
Auth	Bearer token (OIDC, any authenticated tenant user)
Idempotent	Yes (`Idempotency-Key` header)
Async	Auto if text > 1200 chars or `Prefer: respond-async` header

The proofread endpoint uses an expert Tamil linguist persona with knowledge of Tholkappiyam, Nannool, Sandhi/Punarchi rules, Mayangoli distinctions (ண/ன/ந, ல/ள/ழ, ர/ற), and Senthamizh vs Pechu Tamil.

Request


{
  "text": "தமிழ் உரை (1–10,000 chars)",
  "language": "ta"
}

Field	Type	Required	Constraints
`text`	string	Yes	1–10,000 characters
`language`	string	Yes	Must be `"ta"`

Sync Response (200)

Returned when text is under 1200 characters (and Prefer: respond-async is not set):


{
  "request_id": "string",
  "tenant_id": "string",
  "operation_id": "uuid",
  "status": "succeeded",
  "provider": "gemini",
  "model": "gemini-2.5-flash",
  "latency_ms": 1200,
  "result": {
    "original_text": "...",
    "corrected_text": "...",
    "issues": [
      {
        "type": "grammar | spelling | style | clarity",
        "severity": "low | medium | high",
        "message": "...",
        "start": 0,
        "end": 5,
        "suggestion": "..."
      }
    ]
  }
}

Issue Types

Type	Description
`grammar`	Grammatical errors (Sandhi, verb agreement, etc.)
`spelling`	Spelling mistakes and Mayangoli confusions
`style`	Stylistic improvements
`clarity`	Ambiguous or unclear phrasing

Issue Severity

Level	Meaning
`high`	Must fix — breaks correctness
`medium`	Should fix — improves quality
`low`	Optional — stylistic polish

Async Response (202)

Returned when text exceeds 1200 characters or Prefer: respond-async header is present:


{
  "request_id": "string",
  "tenant_id": "string",
  "operation_id": "uuid",
  "status": "queued",
  "poll_url": "/v1/operations/{operationId}"
}

Poll the poll_url until the operation reaches a terminal state (succeeded or failed).

Example


curl -X POST "https://api.gotamil.in/v1/proofread" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "text": "தமிழ் உரை சரிபார்ப்பு சோதனை.",
    "language": "ta"
  }'