Developer docs

The OneGov AI API lets your software ask questions about Zimbabwe's Constitution, Acts of Parliament, statutory instruments, general notices, Government Gazettes and national policies, and get back an answer with exact section citations.

Getting a key

API access is part of the Pro plan (US$15 per 30 days). In the app, sign in, open your account menu and choose API keys to create a key. Keys look like ogk_.... You can hold up to 5 active keys and revoke any of them at any time.

Treat keys like passwords. Anyone with your key can spend your monthly call allowance.

Authentication

Send the key in the Authorization header on every request:

Authorization: Bearer ogk_your_key_here

Ask a question

POST https://onegovai.app/api/v1/ask

Field	Type	Description
`question`	string, required	The question, 1 to 8000 characters.
`lang`	string, optional	`en` (default), `sn` for Shona, or `nd` for Ndebele.

Example request:

curl -X POST https://onegovai.app/api/v1/ask \
  -H "Authorization: Bearer ogk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"question": "What does section 61 of the Constitution say?"}'

Example response:

{
  "answer": "Section 61 of the Constitution protects ... (Markdown)",
  "searches": ["section 61 Constitution freedom of expression"],
  "sources": [
    {"instrument": "Constitution of Zimbabwe", "citation": "s 61"}
  ],
  "share_url": "https://onegovai.app/s/ab12cd34ef"
}

Field	Description
`answer`	The answer in Markdown, with section citations.
`searches`	The corpus searches run to produce the answer.
`sources`	The instruments consulted while answering, with citations where available.
`share_url`	A public page showing this exact question and answer.

Search the corpus

POST https://onegovai.app/api/v1/search — the same hybrid (vector + keyword) retrieval the agent uses, without the LLM. Fast, and ideal for building your own features on the corpus. Counts toward the monthly call limit.

Field	Type	Description
`query`	string, required	Search text, 1 to 1000 characters.
`top_k`	int, optional	Results to return, 1–20 (default 8).
`doc_type`	string, optional	`constitution`, `act`, `si`, `gn`, `gazette` or `policy`.
`year`	int, optional	Restrict results to instruments of a year.

curl -X POST https://onegovai.app/api/v1/search \
  -H "Authorization: Bearer ogk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "minimum wage domestic workers", "top_k": 5}'

Each result carries instrument, citation, doc_type, section, section_title, text, a relevance score and a download_url for the original gazetted document.

Check your usage

GET https://onegovai.app/api/v1/usage — the key's consumption this month. Free: does not count as a call.

{"month": "2026-07", "used": 143, "limit": 1000,
 "remaining": 857}

Python example

import requests

r = requests.post(
    "https://onegovai.app/api/v1/ask",
    headers={"Authorization": "Bearer ogk_your_key_here"},
    json={"question": "What is the minimum wage law in Zimbabwe?"},
    timeout=60,
)
r.raise_for_status()
print(r.json()["answer"])

JavaScript example

const r = await fetch("https://onegovai.app/api/v1/ask", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ogk_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ question: "How do I register a company?" }),
});
const data = await r.json();
console.log(data.answer);

Limits

1000 calls per key per calendar month. Usage per key is shown in the API keys screen in the app.
8 requests per minute per IP (shared with the web app).
Answers can take 5 to 20 seconds; use a generous timeout.

Errors

Status	Meaning
`400`	Bad request, for example an empty or too-long question.
`401`	Missing, unknown or revoked API key.
`402`	The Pro plan on the key's account has expired.
`429`	Monthly call limit or per-minute rate limit reached.
`502 / 503`	Temporary problem answering; retry after a short wait.

Error bodies are JSON: {"detail": "..."}.

Public endpoints (no key needed)

These read-only endpoints back the web app and are free to use for light, non-abusive traffic. They share the per-IP rate limit.

Endpoint	Returns
`GET /api/catalog`	Every instrument in the corpus, newest first. Optional filters: `?doc_type=act\|si\|notice\|...` and `?year=2025`.
`GET /api/whatsnew?n=12`	The `n` most recently gazetted instruments.
`GET /api/meta`	Corpus size and the date it was last updated.
`GET /api/source?q=Labour+Act`	Best-matching source document for a title, with its download URL.
`GET /api/download/{file}`	The raw gazetted PDF/HTML itself.
`GET /api/answer/{id}`	A stored question and answer (the JSON behind `share_url`).

Example — list this year's statutory instruments:

curl "https://onegovai.app/api/catalog?doc_type=si&year=2026"

Good to know

Each call is independent; there is no conversation state. Put all needed context in the question.
Answers are general information from the gazetted texts, not legal advice.
Do not send personal details such as identity numbers in questions. See the privacy policy and terms of service.

Support

Questions, bug reports or higher-volume needs: kudziezhuwaki@gmail.com. Breaking API changes will be announced on this page ahead of time.

Back to the app