Add Persian vowel marks

Request

Send text containing at least one Persian-script letter. include_ezafe defaults to true. Set it to false when your interface should omit marks introduced specifically for Ezafe while retaining other reading marks.

curl https://api.vowelmarks.com/v1/diacritize \
  -H "Authorization: Bearer $VOWELMARKS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lesson-42-diacritize" \
  --data '{"text":"کتاب جدید","include_ezafe":true}'

Response

original is the exact parsed JSON string you submitted. marked is produced by adding Arabic-script combining marks to that source. operations lets a renderer apply the same marks without trusting rewritten text.

{
  "request_id": "95b…",
  "engine_version": "vowelmarks-api-v1.2026-08-10",
  "original": "کتاب جدید",
  "marked": "کِتابِ جَدید",
  "operations": [
    { "source_index": 0, "mark": "ِ", "type": "reading" },
    { "source_index": 3, "mark": "ِ", "type": "ezafe" },
    { "source_index": 5, "mark": "َ", "type": "reading" }
  ],
  "usage": {
    "meter": "text", "input_code_points": 9,
    "multiplier": 1, "units": 9,
    "additional_units": 0, "cache_hit": false
  }
}

Index operations correctly

source_index is a Unicode code-point index, not a JavaScript UTF-16 code-unit offset and not a UTF-8 byte offset. Convert with Array.from(text) in JavaScript. ZWNJ, spaces, punctuation, and existing combining marks each retain their own source positions and count toward usage.

const characters = Array.from(result.original);
for (const operation of result.operations) {
  const sourceCharacter = characters[operation.source_index];
  // Attach operation.mark after sourceCharacter.
}

Source-preservation guarantee

A valid operation can add only documented Arabic-script combining marks to an Arabic-script source letter. If engine output changes source letters, punctuation, spacing, ZWNJ, numbers, or embedded English, VowelMarks rejects the generation and charges no usage.

• Do not normalize original before applying operations.
• Do not calculate indexes with JavaScript string.length.
• Treat type as a stable public category, currently reading or ezafe.
• Do not infer confidence from operation presence; v1 does not publish calibrated confidence scores.