Developer Guides

Authentication

Every /api/v1/** request requires an Authorization: Bearer <key> header. Issue a key from your organization's Developer page in the dashboard. Keys are prefixed kv_live_ or kv_sandbox_. The raw key value is shown once, at creation — Kuvola only ever stores its hash.

SDK examples

No official SDK is published yet — every language works with a plain HTTP client.

cURL

curl https://kuvola.ao/api/v1/datasets \
  -H "Authorization: Bearer kv_live_..."

JavaScript

const res = await fetch("https://kuvola.ao/api/v1/datasets", {
  headers: { Authorization: "Bearer kv_live_..." },
});
const { data, pagination } = await res.json();

Python

import requests

res = requests.get(
    "https://kuvola.ao/api/v1/datasets",
    headers={"Authorization": "Bearer kv_live_..."},
)
body = res.json()

Webhooks

For a source that pushes data to Kuvola rather than being polled — infrastructure-to-infrastructure only, authenticated with a shared bearer secret, not a per-organization API key. See ConnectorGuide.md for the full setup.

POST /api/internal/ingestion/webhook/{sourceId}
Authorization: Bearer <INGESTION_CRON_SECRET>
Content-Type: application/json

{
  "datasetSlug": "your-dataset-slug",
  "datasetName": "Your Dataset",
  "records": [
    { "code": "...", "name": "...", "country_code": "AO", "unit": "...", "frequency": "daily", "value": 123.45, "as_of_date": "2026-08-09" }
  ]
}

Error reference