API design principles

The Bonfire public API is built to be predictable. Once you learn one resource, the rest behave the same way. This page explains the conventions so you can integrate with confidence.

Versioned and stable

All endpoints live under /api/v1. The version prefix means we can evolve the platform without breaking your integration: existing v1 behavior is preserved, and breaking changes ship under a new version.

Resource-oriented

The API is organized around resources — members, spaces, channels, courses, lessons, payments — addressed by stable IDs:

GET    /api/v1/members
GET    /api/v1/members/{id}
POST   /api/v1/channels
PATCH  /api/v1/channels/{id}
DELETE /api/v1/channels/{id}

Standard HTTP verbs do the obvious thing: GET reads, POST creates, PATCH partially updates, DELETE removes. Bodies and responses are JSON.

Authenticated and scoped

Every request carries a Bearer key from Admin → API Keys. Keys hold scopes (e.g. members:read, content:write) so you can grant least privilege per integration. This is the same model the CLI and MCP server build on.

Consistent shapes

• Lists return a paginated collection with cursors, so large communities stay performant.
• Errors always use the { "error": { "code, message } } envelope and standard status codes.
• Timestamps are ISO 8601 in UTC.
• IDs are opaque, prefixed strings (mem_, chan_, evt_) — don't parse them.

Real-time via webhooks

Rather than polling, subscribe to webhooks for push-based events (member.joined, payment.succeeded, …). Combined with the REST API for reads/writes, this covers most integration needs.

Layered tooling

The same API powers three developer surfaces, so you can pick the right altitude:

Related

• Authenticate with the Bonfire API
• Rate Limits and Errors
• Community as Code (CLI)

FAQ

Will v1 ever break? No. Breaking changes land under a new version prefix; v1 stays compatible.

How do I paginate? List endpoints return a cursor; pass it back to fetch the next page.

Are IDs guessable or sequential? No. They're opaque prefixed strings — treat them as black boxes.

REST, CLI, or MCP — which should I use? REST for custom code, CLI for declarative setup, MCP for natural-language admin from Claude.