REST API reference

Member sign-in, sign-up, emailed sign-in links, password recovery, email verification and Continue with Google, all called from your server with a secret key holding MEMBER_AUTH. Each returns a member session bound to this community; see Member sessions and user keys for how to store it and Sign in and recover accounts for the full flow.

Use it to show and manage the community's members from your own backend.

List members

Scope READ_PUBLIC, or MEMBERS_ADMIN for the full roster

Without MEMBERS_ADMIN (any key type, no member session), both routes follow the community's Members page setting:

To show the directory to a signed-in member, use GET /me/directory with their member session instead. For an admin integration that needs everyone, use a secret key holding MEMBERS_ADMIN (or ADMIN): it returns the full roster, hidden members included. MEMBERS_ADMIN is never available on a publishable key and is never granted to apps.

Membership standing

Scope READ_PUBLIC

Whether this person is a member of this community, and in what state. An app that gates its own content asks here.

It follows the same Members page rules as the roster above: members who hide from the directory are 404, and a members-only or private community answers 403 unless the key holds MEMBERS_ADMIN.

permissions and segments (paid tiers) are entitlements, so they are returned only to a secret key holding APP_ONBOARDING or MEMBERS_ADMIN. For any other key the fields are left out: absent means "not granted to this key", an empty array means "none". Read them as optional:

const m = await cobuntu.members.membership(userId);
if (m.permissions === undefined) {
  // This key may not see entitlements. Do not treat it as "no permissions".
}

Applications

Use it to keep your own apply form and push the result in. You own the apply page, any scoring and any review screen; Cobuntu is the member home — directory, events, chat.

Make these calls non-blocking: if Cobuntu is unreachable, save the application to your own store anyway and retry later.

Read a tier's form schema

Scope READ_PUBLIC

The fields the community configured for that tier, so your form asks the same questions. Read it rather than hard-coding, or your form silently drifts from what the community expects the moment a leader edits it.

• An unknown :communityTag is 404, and a key from another community is 403. The form is only ever looked up inside the key's community.
• A hidden (invite-only) tier's form is served only with ?invitationToken=<token> for that tier. Without it the tier looks like it does not exist (404).

Submit an application

Scope WRITE_APPLICATIONS — carried by the publishable key.

{ "answers": { "email": "…", "name": "…" }, "source": "your_site" }

source tags where the application came from. Worth setting: it is how a community tells site applications apart from ones made on Cobuntu.

For this to land as PENDING rather than admitting someone immediately, the community must be in application mode.

Which tiers can be submitted

Only an active, non-deleted tier. A hidden tier also needs invitationToken in the body: a pending, unexpired invitation to that tier with uses left. A personal invitation must also match the submitted email. Every failure answers the same 404 "Segment not found" as a missing tier.

{ "answers": { "email": "…" }, "invitationToken": "…" }

Email confirmation on browser submits

On the publishable key nobody has proved they own the submitted address. So a submit that would otherwise be admitted at once (a free tier on an open, live community) stays PENDING and answers:

{ "success": true, "requestId": "…", "awaitingEmailConfirmation": true }

The applicant is emailed a confirmation link (valid 48 hours). Clicking it runs the normal approval and sends them to the community's sign-in page. Show a "check your inbox" state when you see awaitingEmailConfirmation, not a "welcome in" one.

No confirmation is needed when:

• you submit with a secret key from your server (you vouch for the address), or
• a signed-in applicant submits their own account email.

Submits are limited to 10 per hour per IP (the real client IP, not a header the caller sets).

Approve or reject

Scope WRITE_MEMBERS

Server side only. WRITE_MEMBERS is deliberately absent from the publishable key, because it lets the caller name any email in the body. A browser-exposed key holding it would let anyone admit anyone.

Paid tiers

Scope WRITE_APPLICATIONS

Chain this after /segments/:id/submit when the tier is paid: submit returns a requestId, and this turns it into a checkout.

Same base URL and same key as every other endpoint here.

Events

