HTTP API

incdai Public and authorized incdai Nodes share the same API, so applications can choose an operator without receiving access to private engine logic.

Base URL: https://api.incdai.incpritech.com for incdai Public, or the HTTPS origin declared by an authorized node.

Public endpoints

Called by the widget. If your profile sets allowed_origins, only those websites can use them.

GET /v1/sites/{site}/config

The assistant's public settings: name, business, greeting, colour, position, suggestions, WhatsApp link, and voice (whether the microphone is available).

POST /v1/sites/{site}/ask

{ "question": "Do you offer school transport?", "history": [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}] }

Responds with a stream of server-sent events. Text arrives as token events, then one done event:

data: {"type": "token", "text": "Yes, school buses cover "}
data: {"type": "token", "text": "routes within Arusha city."}
data: {"type": "done", "answered": true, "language": "en", "sources": [], "handoff": "https://wa.me/255700000000?text=..."}

For voice conversations, add "mode": "voice" for short answers that sound natural read aloud, and "language": "sw" or "en" from the transcription.

answered: false means incdai could not answer from the approved business information; the widget can then offer contact options. Usage limits depend on the selected service and return status 429 when reached.

POST /v1/sites/{site}/transcribe

Speech to text for one spoken question. Send the recording as the request body, with its type as Content-Type (audio/webm, audio/mp4, audio/ogg, audio/wav or audio/mpeg), up to about a minute.

curl https://api.incdai.incpritech.com/v1/sites/your-site/transcribe \
  -H "Content-Type: audio/webm" --data-binary @question.webm

{"text": "Mnafungua saa ngapi Jumapili?", "language": "sw"}

An empty text means no speech was recognized. The endpoint returns 403 when voice is unavailable for the assistant.

POST /v1/sites/{site}/speak

{ "text": "Karibu! We are open until 9 pm.", "voice": "luna" }

Text to speech in a natural voice. Audio format and available voices are node capabilities. On incdai Public each call counts toward the plan's monthly natural-voice allowance; when none are left it returns 402 with code: "plan".

GET /v1/sites/{site}/live

A WebSocket for real-time voice conversations: microphone audio in, answers and speech out. See Live voice for the protocol.

POST /v1/sites/{site}/leads

{ "name": "Asha", "contact": "+255 711 111 111", "message": "A Form One place for my daughter next year" }

Owner endpoints

Owner endpoints require a bearer credential issued by incdai Public or the selected node operator. Never place that credential in browser or mobile application code.

Example: ask from your own code

curl -N https://api.incdai.incpritech.com/v1/sites/your-site/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "Mnafungua saa ngapi?"}'