Using the API

Voice parsing

Send audio and a schema; stream progress if you like.

POST /api/v1/voice/parse accepts multipart/form-data. Accepted audio: webm, ogg, opus, mp4 / m4a, aac, mp3, wav, flac, aiff. Browser MediaRecorder output (webm/opus in Chrome and Firefox, mp4/aac in Safari) works without conversion.

Field	Required	Description
`audio`	Yes	The recording.
`schema`	No	A name (latest), `name@version`, or an inline JSON definition. Default `delivery_order`.
`schemaVersion`	No	Pins a version when `schema` is a name.
`locale`, `dialect`	No	Optional overrides. Default auto: language and dialect are detected. See Languages & dialects.
`sessionId`	No	Adds the recording to a session.
`context`	No	JSON: `referenceTime`, vocabulary, phone region, currency, required fields.

curl -X POST https://api.example.com/api/v1/voice/parse \
  -H "Authorization: Bearer $API_KEY" \
  -F "audio=@voice.webm" \
  -F "schema=restaurant_order"

Context

referenceTime is the speaker's current date and time. Relative dates — «بكرا», «الأحد الجاي», tomorrow — are resolved from it, in code. Without it they come back invalid with what was heard, never guessed. Vocabulary helps with names the speech model would misspell; it never fills a field on its own.

context

{
  "referenceTime": "2026-09-24T14:30:00+03:00",
  "vocabulary": {
    "places": ["الجاردنز", "فرع الصويفية"],
    "businesses": ["مطعم حمادة"]
  },
  "phoneRegion": "JO",
  "currency": "JOD",
  "requiredFields": ["items", "address"]
}

Streaming progress

Add ?stream=true to receive one JSON event per line as each stage completes. Once streaming starts the HTTP status is 200; check the last event for result or error.

NDJSON

curl -N -X POST "https://api.example.com/api/v1/voice/parse?stream=true" \
  -H "Authorization: Bearer $API_KEY" -F "audio=@voice.webm" -F "schema=restaurant_order"

{"event": "received", "audioSeconds": 6.2}
{"event": "transcribing"}
{"event": "transcribed", "transcription": {"text": "…", "language": "ar", "confidence": 0.9}}
{"event": "extracting"}
{"event": "result", "result": { … }}