Segments

Segments are member tiers — the equivalent of "Free", "Pro", "Founding Member", "Annual Supporter" depending on your model. A segment can have a public form (members submit it to apply), pricing (monthly / quarterly / yearly), and an active flag.

Public-read endpoints (READ_PUBLIC) — list segments, fetch form schema, check email. Write endpoints — submit form (WRITE_MEMBERS), accept rules (WRITE_MEMBERS), patch a segment (ADMIN).

Base URL: https://api.cobuntu.com/api/v1

Every endpoint requires an X-API-Key header. See Authentication for scope details.

`GET` `/communities/{communityTag}/segments/public` — List public segments (tiers)

Scope: READ_PUBLIC

Path parameters:

Param	Type	Description
`communityTag`	`string`	Your community's tag (e.g. `bela-escala`, `orbis`).

Response (200):

[
  {
      "id": "…",
      "name": "…",
      "description": "…"  // nullable,
      "color": "…",
      "hasForm": false,
      "priceMonthly": 0  // nullable,
      "priceQuarterly": 0  // nullable,
      "priceYearly": 0  // nullable,
    }
]

Field	Type	Description
`id`	`string`	Stable segment identifier (uuid).
`name`	`string`	Display name (e.g. `Free`, `Pro`, `Founding Member`).
`description`	`string` (nullable)	Long-form description shown on the segment's apply page.
`color`	`string`	Display color, hex.
`hasForm`	`boolean`	True if the segment requires submitting a form to join (use `GET /segments/{segmentId}/form`).
`priceMonthly`	`integer` (nullable)	Monthly price in cents (null = not offered monthly).
`priceQuarterly`	`integer` (nullable)	Quarterly price in cents (null = not offered quarterly).
`priceYearly`	`integer` (nullable)	Yearly price in cents (null = not offered yearly).

Example:

curl https://api.cobuntu.com/api/v1/communities/my-community/segments/public \
  -H "X-API-Key: pk_live_..."

`GET` `/communities/{communityTag}/segments/{segmentId}/check-email` — Check whether an email is already registered for this segment

Scope: READ_PUBLIC

Path parameters:

Param	Type	Description
`communityTag`	`string`	Your community's tag (e.g. `bela-escala`, `orbis`).
`segmentId`	`string`	Segment identifier from `GET /segments/public`.

Query parameters:

Param	Type	Default	Description
`email`	`string`		Email address (RFC 5322).

Response (200):

{
  "exists": false,
  "status": "…",
}

Field	Type	Description
`exists`	`boolean`
`status`	`string`

Example:

curl https://api.cobuntu.com/api/v1/communities/my-community/segments/EXAMPLE_ID/check-email \
  -H "X-API-Key: pk_live_..."

`GET` `/communities/{communityTag}/segments/{segmentId}/form` — Get the segment's form schema

Scope: READ_PUBLIC

Path parameters:

Param	Type	Description
`communityTag`	`string`	Your community's tag (e.g. `bela-escala`, `orbis`).
`segmentId`	`string`	Segment identifier from `GET /segments/public`.

Response (200):

{
  "segmentId": "…",
  "schema": […],
}

Field	Type	Description
`segmentId`	`string`
`schema`	`array`

Example:

curl https://api.cobuntu.com/api/v1/communities/my-community/segments/EXAMPLE_ID/form \
  -H "X-API-Key: pk_live_..."

`POST` `/communities/{communityTag}/rules/accept` — Accept the community rules (per visitor / on first member action)

Scope: WRITE_MEMBERS

Path parameters:

Param	Type	Description
`communityTag`	`string`	Your community's tag (e.g. `bela-escala`, `orbis`).

Request body:

{
  "rulesVersion": 0,
}

Field	Type	Description
`rulesVersion`	`integer`	Integer version of the rules document the visitor accepted. Get the current version from the community's storefront config.

Response (200):

{
  "ok": false,
}

Field	Type	Description
`ok`	`boolean`	Always `true` on a 200 response.

Example:

curl -X POST \
  https://api.cobuntu.com/api/v1/communities/my-community/rules/accept \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

`PATCH` `/communities/{communityTag}/segments/{segmentId}` — Update a segment (name / pricing / active)

Scope: ADMIN

Path parameters:

Param	Type	Description
`communityTag`	`string`	Your community's tag (e.g. `bela-escala`, `orbis`).
`segmentId`	`string`	Segment identifier from `GET /segments/public`.

