REST API
Cobuntu's REST API lives at https://api.cobuntu.com, namespaced
under /api/v1/. Every endpoint is scope-gated by an API key
you generate per-community.
Base URL
https://api.cobuntu.com/api/v1All endpoints in this section are relative to that.
Authentication
Pass your key in the X-API-Key header:
curl https://api.cobuntu.com/api/v1/communities/my-community/events \
-H "X-API-Key: pk_live_..."Two key types per community (Stripe-style):
| Type | Prefix | Use from | Scope cap |
|---|---|---|---|
| Publishable | pk_live_… | Browser, server, anywhere | READ_PUBLIC only |
| Secret | sk_live_… | Server only — never ship in browser bundles | Any scope (READ_PUBLIC + WRITE_MEMBERS + WRITE_SALES + WRITE_BROADCASTS + ADMIN) |
Generate keys in cobuntu-admin → Integrations → API Keys.
Scopes
| Scope | Grants |
|---|---|
READ_PUBLIC | List/get public-readable resources: events, articles, products, members, atlas hotspots, segments |
WRITE_MEMBERS | Create/update/delete member-level resources: RSVPs, form submissions, profile updates |
WRITE_SALES | RSVP for paid events, checkout flows |
WRITE_BROADCASTS | Send emails to segments (rate-limited 5 per 24h per community) |
ADMIN | All of the above + ban/kick members, edit segments |
ADMIN satisfies every other scope's check. Choose the narrowest
scope that works for your use case.
Endpoints (today)
| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | /communities/:tag/events | READ_PUBLIC | List events |
| GET | /communities/:tag/events/:slug | READ_PUBLIC | Event detail |
| GET | /communities/:tag/events/:slug/tiers | READ_PUBLIC | Tier list for an event |
| POST | /communities/:tag/events/:slug/rsvp | WRITE_SALES | RSVP to a free event |
| GET | /communities/:tag/tiers/:tierId/form | READ_PUBLIC | Form schema for a tier |
| GET | /communities/:tag/articles | READ_PUBLIC | List published articles |
| GET | /communities/:tag/products | READ_PUBLIC | List products |
| GET | /communities/:tag/products/:sku | READ_PUBLIC | Product detail |
| GET | /communities/:tag/members | READ_PUBLIC | List members (public) |
| GET | /communities/:tag/atlas/hotspots | READ_PUBLIC | List atlas hotspots |
| GET | /communities/:tag/atlas/hotspots/:id | READ_PUBLIC | Hotspot detail |
| GET | /communities/:tag/atlas/categories | READ_PUBLIC | Atlas categories |
| GET | /communities/:tag/segments/public | READ_PUBLIC | Public segments (tiers) |
| GET | /communities/:tag/segments/:id/form | READ_PUBLIC | Segment form schema |
| POST | /communities/:tag/segments/:id/submit | WRITE_MEMBERS | Submit segment form |
| POST | /communities/:tag/rules/accept | WRITE_MEMBERS | Acknowledge community rules |
| POST | /communities/:tag/members/:userId/kick | WRITE_MEMBERS | Kick a member |
| POST | /communities/:tag/members/:userId/ban | WRITE_MEMBERS | Ban a member |
| POST | /communities/:tag/applications/:id/approve | WRITE_MEMBERS | Approve a membership application |
| POST | /communities/:tag/applications/:id/reject | WRITE_MEMBERS | Reject a membership application |
| PATCH | /communities/:tag/segments/:id | ADMIN | Update segment (name / pricing / active) |
| POST | /communities/:tag/broadcasts | WRITE_BROADCASTS | Send a one-shot mass email |
OpenAPI 3.1 spec at https://api.cobuntu.com/openapi.json (coming
in the next docs release; for now, this table is the contract).
Versioning
/api/v1/...is forever-stable. Additive changes (new fields, new endpoints) land here.- Breaking changes mint
/api/v2/...— both coexist until external consumers migrate.
Rate limits
| Key | Limit |
|---|---|
Publishable (pk_live_…) | 100 req/s per key |
Secret (sk_live_…) | 50 req/s per key |
| Broadcasts | 5 sends per community per 24h (windows are shared with admin-UI sends) |
Exceeded limits return 429 Too Many Requests with a
Retry-After header.
Pagination
List endpoints accept ?limit=20&offset=0 (or ?cursor=... for
cursor-paginated ones — noted per-endpoint). Default limit is 20,
max is 100.