Use this page as the public endpoint map. Each group links to a focused guide with request fields, response examples, and integration notes. Privileged administration, upstream credentials, private infrastructure, and internal database operations are intentionally not documented here.
Most endpoints return {status, code, data, error_code, message, request_id}. Gateway routes use OpenAI-compatible response shapes where documented. The speech endpoint returns raw audio on success; all failed requests return JSON errors. See Errors and response format.
Recommended integration path
| Step | Endpoint | Credential | Use |
|---|---|---|---|
| 1 | GET /v1/models | API key | Discover enabled paid models, modalities, parameters, and prices. |
| 2 | GET /v1/billing/balance | API key or JWT | Confirm the current credit balance. |
| 3 | POST /v1/chat/completions | API key or JWT | Send an OpenAI-compatible text or multimodal request. |
| 4 | POST /v1/embeddings | API key or JWT | Create vectors for search and retrieval workflows. |
| 5 | POST /v1/voice/responses | API key or JWT | Run the combined Ongea na Ngamia Kiswahili voice flow. |
| 6 | POST /v1/payments/topup | JWT | Start a TZS mobile-money top-up when credits are low. |
Authentication
See Register, login & sessions and Authentication.
| Method and path | Credential | Purpose |
|---|---|---|
POST /v1/auth/register | None | Create an account pending verification. |
POST /v1/auth/otp/verify | None | Verify an email or phone code and receive tokens. |
POST /v1/auth/otp/resend | None | Resend a verification or reset code. |
POST /v1/auth/login | None | Start a session or MFA challenge. |
POST /v1/auth/refresh | Refresh token | Rotate the access and refresh token pair. |
POST /v1/auth/logout | JWT | Invalidate a refresh token. |
POST /v1/auth/password/forgot | None | Request a password-reset code. |
POST /v1/auth/password/reset | None | Set a new password with a reset code. |
GET /v1/auth/google/start | None | Start Google login in a browser. |
GET /v1/auth/google/callback | None | Google OAuth browser callback. |
POST /v1/auth/google/mobile | None | Native Android: trade a Google ID token for a session. |
GET /v1/auth/github/start | None | Start GitHub login in a browser. |
GET /v1/auth/github/callback | None | GitHub OAuth browser callback. |
POST /v1/auth/camel | None | Sign in with a verified CamelAccounts access token. |
Account and workspaces
See Profile & workspaces.
| Method and path | Credential | Purpose |
|---|---|---|
GET /v1/me | JWT | Read the current profile. |
PATCH /v1/me | JWT | Update name or avatar. |
DELETE /v1/me | JWT | Delete the current account. |
POST /v1/me/phone | JWT | Add or change the phone number; resets verification and fires an OTP. |
GET /v1/workspaces | JWT | List workspaces available to the account. |
POST /v1/workspaces | JWT | Create a workspace. |
GET /v1/workspaces/{slug} | JWT | Read one workspace. |
PATCH /v1/workspaces/{slug} | JWT | Rename or describe a workspace. |
DELETE /v1/workspaces/{slug} | JWT | Delete a non-default workspace. |
API keys
See API keys.
| Method and path | Credential | Purpose |
|---|---|---|
POST /v1/api-keys | JWT | Create a key; the secret is shown once. |
GET /v1/api-keys | JWT | List keys and their prefixes. |
PATCH /v1/api-keys/{id} | JWT | Rename a key. |
DELETE /v1/api-keys/{id} | JWT | Revoke a key. |
Models and AI gateway
See Models, Chat completions, Embeddings, Image generation, Video generation, and Voice & Ongea na Ngamia.
| Method and path | Credential | Purpose |
|---|---|---|
GET /v1/models | API key | List enabled paid models and current catalog metadata. |
GET /v1/models/{id} | API key | Read one catalog record by resource id. |
POST /v1/chat/completions | API key or JWT | Send a streaming or non-streaming text/multimodal request. |
POST /v1/embeddings | API key or JWT | Create a complete vector embedding response. |
POST /v1/audio/transcriptions | API key or JWT | Transcribe JSON/base64 or multipart audio. |
POST /v1/audio/speech | API key or JWT | Generate raw MP3 or PCM audio. |
POST /v1/voice/responses | API key or JWT | Transcribe, respond in Kiswahili or English, and optionally synthesize audio. |
POST /v1/documents/analyze | API key or JWT | Analyze a PDF business document with a model instruction. |
POST /v1/vision/analyze | API key or JWT | Analyze a private image with a model instruction. |
POST /v1/video/analyze | API key or JWT | Analyze a private video with a model instruction. |
POST /v1/images/generations | API key or JWT | Generate images as base64 through a catalog image-output model. |
POST /v1/videos | API key or JWT | Submit an async video generation; returns a job_id to poll. |
GET /v1/videos/{job_id} | API key or JWT | Poll a video-generation job for status and settled cost. |
GET /v1/videos/{job_id}/content | API key or JWT | Download a completed video generation as streamed bytes. |
GET /v1/gateway/health | None | Aggregate upstream provider health (no per-provider detail). |
Billing and payments
| Method and path | Credential | Purpose |
|---|---|---|
GET /v1/billing/balance | API key or JWT | Read the current available credit balance. |
GET /v1/billing/transactions | JWT | List the account ledger. |
POST /v1/payments/topup | JWT | Start a TZS mobile-money top-up. |
GET /v1/payments | JWT | List account payments. |
GET /v1/payments/{id} | JWT | Read one payment. |
Activity and notifications
See Activity & analytics and Notifications.
| Method and path | Credential | Purpose |
|---|---|---|
GET /v1/activity | JWT | Read usage events across chat, embeddings, and voice services. |
GET /v1/activity/summary | JWT | Read usage totals for a period. |
GET /v1/notifications | JWT | Read in-app notifications. |
PATCH /v1/notifications/{id}/read | JWT | Mark one notification as read. |
GET /v1/me/notification-preferences | JWT | Read email and SMS preferences. |
PATCH /v1/me/notification-preferences | JWT | Update delivery preferences. |
Public health check
| Method and path | Credential | Purpose |
|---|---|---|
GET /healthz | None | Check that the API process is alive. |
Do not infer private infrastructure, provider credentials, or privileged controls from the public endpoint list. Build integrations only against the documented routes and the live model catalog.