API Reference

Complete endpoint reference for GoTamil API v1.

Base URL


https://api.gotamil.in/v1

Endpoint Summary

Endpoint	Method	Auth	Async	Idempotent	Description
`/v1/health`	GET	None	No	No	Liveness check
`/v1/ready`	GET	None	No	No	Deep readiness check
`/v1/proofread`	POST	Tenant OIDC	Auto	Yes	Tamil proofreading
`/v1/essay-critique`	POST	Tenant OIDC	Auto	Yes	Tamil essay critique
`/v1/operations/:id`	GET	Tenant OIDC	No	No	Poll async operation
`/v1/admin/onboarding/status`	GET	Admin/Viewer	No	No	Onboarding progress
`/v1/admin/integrations/:integrationId/certifications`	POST	Admin	Always	Yes	Run integration certification
`/v1/admin/byok/.../credentials`	POST	Admin	No	Yes	Upload BYOK credential
`/v1/admin/byok/.../validate`	POST	Admin	No	Yes	Validate credential
`/v1/admin/dashboard/feed`	GET	Admin/Viewer	No	No	Operational metrics
`/v1/operator/invites`	GET/POST	Operator	No	No	Manage invites
`/v1/internal/tenants`	GET/POST	Operator	No	No	Manage tenants

Dashboard Feed Notes

Endpoint: /v1/admin/dashboard/feed
Optional query: window_minutes
Allowed values: 1, 10, 60, 360, 1440, 10080
Reliability payload includes token analytics in reliability.token_usage:
- summary totals for input/output/total/cached tokens
- bucketed token trend over the selected window

Common Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <oidc-jwt-token>`
`Content-Type`	Yes (POST)	`application/json`
`Idempotency-Key`	Recommended	UUID for safe retries (1-200 chars)
`Prefer`	Optional	`respond-async` to force async processing

Error Format

All errors follow RFC 7807 Problem Details:


{
  "type": "https://api.gotamil.in/problems/{error-code}",
  "title": "Human-readable title",
  "status": 400,
  "detail": "Detailed explanation",
  "request_id": "fastify-request-id"
}