Scope READ_PUBLIC

Use it to list events on your own site and link each one through to the community app.

Registration, invitations, attendance and donations are covered in the Events guide and the client reference. Editing an event by id (PATCH /events/:eventId) is on Server and app platform.

The event bridge

Scope WRITE_EVENTS

Upsert an event that lives on somebody else's ticketing platform, addressed by their id rather than ours. PUT creates on first call and updates afterwards, so an importer can run repeatedly without tracking what it has already sent.

Use it to sync events from external ticketing platforms into the community.

Why the identifier is theirs and not ours

An importer reading someone else's calendar has no Cobuntu id to send. Keying on (platform, externalId) makes the write idempotent from the caller's point of view: re-running the importer reconciles rather than duplicates.

This is the one place in Embed where a resource is addressed by a foreign key, and that is deliberate rather than an oversight.

What the response tells you

Read back created, archived, event.id, event.slug and linkConflicts — so a sync run can report what it changed instead of guessing.

Write carefully. Make your importer dry-run by default, write only on an explicit flag, pause between writes, and record every result. An importer that silently rewrites a community's calendar is a bad afternoon for whoever owns that calendar.

Donations to a product

Scope WRITE_SALES (donate), READ_PUBLIC (summary)

A "support the maker" donation without buying the product. The body is { donation: { amount }, customer?: { email }, successUrl, cancelUrl }, with amount a positive integer in cents; customer.email is required when no member session is forwarded. It answers { checkoutUrl, sessionId }: send the buyer to checkoutUrl. The summary answers { total, count, currency } with no donor identity.

const { checkoutUrl } = await cobuntu.products.donate("acme-notebook", {
  donation: { amount: 1000 },
  customer: { email },
  successUrl: returnUrl(origin, "/thanks"),
  cancelUrl: returnUrl(origin, "/marketplace/acme-notebook"),
});
const { total, count } = await cobuntu.products.donationsSummary("acme-notebook");

Codes: 400 INVALID_DONATION_AMOUNT, 400 missing return URLs or email, 404 unknown product, 429 (30 per hour per visitor IP). The default publishable key does not carry WRITE_SALES, so donate from your server.

Use it to run a full storefront on your own domain.

Products

Scope READ_PUBLIC

The detail route takes either the product id or its SKU. Both have always worked; the path parameter used to be named :sku, which is why earlier versions of this page said SKU was the only way in.

Filtering

An unknown category id narrows to nothing and returns an empty page rather than a 400, so a filter pointed at a deleted category does not break the page. GET /products/facets returns the counts for a filter bar. Each product carries seller and variants[] with stock and member prices. See the Marketplace guide for checkout, purchases and refunds.

Courses

Scope READ_PUBLIC

Courses are a product type and sit behind the community's Learning install. The list takes ?category / ?subcategory (from the COURSE taxonomy, categories({ type: "COURSE" })) and ?limit / ?offset. It answers { courses, pagination } with each course in the product shape, and 404 when Learning is not enabled for the community. Only PUBLIC courses are listed. On the client: cobuntu.courses.list({ category, limit, offset }).

There is deliberately no /courses/:id. A course is a product row with productType: COURSE, so GET /products/:idOrSku already serves it.

Categories

Scope READ_PUBLIC

Returns the community's categories with their subcategories nested, so a filter UI is one request rather than one per level. Feed the ids straight back as ?category= / ?subcategory=.

?type is required and must be one of PRODUCT, EVENT, COURSE, ARTICLE. It is not defaulted on purpose: categories are one table with a content-type discriminator, and a default would hand you a different taxonomy's categories with a 200.

Cart

Scope WRITE_CART on all of them, including the GET.

The read takes a write scope deliberately: a cart is the caller's own private object, and the same credential governs reading and writing it. Splitting them would imply a read-only cart view exists for somebody else to use.

Why the cart is held server side

So a landing page on another origin shares one cart with the community app. That is the whole point: somebody fills a basket on your site and finishes on Cobuntu without losing it.

