Graine AI
API referenceTransliterate

Convert names into the script your agent speaks

Rewrites values into another script while preserving pronunciation ('Rishabh' → 'ऋषभ'), so a voice agent says a name correctly instead of mangling it.

Rewrites values into another script while preserving pronunciation ('Rishabh' → 'ऋषभ'), so a voice agent says a name correctly instead of mangling it.

This endpoint is fast and partial, by design. Cached values return instantly. Values needing the vendor are converted only as far as the shared per-account budget allows right now; the rest come back in pending, unchanged, and are converted in the background. Ask again and they will be there. Never block your dialling on this call — send the original value if a conversion has not arrived yet.

Every conversion is cached for 30 days across the whole platform, so a repeat list costs nothing.

Rate limit: 1000 requests per minute per organization (bucket default). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

POST
/v2/transliterate
/v2/transliterate

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.

In: header

Request Body

application/jsonRequired

values
Required
Values

The values to convert. Duplicates cost nothing — they are collapsed before any work is done.

target_language_code
Required
Target Language Code

The script to convert INTO. One of en-IN, hi-IN, bn-IN, gu-IN, kn-IN, ml-IN, mr-IN, od-IN, pa-IN, ta-IN, te-IN.

source_language_codeSource Language Code

The language the values are WRITTEN in. Names are two or three words — too little text for reliable auto-detection — so send the real code whenever you know it.

Default: "auto"

Response Body

200

Successful Response

converted
Required
Converted

Original value → converted value. Only values that actually changed appear here.

unchanged
Required
Unchanged

Values deliberately left alone: already in the target script, or carrying no letters to pronounce (a phone number, an order id). These are never sent to the vendor.

pending
Required
Pending

Values not converted THIS call because the shared vendor budget was spent. They are being converted in the background — ask again shortly and they will be in converted, served from cache. Send the original value in the meantime; never hold a call waiting for one.

target_language_code
Required
Target Language Code

The script the values were converted into.

cached
Required
Cached

How many values were answered from cache — these cost nothing and are the reason a repeat list is instant.

400

1000 — malformed or contradictory input. 1002 — a required parameter is missing.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

401

1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented instead of an API key.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

403

1102 — the key is valid but lacks the scope this endpoint requires, or names another organization. GET /v2/scopes reports what a key holds.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

422

1001 — the body or query failed validation; the message names the first offending field.

error
Required
integer

Stable integer code from the error table. Branch on this, not on the message.

message
Required
string

One human-readable sentence. Wording may change; the code will not.

429

1300 — the per-organization request rate or concurrent-call limit was reached. Carries Retry-After.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

503

1501 — a service this endpoint depends on is unreachable or returned a 5xx.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

curl -X POST "https://api.graine.ai/v2/transliterate" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "values": [
      "Sanjay Thakre",
      "Arti Gupta",
      "Gowtham"
    ],
    "target_language_code": "hi-IN",
    "source_language_code": "en-IN"
  }'

Successful Response

{
  "converted": {
    "Sanjay Thakre": "संजय ठाकरे",
    "Arti Gupta": "आरती गुप्ता"
  },
  "unchanged": [
    "+917061048672",
    "12345"
  ],
  "pending": [
    "Gowtham"
  ],
  "target_language_code": "hi-IN",
  "cached": 2
}

Previous

Delete a campaign DELETE

Next

Webhooks