API Reference

Qarl Buddy Chat API.

A single stateless endpoint. You send the conversation, ZETIORA returns the next reply.

POST/api/public/v1/ai/chat

Authenticate with Authorization: Bearer <your key>. All requests are logged against the project that owns the key and counted toward its rate limits. Conversations are stateless — resend prior turns to keep context.

Request

POST /api/public/v1/ai/chat
Authorization: Bearer zk_live_xxxxxxxxxxxx
Content-Type: application/json

{
  "assistant": "qarl-buddy",
  "messages": [
    { "role": "user", "content": "Mambo vipi bro?" },
    { "role": "assistant", "content": "Poa sana mkuu! Wewe je? 😎" },
    { "role": "user", "content": "Nimechoka na kazi bana." }
  ]
}

Body fields

Field	Type	Notes
assistant	string	Required. Must be "qarl-buddy".
messages	array	Required. 1–40 turns, oldest first.
messages[].role	string	"user" or "assistant".
messages[].content	string	1–4000 characters.

Response

200 OK

{
  "id": "5b7f...",
  "assistant": "qarl-buddy",
  "created": 1774000000,
  "message": {
    "role": "assistant",
    "content": "Pole mkuu 😮‍💨 Kazi imekubana leo? Hebu niambie..."
  },
  "usage": {
    "input_tokens": 42,
    "output_tokens": 65,
    "response_ms": 812
  }
}

Error shape

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: 20 requests per minute."
  }
}

Error codes

HTTP	Code	Meaning
400	invalid_request	Body failed validation (missing assistant, empty messages, message too long).
401	missing_api_key	No Authorization header was supplied.
401	invalid_api_key	The key does not exist or is malformed.
401	api_key_revoked	The key was revoked in the console.
403	project_suspended	The owning project is not active.
429	rate_limit_exceeded	Per-minute limit reached for this project.
429	daily_quota_exceeded	Per-day quota reached for this project.
503	provider_unavailable	Upstream AI capacity is unavailable. Retry with backoff.
500	internal_error	Unexpected server error.

Rate limits

Free projects start at 20 requests per minute and 500 requests per day. Limits are enforced per project, not per key. Retry 429 responses with exponential backoff.