handoff and claim are the two halves of that crossing. merge folds a guest cart into a member's once they sign in.

A signed-in caller is identified by their session; an off-origin guest holds an X-Cobuntu-Cart-Token instead. One route pair serves both rather than two near-identical surfaces that would drift apart.

The signed-in session here is the community app's own (an Authorization: Bearer session on its origin). An embed member session (X-Cobuntu-Auth-Token) is not accepted, so from your own server every cart is a guest cart and merge answers 401. On the client the routes are cart.create, cart.get, cart.addItem, cart.updateItem (0 removes), cart.removeItem, cart.merge, cart.handoff and cart.claim; each takes the cart token and sends it as the header. See the Cart and handoff guide.

Branding

Scope READ_PUBLIC

Colours, fonts and logos for the community, so an app on another origin can look like it belongs to it. Use it to theme your own surface to match the community.

const branding = await cobuntu.branding();
// { name, iconUrl, theme: { ...the community's theme document }, communityUrl }

theme is passed through exactly as the community stored it, so read the tokens you know and ignore the rest. It is {} when no theme is set. No visibility gate: branding is what every anonymous visitor already sees.

City autocomplete

Scope READ_PUBLIC. No member session needed.

City suggestions for a profile or sign-up form, so your site needs no maps key of its own.

const cities = await cobuntu.places.cities({ q: "lisb", lang: "en" });
// [{ placeId, description: "Lisbon, Portugal", mainText: "Lisbon",
//    secondaryText: "Portugal", countryCode: "PT" }]

• Always 200. A lookup problem degrades to [], so the visitor can still type their city by hand.
• q is trimmed and cut to 100 characters; under 2 characters answers []. At most 6 suggestions.
• countryCode is ISO 3166-1 alpha-2, or null when it could not be resolved.
• Limited to 60 lookups per minute per visitor IP, checked before the key. Debounce keystrokes (about 250 ms). A limited call is 429 with predictions: [].

Map (Atlas)

Scope READ_PUBLIC

The community map: its curated places (hotspots) and their categories, for a map on your own site. The list answers { hotspots }, filtered by a category or subcategory id from atlas/categories (which answers { categories }); the detail answers the hotspot itself. Each hotspot carries at least id, name, latitude and longitude; treat other fields as optional.

Not wrapped by @cobuntu/embed; call with fetch and the publishable or secret key.

Co-creation

Scope READ_PUBLIC. Optional member session in X-Cobuntu-Auth-Token.

May this viewer create an event, a product or a course here, and if not, why not. One entry per surface:

{
  "event":   { "enabled": true,  "requireApproval": false, "feeModel": "FLAT", "state": "allowed",  "reason": "ok" },
  "product": { "enabled": true,  "requireApproval": true,  "feeModel": "FLAT", "state": "locked",   "reason": "tier_locked" },
  "course":  { "enabled": false, "requireApproval": false, "feeModel": null,   "state": "disabled", "reason": "toggle_off" }
}

