Essay Critique

POST /v1/essay-critique — Provide comprehensive academic feedback on Tamil essays.

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

Request


{
  "essay": "தமிழ் கட்டுரை (1–20,000 chars)",
  "language": "ta"
}

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

Response — Result Structure


{
  "result": {
    "summary": "Overall assessment in Tamil",
    "topFixes": ["Fix 1 in Tamil", "Fix 2 in Tamil"],
    "sections": {
      "structure": { "title": "...", "summary": "...", "items": ["..."] },
      "clarity": { "..." },
      "facts": { "..." },
      "citations": { "..." }
    },
    "safetyFlags": [
      {
        "itemId": "str-001",
        "type": "meaning-change | unverified | conflicting",
        "message": "Warning in Tamil"
      }
    ]
  }
}

Analysis Dimensions

The essay critique evaluates four dimensions:

1. Structure & Flow

Introduction, body, and conclusion clarity. Paragraph ordering and transitions.

2. Clarity

Ambiguous sentences, reading level, overly complex constructions.

3. Fact Verification

Claims badged as verified, unverified, or conflicting.

4. Literary Citations

Thirukkural and Sangam literature verification. Attribution accuracy.

Feedback Items

Each item in a section follows this structure:


{
  "id": "str-001",
  "category": "structure",
  "severity": "high | medium | low",
  "title": "...",
  "description": "...",
  "location": { "from": 0, "to": 50, "excerpt": "..." },
  "suggestion": {
    "text": "...",
    "canAutoApply": false,
    "meaningMayChange": true
  },
  "badge": "verified | unverified | conflicting | null",
  "sourceUrl": null,
  "sourceTitle": null
}

All user-facing feedback is output in Tamil.

Example


curl -X POST "https://api.gotamil.in/v1/essay-critique" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "essay": "தமிழ் கல்வி மாணவர்களின் மொழித் திறனை மேம்படுத்துகிறது...",
    "language": "ta"
  }'