Documentation

Builders & API

License HeyBonita's knowledge spine, then add OpenAI-compatible chat and voice on Builder or Studio. Plans and Stripe checkout live on /developers. Keys are minted in Settings → Developers.

Endpoints

GET/api/core/v1/knowledge

Search and page through published knowledge entries from the culture spine. Query params: search, category, page, limit (max 100).

curl "https://heybonita.ai/api/core/v1/knowledge?search=juneteenth&limit=10" \
  -H "x-api-key: $BONITA_API_KEY"

GET/api/core/v1/knowledge/{id}

Fetch a single knowledge entry by id, including biography, tags, and trust metadata.

curl "https://heybonita.ai/api/core/v1/knowledge/ENTRY_ID" \
  -H "x-api-key: $BONITA_API_KEY"

GET/api/core/v1/knowledge/map

Geo-tagged cultural map entries (city/state, coordinates, peoples, time period) for map visualizations.

curl "https://heybonita.ai/api/core/v1/knowledge/map" \
  -H "x-api-key: $BONITA_API_KEY"

GET/api/core/v1/knowledge/regional?region={name}

Regional knowledge for a city, state, or region name. Query param: region (required).

curl "https://heybonita.ai/api/core/v1/knowledge/regional?region=atlanta" \
  -H "x-api-key: $BONITA_API_KEY"

GET/api/core/v1/knowledge/calendar

Cultural calendar events — holidays, history, arts, music, community observances. Query params: month (1–12), category, limit.

curl "https://heybonita.ai/api/core/v1/knowledge/calendar?month=6" \
  -H "x-api-key: $BONITA_API_KEY"

GET/api/core/v1/knowledge/random

A random published knowledge entry — handy for 'on this day' or discovery widgets.

curl "https://heybonita.ai/api/core/v1/knowledge/random" \
  -H "x-api-key: $BONITA_API_KEY"

Machine-readable spec: /api/core/v1/openapi.json

Authentication

Send your key on every request as the x-api-key header (or Authorization: Bearer <key>). Invalid keys return 401; deactivated keys return 403.

curl "https://heybonita.ai/api/core/v1/knowledge?limit=5" \
  -H "x-api-key: $BONITA_API_KEY"

During beta, read endpoints may answer unauthenticated requests at fair-use levels. Keep keys server-side — never ship them in browser bundles.

Beta terms

No enforced per-key rate limits yet — stay within fair use.
No metered billing yet for approved partners during beta.
Responses are JSON with an ok boolean; list endpoints include pagination fields.

Request a key

Self-serve key creation isn't available yet. Tell us who you are and what you're building; approved requests receive a key by email. Or write developers@heybonita.ai.