OpenAPI spec

The Cobuntu REST API ships a versioned OpenAPI 3.1 spec.

Download

JSON: /openapi.json (this docs site)
Production: https://api.cobuntu.com/openapi.json (coming with the next backend release)

Both URLs serve the same spec. The docs-site copy is the one this site renders interactively; the api.cobuntu.com copy is what downstream tools (@cobuntu/sdk codegen, Postman, Insomnia, Stainless, Speakeasy, Fern, etc.) should consume in CI to stay current.

Scope

The spec covers every route under /api/v1/. 24 paths today, grouped into 9 tags:

Tag	Endpoints
Events	List, detail, tiers, free-RSVP, tier-form
Articles	List, by-slug
Products	List, by-SKU
Members	Public directory, kick, ban
Atlas	Hotspots, hotspot detail, categories
Segments	Public list, check-email, form, submit, admin patch
Applications	Approve, reject
Broadcasts	Send
Rules	Accept

Each route declares its required scope (READ_PUBLIC, WRITE_MEMBERS, WRITE_SALES, WRITE_BROADCASTS, ADMIN) and emits typed responses referencing 11 schema components (Event, Tier, Article, Product, Member, AtlasHotspot, AtlasCategory, Segment, Membership, Error, Pagination).

Authentication

Two apiKey schemes, both pass via the X-API-Key header:

PublishableKey (pk_live_…) — browser-safe, capped at READ_PUBLIC. Auto-provisioned per community via GET /communities/{tag}/publishable-key (no auth required).
SecretKey (sk_live_…) — server-only, never ship in browser bundles. Can carry any scope.

Use it to generate a client

The spec is enough to generate a typed client in any language with an OpenAPI codegen:

# Stainless
npx stainless generate --spec https://docs.cobuntu.com/openapi.json
 
# Speakeasy
speakeasy generate sdk --schema https://docs.cobuntu.com/openapi.json --lang typescript
 
# OpenAPI Generator (open source)
openapi-generator-cli generate -i https://docs.cobuntu.com/openapi.json -g typescript-fetch -o ./cobuntu-client

The forthcoming @cobuntu/sdk Node package will be generated from this spec — same source, same surface, just packaged.

Stability

/v1/* is forever-stable.

Additive changes (new fields, new endpoints, new scopes) land on v1 directly and never break existing clients.
Breaking changes (removing fields, renaming params, changing response shapes) mint /v2/*. Both versions coexist for at least 12 months after v2 GA.

Inline interactive renderer

Render the spec inline with a Redoc / Stoplight embed — coming in the next docs pass. For now, the raw openapi.json link above is the source of truth.

Overview Authentication