state is decided in order: disabled (show nothing), signin (no session), join (not an accepted member), locked (the member's tier may not create this kind), allowed. reason is ok, role_grant, not_member, toggle_off, tier_locked or null. Errors: 404 COMMUNITY_NOT_FOUND, 403 WRONG_COMMUNITY.

Marketplace categories

Reads are open (no scope). Mutations are gated on MARKETPLACE_CREATE.

This one is not under /api/v1. It is the unversioned surface, and it is the only documented endpoint here other than the cart handoff that sits outside the versioned API. Call it exactly as written above: it has a different prefix and a different auth posture from the rest.

Reads are deliberately open so a storefront filter can list categories without auth.

Articles

Scope READ_PUBLIC

Use it to run a journal or blog on your own domain from the community's content. Creating, editing and publishing articles (WRITE_ARTICLES) is on Server and app platform.

Feed posts

Scope WRITE_FEED

Use it to post into the community's feed from your own system.

Notifications

Scope WRITE_NOTIFICATIONS

Send a notification to a member through Cobuntu's own bell and email, rather than building a second delivery path your members have to learn.

Both of these are server-side scopes. Neither belongs in a browser.

Use it to pull a community's Cobuntu revenue into your own reporting, next to whatever else the business runs on.

Three reads, all server-side, all scoped to one community.

Ledger entries

Scope READ_FINANCE, plus READ_FINANCE_PII for buyer identity

Every entry is one thing that happened: a sale the community made, a commission it earned on a member's sale, a refund, a donation. Amounts are integer cents with an explicit currency, never a decimal.

Whose money is it

Each entry carries a role, and you should read it before you read net.

This is not decoration. On a commission entry the sale's full value also appears, as gross, because it is useful context — but it is the member's money, not the community's. Summing gross across the ledger will give you a number that looks like revenue and is not. Sum net.

Refunds

A refund is reported on the sale it refunded, as a refund block carrying refundedAt, amount and status. It does not arrive as a separate entry.

A fully refunded sale reports net: 0. So summing net already excludes refunded money and you should not subtract the refund again — the refund block is there to tell you when and how much, not to be added up.

Settlement status

Every entry carries a settlement block saying where the money is. status is one of:

BLOCKED is not a sanction. It is the payout engine recording that a sale will never pay out, and on this endpoint that always means the sale was fully refunded — usually before any transfer ran, so payoutId and paidAt stay null. Such an entry also carries a refund block and reports net: 0.

So do not surface BLOCKED to a community as-is. It reads like a compliance hold or a frozen account, and it means "refunded". Show the entry as refunded, and show net, not gross — a fully refunded sale still has its original gross, so rendering gross displays returned money as income.

Entries are keyed to rows that are only ever inserted, so an incremental sync by cursor never has to re-read the head of the list.

One caveat worth building for: figures can be restated in place. Stripe occasionally settles a fee differently from its original estimate, and when that happens the entry's fees change without a new entry appearing. Re-sync a full window periodically — monthly is ample — rather than trusting an incremental cursor to surface it.

Paging

Entries come back oldest first, so a cursor walks forward in time and a sync never has to re-read the head of the list. Read nextCursor until hasMore is false.

Treat the cursor as opaque. Every entry also carries its own cursor, which is the value to resume from — do not build one out of id, which is prefixed and will not compare the way you expect.

A malformed cursor is a 400, deliberately. Restarting silently from the top would look like it worked and would duplicate everything downstream.

Buyers

Without READ_FINANCE_PII an entry carries only buyerRef: an opaque, stable handle you can group a buyer's purchases by, with no identity attached. With the scope, buyer.email and buyer.name are included as well.

The two are separate grants on purpose. Buyer identity turns a revenue feed into an export of members' purchase history, which is a different thing to agree to. buyerRef can also be null — on a guest checkout, and on any purchase whose buyer has since exercised erasure.

buyer.email prefers the address used at purchase time and falls back to the account's. buyer.name comes from the account, so it is null for a guest checkout and for a buyer who has been erased.

Settlements

Scope READ_FINANCE

What Cobuntu actually transferred, and when. An entry's settlement.payoutId joins to a row here.

This is not your bank statement

Money reaches a community in two hops, and only the first is ours:

1. Cobuntu to the community's Stripe balance. That is a row in this endpoint.
2. Their Stripe balance to their bank. That runs on the community's own Stripe payout schedule, batches however many of our transfers have accumulated, and we do not hold it.

So one bank credit routinely covers several rows here. One community saw nine of our transfers, spread over two months, arrive as a single bank line. If you are reconciling against a bank feed, expect to match many-to-one, and use the Stripe dashboard for the bank side.

Same paging contract as entries.

Totals

Scope READ_FINANCE

Aggregates for a window, broken down by stream and by entry type, and grouped by currency. Totals are never summed across currencies, because a community selling in two of them has two numbers, not one blended one.

Takes ?from= and ?to=; the window you asked for is echoed back.

This is computed from exactly the same entries /entries serves, so the two cannot disagree. If you need a breakdown this does not offer, aggregate the entries yourself rather than expecting another cut here.

What one bank credit covered

Scope READ_FINANCE

A remittance statement: the payouts, and their invoice numbers, behind a single line on the bank statement. JSON by default; add ?format=pdf for a document you can forward to an accountant.

You get a depositId from the payout.deposited webhook, which fires when the money reaches the bank.

totals has three numbers and the third is the interesting one:

unaccounted is normally zero. Non-zero is not an error: it means the deposit also carried money that did not come through Cobuntu, which happens when the same Stripe account takes payments directly. We show it rather than quietly letting the two figures disagree.

This is a statement, not an invoice. Every payout in it was already invoiced on its own, so nothing here is additional income and nothing here should be filed as a separate revenue document.

Keys

These are secret-key only. A publishable key is refused with SECRET_KEY_REQUIRED even when it somehow carries the scope, because a publishable key ships in browser bundles and this is a community's whole commercial history. A key belonging to another community gets WRONG_COMMUNITY.

Reads are logged. A community can be told which key read its finances and when, including whether buyer identity was served — the question a data processing agreement asks.

Routes for an app installed in a community and running on its own origin. They are secret-key only and act with the community's authority.

• App handoff: sign a member into your app with a one-time code, and mint short-lived member tokens.
• Onboarding: read what a member still owes the community and satisfy it in your own UI.
• App data: per-member key/value storage, and writing a member's language back.
• Server patterns: calling these routes with fetch, errors and the acting user.

Every other endpoint in Embed is addressed by community: you hold a key for :communityTag and you read that community's things. These four are addressed by person.

The case they exist for is a personal website. Someone who sells through Cobuntu wants their own products, courses and events on a page they control, under their own domain. That catalogue may span a community they sell into, but it is not that community's to hand out, so no community key can express it.

Authentication

A user key, not a community key. Same two header styles as everywhere else in Embed:

User keys start uk_; community keys start ck_. They are separate credentials against separate tables, and neither works where the other belongs — a community key on these routes is a 401, and a user key on a community route is a 401 too. The prefixes exist so a mix-up is visible before you deploy rather than after.

Scope READ_OWN — the only user-level scope there is. Note there is no user-level equivalent of the community ADMIN wildcard.

Generate and revoke keys in the Cobuntu app under Settings → API. The raw key is shown once and stored only as a hash, so it cannot be retrieved later.

The endpoints

me is not a placeholder. There is no :userId to supply — the owner is whoever the key resolves to. That is deliberate: an id in the path would be either redundant (it has to equal the key's user) or a way to ask for someone else's catalogue.

Courses

Through ?type=COURSE on the products list. A course is a product row with productType: COURSE, so there is no separate route:

Unfiltered, the products list includes courses and excludes event tickets. That matches how a profile works rather than how a marketplace shelf works: a course is a portfolio piece that keeps selling and belongs under its maker's name, where an event is a moment that has passed.

Filtering and pagination

The same parameters as the community lists: ?type, ?category, ?subcategory, ?limit (capped at 100, default 20), ?offset. Events also take ?upcoming=true.

Category ids come from the community categories endpoint. An unknown id returns an empty page, not a 400.

What these return

Exactly what is public. The key belongs to the owner, but its purpose is to render a public web page, so everything it returns is one fetch away from being public:

• drafts are excluded
• member-only items are excluded
• tier backing rows are excluded (every paid tier has its own underlying product row; those are tickets, not listings)

An owner who wants to see their own drafts uses the app.

A product or event that is not yours answers 404, not 403. Ownership is part of the lookup rather than a check after it, so the row simply is not found — a 403 would confirm the id names something real.

Events are not filtered by community, products are

A small asymmetry worth knowing. GET /users/me/products returns products you own, excluding ones a community owns. GET /users/me/events returns events you created, including ones created inside a community — an event is created into a community far more often than not, and excluding those would empty the endpoint for exactly the person it is for.