Endpoint reference
All endpoints are POST with a JSON body, except where the method column says
GET. Paths are shown relative to the API host.
Authentication legend
| Badge | Meaning |
|---|---|
| Public | No credential required. Rate limited per IP. |
| Key protected | Send X-Kaonic-Key or Authorization: Bearer. |
Adaptive intelligence
Question answering, voice planning and document generation.
POST
/api/ask
Adaptive question answering with conversation history. Public
| Request | { "question": "How do I register a business in Uganda?", "language": "en", "languageName": "English", "history": [] } |
|---|---|
| Response | { "answer": "...", "engine": "kaonic-openai", "intent": "openai_response", "language": "en" } |
| Notes | Question 2–1,000 characters. History accepts the last 6 turns. Rate limited to 30 requests per 10 minutes per IP. |
POST
/api/tts
Voice plan for African languages — synthesised on the client device. Public
| Request | { "text": "Welcome to Kaonic Ai Beta", "language": "lg" } |
|---|---|
| Response | { "engine": "kaonic-engine", "voice": "...", "language": "lg", "rate": 0.94, "pitch": 0.86, "segments": [], "estimated_seconds": 3.4 } |
| Notes | Text 1–5,000 characters. No external AI provider is contacted — the plan is rendered locally. |
POST
/api/generate-document
Generate structured business documents (proposals, invoices, briefs). Key protected
| Request | { "type": "proposal", "business": "Acme Ltd", "brief": "..." } |
|---|---|
| Response | { "document": { "title": "...", "sections": [] } } |
Content generators
Images, music, speech, podcasts, video prompts and transcription.
POST
/api/generate/image
Marketing visuals, posters and product imagery. Key protected
| Request | { "prompt": "School poster in Kampala", "size": "landscape_4_3" } |
|---|---|
| Response | { "image_url": "...", "prompt": "..." } |
POST
/api/generate/music
Original music beds and jingles for campaigns. Key protected
| Request | { "prompt": "Afrobeat jingle for a restaurant", "seconds": 30 } |
|---|---|
| Response | { "audio_url": "...", "duration": 30 } |
POST
/api/generate/speech
Voice-over generation for ads, IVR and announcements. Key protected
| Request | { "text": "...", "voice": "female-ug", "language": "en" } |
|---|---|
| Response | { "audio_url": "...", "voice": "female-ug" } |
POST
/api/generate/podcast
Multi-speaker podcast scripts and audio. Key protected
| Request | { "topic": "Growing a school in Uganda", "minutes": 8 } |
|---|---|
| Response | { "script": "...", "audio_url": "..." } |
POST
/api/generate/cinematic
Cinematic video prompt packs and storyboards. Key protected
| Request | { "hero": "founder", "scene": "Kampala skyline", "style": "afrofuturist" } |
|---|---|
| Response | { "prompt_pack": "...", "storyboard": [] } |
POST
/api/generate/text-audio
Long-form text turned into narration audio. Key protected
| Request | { "text": "...", "language": "sw" } |
|---|---|
| Response | { "audio_url": "..." } |
POST
/api/generate/audio-text
Speech-to-text transcription for meetings and interviews. Key protected
| Request | { "audio_url": "https://.../clip.mp3", "language": "en" } |
|---|---|
| Response | { "transcript": "...", "language": "en" } |
Voice, devices and verticals
Versioned endpoints for apps, hardware and SEO auditing.
POST
/api/v1/chat
Versioned conversational endpoint for apps and devices. Key protected
| Request | { "message": "Hello Kaonic", "conversation_id": null } |
|---|---|
| Response | { "reply": "...", "conversation_id": "..." } |
POST
/api/v1/voice
Voice-profile aware synthesis for phones, drones and kiosks. Key protected
| Request | { "text": "...", "profile_id": null, "language": "en" } |
|---|---|
| Response | { "audio_url": "...", "profile_id": null } |
POST
/api/v1/command
Natural-language command routing for robots, vehicles and machines. Key protected
| Request | { "command": "return to base", "device_id": "..." } |
|---|---|
| Response | { "intent": "return_to_base", "actions": [] } |
POST
/api/v1/telemetry
Device telemetry ingest with optional HMAC signing. Key protected
| Request | { "device_id": "...", "metrics": { "battery": 82 } } |
|---|---|
| Response | { "ok": true, "received_at": "..." } |
| Notes | Device keys sign requests with X-Kaonic-Device-Key, X-Kaonic-Device-Timestamp and X-Kaonic-Device-Signature. |
POST
/api/v1/devices/register
Register a device and receive its device key pair. Key protected
| Request | { "name": "Field tablet 01", "meta": {} } |
|---|---|
| Response | { "device_id": 1, "device_key": "kai_dev_...", "device_secret": "..." } |
POST
/api/v1/seo/audit
SEO audit for a connected website — issues, opportunities and fixes. Key protected
| Request | { "site_id": 1, "refresh": true } |
|---|---|
| Response | { "score": 74, "issues": [], "opportunities": [], "fixes": [] } |
Accounts and API keys
Registration, tokens, key lifecycle and usage reporting.
POST
/api/auth/register
Create a Kaonic account. Returns a bearer token. Public
| Request | { "name": "...", "email": "...", "password": "..." } |
|---|---|
| Response | { "token": "...", "user": { "id": "...", "email": "..." } } |
POST
/api/auth/login
Exchange credentials for a bearer token. Public
| Request | { "email": "...", "password": "..." } |
|---|---|
| Response | { "token": "...", "user": { "id": "...", "email": "..." } } |
POST
/api/keys/generate
Create an API key pair. The private key is returned once only. Key protected
| Request | { "project": "My App", "permissions": ["read", "write"] } |
|---|---|
| Response | { "key_id": "kk_...", "public_key": "KG_...", "private_key": "GK_...", "permissions": ["read", "write"], "warning": "Store the private_key now — it will never be shown again." } |
| Notes | Rate limited to 20 key creations per hour per IP. |
POST
/api/keys/list
List your API keys. Private keys are always masked. Key protected
| Request | {} |
|---|---|
| Response | { "keys": [ { "id": "kk_...", "project": "My App", "permissions": ["read"], "public_key": "KG_...", "private_mask": "GK_...a1b2c3", "revoked": false, "last_used_at": null, "created_at": "..." } ] } |
POST
/api/keys/revoke
Revoke an API key immediately. Key protected
| Request | { "key_id": "kk_..." } |
|---|---|
| Response | { "ok": true, "revoked": true, "key_id": "kk_..." } |
| Notes | Revocation is permanent. Create a new key to restore access. |
POST
/api/dashboard/summary
Usage, credits and request counts for the signed-in developer. Key protected
| Request | {} |
|---|---|
| Response | { "credits": 5000, "calls_today": 12, "by_endpoint": [] } |
Business and engagement
Contact, careers, integrations and support data.
POST
/api/contact
Contact form delivery for sales and support enquiries. Public
| Request | { "name": "...", "email": "...", "message": "..." } |
|---|---|
| Response | { "ok": true } |
POST
/api/careers
Job application submission. Public
| Request | { "role": "...", "name": "...", "email": "..." } |
|---|---|
| Response | { "ok": true } |
GET
/api/integrations/list
Installed integrations for the account. Key protected
| Request | — |
|---|---|
| Response | { "integrations": [] } |
POST
/api/integrations/install
Install a platform integration (WordPress, WhatsApp, CRM). Key protected
| Request | { "provider": "wordpress", "config": {} } |
|---|---|
| Response | { "ok": true, "integration": {} } |
Quick reference
| Method | Path | Auth |
|---|---|---|
| POST | /api/ask |
Public |
| POST | /api/tts |
Public |
| POST | /api/generate-document |
Key |
| POST | /api/generate/image |
Key |
| POST | /api/generate/music |
Key |
| POST | /api/generate/speech |
Key |
| POST | /api/generate/podcast |
Key |
| POST | /api/generate/cinematic |
Key |
| POST | /api/generate/text-audio |
Key |
| POST | /api/generate/audio-text |
Key |
| POST | /api/v1/chat |
Key |
| POST | /api/v1/voice |
Key |
| POST | /api/v1/command |
Key |
| POST | /api/v1/telemetry |
Key |
| POST | /api/v1/devices/register |
Key |
| POST | /api/v1/seo/audit |
Key |
| POST | /api/auth/register |
Public |
| POST | /api/auth/login |
Public |
| POST | /api/keys/generate |
Key |
| POST | /api/keys/list |
Key |
| POST | /api/keys/revoke |
Key |
| POST | /api/dashboard/summary |
Key |
| POST | /api/contact |
Public |
| POST | /api/careers |
Public |
| GET | /api/integrations/list |
Key |
| POST | /api/integrations/install |
Key |