Overview
Base URL, keys, limits and errors.
Base URL
https://staging.api.naalyaschools.ac.ug for this environment. Set it once as NAALYA_API; every path below is relative to it.
Keys
Header: X-API-Key. Created under Development > API Keys; shown once.
| Secret | Publishable | |
|---|---|---|
| Lives in | Your server | The visitor's browser |
| Origin check | None | Origin must match an allowed origin on the key |
| Use for | A backend calling the API | A widget or form calling the API from the page |
An origin is scheme + host + port, exact and lowercase: https://www.school.ac.ug and https://school.ac.ug are two entries.
Never ship a secret key in a page
Revoke it in the Hub if it leaks; revoking is immediate.
Clients
- Widget: one script tag, no code.
@naalya/chaton npm:createNaalyaChatfor any framework,useNaalyaChatfor React,mountNaalyaChatto place the widget from code.- Plain HTTP, as documented on the Chat and Enquiries pages.
Limits
- 60 requests a minute per key.
- 10 requests a minute per visitor IP on publishable keys.
Over the limit: 429, resets within a minute.
Errors
{
"statusCode": 403,
"error": "Forbidden",
"message": "Origin not allowed for this key",
"path": "/api/v1/public-ai/chat",
"timestamp": "2026-10-03T08:15:00.000Z",
"requestId": "a1b2c3d4-1234-4321-9876-abcdefabcdef"
}400 adds details, one line per field.
| Status | Why | Fix |
|---|---|---|
400 | Body failed validation | Read details |
401 | No key, revoked or unknown | Check the header and the key |
403 | Wrong key kind, or origin not allowed | Use the right kind or add the origin |
413 | Body over 1 MB (chat) or 100 KB (enquiries) | Shorten the messages |
429 | Rate limit | Back off for a minute |