APIOverview
Wonda API offers a single server-side chat endpoint backed by an AI provider and model configured for your project. The provider credentials are managed by Wonda; your application authenticates using its project API key.
Endpoint: POST https://api.wonda.co.zw/v1/chat
Requests use JSON and are processed under the project's configured output cap, rate limit and daily spend limit. Streaming and client-side provider/model switching are not supported by this endpoint.
Authentication
Include your project key in the HTTP Authorization header as a bearer token. All requests must be made over HTTPS.
Authorization: Bearer $WONDA_API_KEY Content-Type: application/json Idempotency-Key: unique-key-000001
Keep the key secret. Store it in a server-side environment variable or private configuration file. Never place it in browser JavaScript, HTML, a mobile app bundle or a public source repository.
Every new request needs a unique Idempotency-Key containing 16–96 permitted characters. This protects against duplicate billing caused by accidental resubmission. Do not automatically retry ambiguous upstream failures.
Send a request
The request body contains a messages array with 1–12 objects. Each message has a role (system, user or assistant) and a non-empty string content.
curl -X POST https://api.wonda.co.zw/v1/chat \
-H "Authorization: Bearer $WONDA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(openssl rand -hex 16)" \
-d '{"messages":[{"role":"user","content":"Summarize this text."}]}'The configured model and provider are selected by Wonda for the project; do not add model, provider, stream or tools fields to the request.
Response and errors
On completion, the JSON response includes a request ID, generated reply, model, input/output usage and settled per-request charge.
{
"id": "wa_123",
"reply": "Example response text.",
"model": "project-configured-model",
"usage": {"input_tokens": 10, "output_tokens": 20},
"billed_usd": "$0.020000"
}| HTTP status | Meaning |
|---|---|
| 400 | Invalid JSON, message structure or request parameters. |
| 401 | Missing, invalid or inactive API key. |
| 402 | Insufficient prepaid credits. |
| 409 | Duplicate idempotency key for the same project. |
| 429 | Rate or daily spend limit reached. |
| 502 | Upstream outcome is uncertain and may require reconciliation. Do not automatically retry. |
| 503 | Gateway or provider temporarily unavailable. |
For uncertain provider responses, retain the request's idempotency key and contact support. Never assume that a timeout means no upstream charge occurred.
Project controls
The Wonda team configures each project with a provider/model combination, maximum message size, output-token limit, request rate, daily spend ceiling and per-request fee.
Authenticated customers can view their active projects, API key prefixes (not full secrets), recent requests and monthly statements in the developer customer portal.
Safety and billing
- Use Wonda API only from your trusted backend over HTTPS.
- Keep all project API keys outside version control and browser applications.
- Project requests are charged at the configured prepaid per-request rate after credit reservation.
- Ambiguous upstream errors may retain reserved credit until investigated and reconciled.
- Prompt content may be processed by the configured upstream AI provider; it is not retained in the gateway's financial ledger.
- Maintain your own application-level access control, consent and data-handling practices.
Request developer access
Wonda API is currently a managed, controlled-access offering. To discuss a pilot integration, project setup, account recovery, credit funding or API key rotation, contact the Wonda team.