API Reference

Voice & Speech-to-Text

Turn spoken audio into text (English + Arabic) and call Navvo's direct AI helpers for query understanding and route labels.

Voice & Speech-to-Text

Navvo hosts its own speech-to-text engine — upload a short audio clip and get the transcript back, in English or Arabic. This is the same endpoint behind the Navvo map's voice search and hands-free Atlas conversations; pair it with POST /ai/atlas to build a full voice assistant.

All AI responses are model-neutral: the model field always reads "navvo-ai". The underlying engines are Navvo implementation details and may change without notice.

POST /ai/transcribe

Speech-to-text over a multipart audio upload. Send the clip as the multipart file part; webm, ogg, and mp4/m4a audio are accepted (a browser MediaRecorder blob works as-is).

Query parameters

language

string

Transcription language: a 2-letter code (en, ar, … — case-insensitive, forwarded lowercased) or auto (default). Anything else — including auto, empty, or garbage — is clamped to auto-detect; an invalid language never returns a 400 (non-breaking clamp).

The body must be multipart/form-data with the audio as the file part. A non-multipart body (e.g. application/json) now returns a clean 400 { "message": "Expected multipart/form-data", "error": "Bad Request", "statusCode": 400 }.

curl -s -X POST "https://navvo.io/api/v1/ai/transcribe?language=auto" \
  -H "x-api-key: $NAVVO_API_KEY" \
  -F "[email protected];type=audio/webm"

Response

{ "text": "أقرب صيدلية مفتوحة الآن", "language": "ar", "unavailable": false }

Field	Type	Notes
`text`	string	the transcript (empty string when nothing was recognized)
`language`	string \| null	the detected/used language, when reported
`unavailable`	boolean	`true` when the speech engine is unreachable or the clip is empty — always check it before using `text`

Keep clips short (a spoken search phrase, a command); requests time out after ~20 s of processing. An upload with no file part returns 400.

Voice search in three steps: record with MediaRecorder (audio/webm), POST /ai/transcribe, then feed text into GET /search or POST /ai/atlas for a structured map action.

Direct AI helpers

Two small, deterministic-contract helpers used by the Navvo map itself. Both return the standard brand-neutral AI envelope — { model: "navvo-ai", unavailable, purpose, content } — where content is the model's reply text.

These are LLM-backed helpers, not bulk endpoints — POST /ai/search-understanding, POST /ai/route-labels, and POST /ai/constraints are each throttled to 30 requests/min per client IP (over the global limit). Exceeding it returns 429 ThrottlerException. Cache and debounce results.

POST /ai/search-understanding

Turns a free-text place query into a structured query plan (filters, category hints, locale, urgency) for smarter search UX.

curl -s -X POST "https://navvo.io/api/v1/ai/search-understanding" \
  -H "x-api-key: $NAVVO_API_KEY" -H "content-type: application/json" \
  -d '{ "query": "quiet cafe with wifi near Abdoun open now" }'

→ { "model": "navvo-ai", "unavailable": false, "purpose": "search_understanding", "content": "{ \"filters\": [\"wifi\"], \"categoryHints\": [\"cafe\"], \"locale\": \"en\", \"urgency\": \"now\" }" }

content is a strict-JSON string — parse it client-side, and fall back to a plain search when unavailable is true.

POST /ai/route-labels

Summarizes a raw routing response into a short human label + tip — the same block POST /routing/route attaches automatically.

Field	Type	Notes
`payload`	object	required — the raw routing response envelope you got from `/routing/route` or `/routing/plan`

→ { "model": "navvo-ai", "unavailable": false, "purpose": "route_labels", "content": "…", "parsed": { "label": "Fast city route", "tip": "Light traffic, mostly highways" } }

parsed is the best-effort structured extraction — it is null when the model's reply couldn't be parsed. Prefer parsed and treat content as the raw fallback. The envelope always carries unavailable — including the degenerate "no usable trip in the payload" case, which now returns { "model": "navvo-ai", "unavailable": false, "purpose": "route_labels", "content": "", "parsed": null }.

Spoken guidance (navigation)

For turn-by-turn voice, the POST /navigation/speak endpoint turns a maneuver instruction into speech-ready output — a normalized string plus ready-to-use SSML with the correct language and a calm speaking rate (and an audioUrl when a server-side TTS provider is configured; otherwise clients synthesize on-device for zero-latency, consistent Arabic/English pronunciation). The verbal instruction text itself comes from each maneuver's verbalAlert / verbalPre / verbalPost fields in a routing or navigation session response.

Users & Sync

Accounts, profiles, saved places, history, and live location sharing — the personal-data API for building a signed-in consumer app on Navvo.

Navigation

The real-time turn-by-turn navigation control plane — managed sessions, server-computed progress and off-route, live ETA, arrival detection, an event log, and spoken-guidance text.