Request body:

{
  "name": "…",
  "priceMonthly": 0  // nullable,
  "priceQuarterly": 0  // nullable,
  "priceYearly": 0  // nullable,
  "isActive": false,
}

Field	Type	Description
`name`	`string`	New display name. Preserves the segment's id and existing memberships.
`priceMonthly`	`integer` (nullable)	New monthly price in cents. Null disables monthly. Existing subscribers keep their current billing until renewal.
`priceQuarterly`	`integer` (nullable)	New quarterly price in cents. Null disables quarterly.
`priceYearly`	`integer` (nullable)	New yearly price in cents. Null disables yearly.
`isActive`	`boolean`	False = closed to new members (existing memberships unaffected). True = open for new applications.

Response (200):

{
  "id": "…",
  "name": "…",
  "description": "…"  // nullable,
  "color": "…",
  "hasForm": false,
  "priceMonthly": 0  // nullable,
  "priceQuarterly": 0  // nullable,
  "priceYearly": 0  // nullable,
}

Field	Type	Description
`id`	`string`	Stable segment identifier (uuid).
`name`	`string`	Display name (e.g. `Free`, `Pro`, `Founding Member`).
`description`	`string` (nullable)	Long-form description shown on the segment's apply page.
`color`	`string`	Display color, hex.
`hasForm`	`boolean`	True if the segment requires submitting a form to join (use `GET /segments/{segmentId}/form`).
`priceMonthly`	`integer` (nullable)	Monthly price in cents (null = not offered monthly).
`priceQuarterly`	`integer` (nullable)	Quarterly price in cents (null = not offered quarterly).
`priceYearly`	`integer` (nullable)	Yearly price in cents (null = not offered yearly).

Example:

curl -X PATCH \
  https://api.cobuntu.com/api/v1/communities/my-community/segments/EXAMPLE_ID \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

`POST` `/communities/{communityTag}/segments/{segmentId}/submit` — Submit the segment's form (= apply for membership)

Scope: WRITE_MEMBERS

Path parameters:

Param	Type	Description
`communityTag`	`string`	Your community's tag (e.g. `bela-escala`, `orbis`).
`segmentId`	`string`	Segment identifier from `GET /segments/public`.

Request body:

{
  "email": "…",
  "name": "…",
  "formAnswers": { … },
}

Field	Type	Description
`email`	`string (email)`	Applicant's email. If a membership request for this email already exists for this segment, the response is 409 with the existing request id.
`name`	`string`	Applicant's display name. Required for downstream `member.requested` event payloads + email correspondence.
`formAnswers`	`object`	Form answers keyed by field id. Shape must match the segment's form schema (`GET /segments/{segmentId}/form`).

Response (200):

{
  "ok": false,
  "requestId": "…",
  "status": "…",
}

Field	Type	Description
`ok`	`boolean`	Always `true` on a 200 response.
`requestId`	`string`	Stable id for the membership request. Carried in the `member.requested` webhook payload.
`status`	`string (enum)`	PENDING for review-required communities; ACCEPTED when the segment is auto-approve.

Example:

curl -X POST \
  https://api.cobuntu.com/api/v1/communities/my-community/segments/EXAMPLE_ID/submit \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

Products Errors

Segments

GET /communities/{communityTag}/segments/public — List public segments (tiers)

GET /communities/{communityTag}/segments/{segmentId}/check-email — Check whether an email is already registered for this segment

GET /communities/{communityTag}/segments/{segmentId}/form — Get the segment's form schema

POST /communities/{communityTag}/rules/accept — Accept the community rules (per visitor / on first member action)

PATCH /communities/{communityTag}/segments/{segmentId} — Update a segment (name / pricing / active)

POST /communities/{communityTag}/segments/{segmentId}/submit — Submit the segment's form (= apply for membership)

`GET` `/communities/{communityTag}/segments/public` — List public segments (tiers)

`GET` `/communities/{communityTag}/segments/{segmentId}/check-email` — Check whether an email is already registered for this segment

`GET` `/communities/{communityTag}/segments/{segmentId}/form` — Get the segment's form schema

`POST` `/communities/{communityTag}/rules/accept` — Accept the community rules (per visitor / on first member action)

`PATCH` `/communities/{communityTag}/segments/{segmentId}` — Update a segment (name / pricing / active)

`POST` `/communities/{communityTag}/segments/{segmentId}/submit` — Submit the segment's form (= apply for membership)