Skip to main content

HeyBonita API · v1

Call Bonita from your product

A keyed, Stripe-billed API for HeyBonita’s knowledge spine, conversational chat, and voice. Partners see bonita — not rented model names. Subscribe, mint a key in Settings → Developers, then call the endpoints below.

Plans

Usage that stays profitable

Monthly subscription. Extra usage bills on Stripe at the rates below, with a monthly cap.

HeyBonita API

Culture

License the knowledge spine

$49/mo

  • • 40,000 knowledge reads / month
  • • Search, map, regional, and calendar
  • • Extra knowledge usage at $0.002 / read
  • • Schools, museums, and media tools

Most teams

Builder

Bonita in your product

$129/mo

  • • Everything in Culture
  • • 2,500 standard + 250 premium chat turns
  • • 250 Bonita voice reads
  • • OpenAI-compatible chat completions

HeyBonita API

Studio

Volume with headroom

$399/mo

  • • Everything in Builder
  • • 150,000 knowledge reads / month
  • • 10,000 standard + 800 premium chat turns
  • • 800 Bonita voice reads

Extra usage: $0.002 per knowledge read; $0.025 per standard chat turn; $0.12 per premium chat turn; $0.09 per voice read (500 characters). Yearly plans include the same monthly usage pool and pause extra usage at the included cap (upgrade or wait for the next month).

Endpoints

What's available in v1

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"
POST/api/v1/chat/completions

OpenAI-compatible Bonita chat. Models: bonita (auto-route) or bonita-premium. Culture RAG and Bonita voice layers are included. Builder or Studio plan required.

curl "https://heybonita.ai/api/v1/chat/completions" \
  -H "Authorization: Bearer $BONITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"bonita","messages":[{"role":"user","content":"What is Juneteenth?"}]}'
POST/api/core/v1/voice

Bonita TTS (MP3). Builder or Studio. Extra usage is $0.09 per 500 characters.

curl "https://heybonita.ai/api/core/v1/voice" \
  -H "x-api-key: $BONITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hey, I’m Bonita."}' \
  --output bonita.mp3

Machine-readable spec: /api/core/v1/openapi.json (OpenAPI 3.0 — covers the Culture API paths above).

Authentication

API keys

Send your key on every request as the x-api-key header (or Authorization: Bearer <key>). Keys are validated against HeyBonita's central key store; invalid keys return 401 and deactivated keys return 403, both as JSON.

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

During beta: read endpoints also answer unauthenticated requests at fair-use levels while we onboard early partners. Key enforcement will switch on ahead of general availability — active keyholders are unaffected. Keep keys server-side; never ship them in browser or mobile bundles.

Limits & plans

Honest beta terms

  • Included usage, then extra usage. Each plan includes a monthly pool. Extra usage bills on Stripe at published rates, with a monthly extra-usage cap so a runaway key cannot wipe the month.
  • Chat and voice require Builder or Studio. Culture remains knowledge-only. Knowledge reads without a key stay on the open beta fair-use path until CULTURE_API_REQUIRE_KEY=true.
  • Responses are JSON with an ok boolean; list endpoints include total, page, and limit for pagination.
  • Entries are filtered to published, culturally on-mission content. Trust metadata (source URL, verification status, confidence) is included where available.

Get access

Request a key

Paid plans mint keys in Settings → Developers. Schools and museums that need invoicing can still request a review. Prefer email? Write to developers@heybonita.ai.