# Cobuntu Public API v1 - generated, edit with care. openapi: 3.1.0 info: title: Cobuntu Public API version: 1.0.0 license: name: Proprietary url: https://cobuntu.com/terms contact: name: Cobuntu developer documentation url: https://docs.cobuntu.com description: >- The Cobuntu public API, version 1. Every route lives under `/api/v1`; breaking changes ship under a new version prefix while v1 keeps working. Each response carries an `X-Cobuntu-API-Version` header. ## Authentication - **Community API key** in `X-API-Key` (or `Authorization: Bearer `). Keys start with `ck_`. - A **publishable** key is safe in a browser and carries only `READ_PUBLIC`, `WRITE_APPLICATIONS` and `WRITE_CART`. - A **secret** key must stay on your server. `ADMIN` satisfies every scope. `MEMBERS_ADMIN` (secret keys only, never granted to apps) reads the full member roster, including members hidden from the directory. - **Member session** in `X-Cobuntu-Auth-Token`: the token returned by the Auth endpoints, forwarded by your server on member (`/me/...`) calls. - **User key** (`uk_`) in `X-API-Key`, only for `/api/v1/users/me/...`. - `X-End-User-IP`: when calling from your server on behalf of a browser, pass the visitor's IP so per-visitor limits apply to them, not to your server. ## Scopes `READ_PUBLIC`, `WRITE_APPLICATIONS`, `WRITE_CART`, `WRITE_MEMBERS`, `MEMBERS_ADMIN`, `WRITE_SALES`, `WRITE_SUBSCRIPTIONS`, `WRITE_SEGMENTS`, `WRITE_EVENTS`, `WRITE_ARTICLES`, `WRITE_BROADCASTS`, `WRITE_NOTIFICATIONS`, `WRITE_FEED`, `MEMBER_AUTH`, `APP_HANDOFF`, `APP_MINT_MEMBER_TOKEN`, `APP_IDENTITY_EMAIL`, `APP_IDENTITY_PROFILE`, `APP_IDENTITY_LOCALE_WRITE`, `APP_ONBOARDING`, `APP_DATA`, `READ_FINANCE`, `READ_FINANCE_PII`, `ADMIN`; user keys: `READ_OWN`. Each operation lists its scope (also in `x-required-scope`). ## Money All amounts are integers in the **smallest currency unit** (cents), with one exception: the optional `amount` on the two refund endpoints (`POST .../sales/{saleId}/refund` and `POST .../events/{idOrSlug}/sales/me/refund`) is in **major units**. ## Errors Errors are JSON `{ "error": string, "code"?: string, ...details }`. Branch on `code` where documented, never on the message. ## Rate limits 600 requests/min per key across v1; 120 writes/min per key on write endpoints; stricter per-endpoint limits are noted on each operation. Limited responses are `429`, with `RateLimit` headers. servers: - url: https://api.cobuntu.com description: Production externalDocs: description: Cobuntu developer documentation url: https://docs.cobuntu.com/reference/rest-api tags: - name: Auth description: Sign members in and up from your own site (server-side, secret key with MEMBER_AUTH). - name: Members description: >- The signed-in member's own data (`/me`), the member directory and authoritative membership, membership tiers, application forms and review, and community rules. - name: Events description: Event listing, detail, tiers, free RSVP, invitations, self-service and the event import bridge. - name: Checkout description: >- Paid checkout (tickets and marketplace baskets), quotes, session status, buyer refunds, guest order links, paid applications and donations. - name: Commerce description: Products (browse, filter counts, variants, stock), the cross-origin cart, host refunds and subscription admin. - name: Content description: Articles, categories, courses, branding, city autocomplete, map, notifications, feed posts and broadcasts. - name: Finance description: A community's own ledger, settlements and totals, for external reporting. Secret keys only. - name: Apps description: 'Installed-app platform: Sign in with Cobuntu handoff, member onboarding for apps, per-member app data, locale.' - name: User keys description: Reads authenticated by a personal user key rather than a community key. security: - ApiKey: [] paths: /api/v1/communities/{communityTag}/auth/sign-in: post: operationId: postAuthSignIn summary: Sign a member in with email and password description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Server-to-server only: requires a **secret** key with `MEMBER_AUTH` (a publishable key gets `403 SECRET_KEY_REQUIRED`). Returns a member session token to forward as `X-Cobuntu-Auth-Token` on member calls. Signing in to an open community joins it (`newMember: true`). **Rate limit:** 10 attempts per 15 min per key + email. tags: - Auth x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 10 attempts per 15 min per key + email. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Session' example: token: eyJhbGciOi... user: id: usr_123 name: Alex Doe email: alex@example.com avatar: null newMember: false '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: email and password are required' value: error: email and password are required code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_CREDENTIALS: summary: 'INVALID_CREDENTIALS: Email or password is incorrect' value: error: Email or password is incorrect code: INVALID_CREDENTIALS API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SUSPENDED: summary: 'SUSPENDED: This account is suspended' value: error: This account is suspended code: SUSPENDED APPLICATION_PENDING: summary: 'APPLICATION_PENDING: Your application is still pending' value: error: Your application is still pending code: APPLICATION_PENDING NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many sign-in attempts for this email. Try again later.' value: error: Too many sign-in attempts for this email. Try again later. code: RATE_LIMITED RATE_LIMITED_2: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email password: type: string referralCode: type: string description: The visitor's `?ref` code, when signing in joins an open community. Best effort. required: - email - password example: email: alex@example.com password: correct horse battery /api/v1/communities/{communityTag}/auth/sign-up: post: operationId: postAuthSignUp summary: Create a member account description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Server-to-server only: requires a **secret** key with `MEMBER_AUTH` (a publishable key gets `403 SECRET_KEY_REQUIRED`). Only for open communities; communities that review applications return `403 APPLICATION_REQUIRED` (use the apply flow instead). **Rate limit:** 5 per hour per key + end-user IP (send X-End-User-IP). tags: - Auth x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 5 per hour per key + end-user IP (send X-End-User-IP). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - $ref: '#/components/parameters/EndUserIp' responses: '201': description: Success. content: application/json: schema: $ref: '#/components/schemas/Session' example: token: eyJhbGciOi... user: id: usr_123 name: Alex Doe email: alex@example.com avatar: null newMember: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: name, email and password are required' value: error: name, email and password are required code: INVALID_INPUT WEAK_PASSWORD: summary: 'WEAK_PASSWORD: Password is too weak' value: error: Password is too weak code: WEAK_PASSWORD '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: APPLICATION_REQUIRED: summary: 'APPLICATION_REQUIRED: This community requires an application' value: error: This community requires an application code: APPLICATION_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: EMAIL_TAKEN: summary: 'EMAIL_TAKEN: An account with this email already exists' value: error: An account with this email already exists code: EMAIL_TAKEN '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many sign-ups. Try again later.' value: error: Too many sign-ups. Try again later. code: RATE_LIMITED RATE_LIMITED_2: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: name: type: string maxLength: 200 email: type: string format: email password: type: string marketingOptIn: type: boolean description: Accepted but currently ignored. referralCode: type: string description: 'The visitor''s `?ref` code. Best effort: never fails the call.' required: - name - email - password example: name: Alex Doe email: alex@example.com password: correct horse battery /api/v1/communities/{communityTag}/auth/email-link: post: operationId: postAuthEmailLink summary: Email a sign-in link description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Server-to-server only: requires a **secret** key with `MEMBER_AUTH` (a publishable key gets `403 SECRET_KEY_REQUIRED`). Always answers `{ ok: true }` so it never reveals whether an account exists. `redirectPath` must be a same-site path starting with `/`; anything else is dropped. The emailed link carries a token you exchange at `POST /auth/email-link/verify` (valid 15 minutes). **Rate limit:** 3 per 15 min per key + email. tags: - Auth x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 3 per 15 min per key + email. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: ok: type: boolean example: ok: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: A valid email is required' value: error: A valid email is required code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many sign-in links requested for this email. Try again later.' value: error: Too many sign-in links requested for this email. Try again later. code: RATE_LIMITED RATE_LIMITED_2: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email redirectPath: type: string required: - email example: email: alex@example.com redirectPath: /account /api/v1/communities/{communityTag}/auth/email-link/verify: post: operationId: postAuthEmailLinkVerify summary: Exchange an emailed sign-in link for a session description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Server-to-server only: requires a **secret** key with `MEMBER_AUTH` (a publishable key gets `403 SECRET_KEY_REQUIRED`). **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Auth x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Session' example: token: eyJhbGciOi... user: id: usr_123 name: Alex Doe email: alex@example.com avatar: null newMember: false '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: token is required' value: error: token is required code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LINK_EXPIRED: summary: 'LINK_EXPIRED: This link has expired' value: error: This link has expired code: LINK_EXPIRED INVALID_LINK: summary: 'INVALID_LINK: This link is not valid' value: error: This link is not valid code: INVALID_LINK API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SUSPENDED: summary: 'SUSPENDED: This account is suspended' value: error: This account is suspended code: SUSPENDED APPLICATION_PENDING: summary: 'APPLICATION_PENDING: Your application is still pending' value: error: Your application is still pending code: APPLICATION_PENDING NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: token: type: string maxLength: 4096 required: - token example: token: eyJhbGciOi... /api/v1/communities/{communityTag}/auth/me: get: operationId: getAuthMe summary: Who is signed in description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Server-to-server only: requires a **secret** key with `MEMBER_AUTH` (a publishable key gets `403 SECRET_KEY_REQUIRED`). `member` is true for an accepted membership; `segments` lists the active membership tiers. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Auth x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: user: $ref: '#/components/schemas/User' member: type: boolean segments: type: array items: type: object properties: id: type: string name: type: string example: user: id: usr_123 name: Alex Doe email: alex@example.com avatar: null member: true segments: - id: seg_pro name: Pro '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing or expired' value: error: Session is missing or expired code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/auth/oauth/exchange: post: operationId: postAuthOauthExchange summary: Exchange a Continue with Google code for a session description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Server-to-server only: requires a **secret** key with `MEMBER_AUTH` (a publishable key gets `403 SECRET_KEY_REQUIRED`). The second half of "Continue with Google" on your site. The Google redirect lands on your `returnUrl` with a one-time `code` (valid 60 seconds); your server trades it here, with the PKCE verifier it kept, for a member session. PKCE (S256) is required. Every unknown, expired, reused, other-community or verifier-mismatch code answers the same `400 INVALID_CODE`, so codes cannot be probed. No membership is created: who may sign in follows the community's access rules, so `newMember` is always false. `isSignUp` is true when the Google sign-in created the account. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Auth x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/Session' - type: object properties: newMember: type: boolean enum: - false isSignUp: type: boolean example: token: eyJhbGciOi... user: id: usr_123 name: Alex Doe email: alex@example.com avatar: null newMember: false isSignUp: false '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: code and codeVerifier are required' value: error: code and codeVerifier are required code: INVALID_INPUT INVALID_CODE: summary: 'INVALID_CODE: Invalid or expired code' value: error: Invalid or expired code code: INVALID_CODE '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SUSPENDED: summary: 'SUSPENDED: Account suspended' value: error: Account suspended code: SUSPENDED SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: Member sign-in needs a secret server key' value: error: Member sign-in needs a secret server key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: code: type: string codeVerifier: type: string description: The PKCE verifier whose S256 challenge started the flow (43-128 characters). required: - code - codeVerifier example: code: moc_abc123 codeVerifier: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk /api/v1/communities/{communityTag}/auth/password-reset: post: operationId: postAuthPasswordReset summary: Email a password-reset link description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Server-to-server only: requires a **secret** key with `MEMBER_AUTH` (a publishable key gets `403 SECRET_KEY_REQUIRED`). Always answers `{ ok: true }` (no account enumeration). **Rate limit:** 3 per 15 min per key + email. tags: - Auth x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 3 per 15 min per key + email. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: ok: type: boolean example: ok: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: A valid email is required' value: error: A valid email is required code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many password reset requests for this email. Try again later.' value: error: Too many password reset requests for this email. Try again later. code: RATE_LIMITED RATE_LIMITED_2: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email required: - email example: email: alex@example.com /api/v1/communities/{communityTag}/auth/password-reset/validate: get: operationId: getAuthPasswordResetValidate summary: Check a password-reset token description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Server-to-server only: requires a **secret** key with `MEMBER_AUTH` (a publishable key gets `403 SECRET_KEY_REQUIRED`). Does not consume the token; use it to decide whether to show the new-password form. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Auth x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: true name: token schema: type: string maxLength: 4096 responses: '200': description: Success. content: application/json: schema: type: object properties: valid: type: boolean example: valid: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: token is required' value: error: token is required code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LINK_EXPIRED: summary: 'LINK_EXPIRED: This link has expired' value: error: This link has expired code: LINK_EXPIRED INVALID_LINK: summary: 'INVALID_LINK: This link is not valid' value: error: This link is not valid code: INVALID_LINK API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/auth/password-reset/confirm: post: operationId: postAuthPasswordResetConfirm summary: Set a new password description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Server-to-server only: requires a **secret** key with `MEMBER_AUTH` (a publishable key gets `403 SECRET_KEY_REQUIRED`). Consumes the token and signs the member in. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Auth x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Session' example: token: eyJhbGciOi... user: id: usr_123 name: Alex Doe email: alex@example.com avatar: null newMember: false '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: token and password are required' value: error: token and password are required code: INVALID_INPUT WEAK_PASSWORD: summary: 'WEAK_PASSWORD: Password is too weak' value: error: Password is too weak code: WEAK_PASSWORD '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LINK_EXPIRED: summary: 'LINK_EXPIRED: This link has expired' value: error: This link has expired code: LINK_EXPIRED INVALID_LINK: summary: 'INVALID_LINK: This link is not valid' value: error: This link is not valid code: INVALID_LINK API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SUSPENDED: summary: 'SUSPENDED: This account is suspended' value: error: This account is suspended code: SUSPENDED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: token: type: string password: type: string maxLength: 1024 required: - token - password example: token: eyJhbGciOi... password: a new strong password /api/v1/communities/{communityTag}/auth/verify-email: post: operationId: postAuthVerifyEmail summary: Confirm an email address description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Server-to-server only: requires a **secret** key with `MEMBER_AUTH` (a publishable key gets `403 SECRET_KEY_REQUIRED`). Exchanges the token from the verification email. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Auth x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: verified: type: boolean example: verified: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: token is required' value: error: token is required code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LINK_EXPIRED: summary: 'LINK_EXPIRED: This link has expired' value: error: This link has expired code: LINK_EXPIRED INVALID_LINK: summary: 'INVALID_LINK: This link is not valid' value: error: This link is not valid code: INVALID_LINK API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SUSPENDED: summary: 'SUSPENDED: This account is suspended' value: error: This account is suspended code: SUSPENDED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: EMAIL_TAKEN: summary: 'EMAIL_TAKEN: This email is already used by another account' value: error: This email is already used by another account code: EMAIL_TAKEN '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: token: type: string required: - token example: token: eyJhbGciOi... /api/v1/communities/{communityTag}/me/verify-email/resend: post: operationId: postMeVerifyEmailResend summary: Resend the verification email description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. **Rate limit:** 3 per 15 min per key + member session. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 3 per 15 min per key + member session. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: sent: type: boolean example: sent: true '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND NO_EMAIL: summary: 'NO_EMAIL: This account has no email' value: error: This account has no email code: NO_EMAIL '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: ALREADY_VERIFIED: summary: 'ALREADY_VERIFIED: Email is already verified' value: error: Email is already verified code: ALREADY_VERIFIED '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many verification emails requested. Try again later.' value: error: Too many verification emails requested. Try again later. code: RATE_LIMITED RATE_LIMITED_2: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/tickets: get: operationId: getMeTickets summary: The member's tickets description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: when schema: type: string enum: - upcoming - past default: upcoming responses: '200': description: Success. content: application/json: schema: type: object properties: tickets: type: array items: $ref: '#/components/schemas/Ticket' example: tickets: - eventSlug: summer-meetup eventName: Summer Meetup startDate: '2026-11-20T18:00:00Z' endDate: '2026-11-20T21:00:00Z' bannerUrl: null tierId: tier_1 tierName: General status: CONFIRMED quantity: 1 saleId: sale_1 refundable: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: when must be upcoming or past' value: error: when must be upcoming or past code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/onboarding: get: operationId: getMeOnboarding summary: The member's onboarding status description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Includes the rule text, tiers and form fields needed to render each pending step. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Onboarding' example: complete: false nextStep: rules steps: rules: required: true done: false data: required: true done: false rules: - id: r1 title: Be kind description: null order: 1 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/onboarding/data: post: operationId: postMeOnboardingData summary: Submit onboarding form answers description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Answers are validated against the tier's form: unknown field ids, missing required fields, values outside a field's options, non-scalar values and strings over 10000 characters are `400 INVALID_INPUT`. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Onboarding' example: complete: false nextStep: rules steps: rules: required: true done: false data: required: true done: true rules: - id: r1 title: Be kind description: null order: 1 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: Missing required field: f_city' value: error: 'Missing required field: f_city' code: INVALID_INPUT FORM_NOT_NATIVE: summary: 'FORM_NOT_NATIVE: This tier uses an external form' value: error: This tier uses an external form code: FORM_NOT_NATIVE '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SEGMENT_NOT_FOUND: summary: 'SEGMENT_NOT_FOUND: Tier not found' value: error: Tier not found code: SEGMENT_NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: segmentId: type: string answers: type: object additionalProperties: true description: Field id to a scalar or an array of scalars. required: - segmentId - answers example: segmentId: seg_pro answers: f_city: Lisbon f_interests: - design - events /api/v1/communities/{communityTag}/me/onboarding/rules: post: operationId: postMeOnboardingRules summary: Accept the community rules description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Onboarding' example: complete: false nextStep: data steps: rules: required: true done: false data: required: true done: false rules: - id: r1 title: Be kind description: null order: 1 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NO_EMAIL: summary: 'NO_EMAIL: This account has no email' value: error: This account has no email code: NO_EMAIL '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/profile: get: operationId: getMeProfile summary: The member's profile description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: profile: $ref: '#/components/schemas/Profile' example: profile: id: usr_123 name: Alex Doe email: alex@example.com bio: null avatarUrl: null phone: null location: Lisbon locationVisibility: CIRCLE languages: - English - Português hideFromDirectory: false usertag: alex pronouns: null gender: null signature: null socials: [] birthday: null emailVisibility: CIRCLE phoneVisibility: 'OFF' isPremium: false bioMaxLength: 300 friendsCount: 4 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable patch: operationId: patchMeProfile summary: Update the member's profile description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Send any subset of the fields. Unknown keys are rejected. Long bios are truncated to the account's plan limit rather than rejected. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: profile: $ref: '#/components/schemas/Profile' example: profile: id: usr_123 name: Alex Doe email: alex@example.com bio: Designer in Lisbon. avatarUrl: null phone: null location: Lisbon locationVisibility: CIRCLE languages: - English - Português hideFromDirectory: false usertag: alex pronouns: null gender: null signature: null socials: [] birthday: null emailVisibility: CIRCLE phoneVisibility: 'OFF' isPremium: false bioMaxLength: 300 friendsCount: 4 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: Unknown field: nickname' value: error: 'Unknown field: nickname' code: INVALID_INPUT INVALID_USERTAG: summary: 'INVALID_USERTAG: Invalid usertag' value: error: Invalid usertag code: INVALID_USERTAG '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: USERTAG_TAKEN: summary: 'USERTAG_TAKEN: This usertag is taken' value: error: This usertag is taken code: USERTAG_TAKEN alternatives: - alex_7 - alex_x2 PHONE_TAKEN: summary: 'PHONE_TAKEN: This phone number is used by another account' value: error: This phone number is used by another account code: PHONE_TAKEN '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 200 bio: type: - string - 'null' maxLength: 5000 avatarUrl: type: - string - 'null' format: uri description: https only, max 2048 characters. phone: type: - string - 'null' pattern: ^\+?[0-9 ()\-.]{4,32}$ location: type: - string - 'null' maxLength: 200 locationVisibility: type: string enum: - PUBLIC - CIRCLE - 'OFF' languages: type: array maxItems: 20 items: type: string minLength: 1 maxLength: 60 description: Trimmed and de-duplicated case-insensitively. hideFromDirectory: type: boolean usertag: type: string pattern: ^[a-z0-9_-]{3,24}$ description: Lowercased before the check. pronouns: type: - string - 'null' maxLength: 50 gender: type: - string - 'null' maxLength: 50 signature: type: - string - 'null' description: Truncated to 50 characters. socials: type: - array - 'null' maxItems: 4 items: type: object properties: label: type: string maxLength: 30 url: type: string description: http(s) URLs; bare domains get https://, empty URLs are dropped. birthday: type: - object - 'null' properties: month: type: integer minimum: 1 maximum: 12 day: type: integer minimum: 1 maximum: 31 description: A real date; Feb 29 allowed. emailVisibility: type: string enum: - PUBLIC - CIRCLE - 'OFF' phoneVisibility: type: string enum: - PUBLIC - CIRCLE - 'OFF' example: bio: Designer in Lisbon. location: Lisbon languages: - English - Português hideFromDirectory: false /api/v1/communities/{communityTag}/me/profile/usertag-available: get: operationId: getMeProfileUsertagAvailable summary: Check a usertag description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. The member's own current usertag counts as available. When taken, `alternatives` are suggestions already checked as free. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: true name: usertag schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: available: type: boolean alternatives: type: array items: type: string example: available: false alternatives: - alex_2 - alex.doe '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_USERTAG: summary: 'INVALID_USERTAG: Invalid usertag' value: error: Invalid usertag code: INVALID_USERTAG '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/profile/avatar: put: operationId: putMeProfileAvatar summary: Upload the avatar description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. A png, jpeg or webp data URL, up to 5 MB decoded. The previous file is deleted. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: avatarUrl: type: string example: avatarUrl: https://storage.example.com/avatars/usr_123.png '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_IMAGE: summary: 'INVALID_IMAGE: Send a png, jpeg or webp data URL' value: error: Send a png, jpeg or webp data URL code: INVALID_IMAGE '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '413': description: Payload too large. content: application/json: schema: $ref: '#/components/schemas/Error' examples: IMAGE_TOO_LARGE: summary: 'IMAGE_TOO_LARGE: Image is over 5 MB' value: error: Image is over 5 MB code: IMAGE_TOO_LARGE '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: base64Image: type: string description: data:image/(png|jpeg|webp);base64,... required: - base64Image example: base64Image: data:image/png;base64,iVBORw0KGgo... delete: operationId: deleteMeProfileAvatar summary: Remove the avatar description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: avatarUrl: type: 'null' example: avatarUrl: null '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/preferences: get: operationId: getMePreferences summary: The member's preferences description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. `notifications` is the email preferences for this community (all true until changed). **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: preferences: $ref: '#/components/schemas/Preferences' example: preferences: locale: en timeFormat: H24 receivePromotionalContent: false notifications: eventsEmail: true postsEmail: true announcementsEmail: true '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable patch: operationId: patchMePreferences summary: Update the member's preferences description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Partial. `notifications` is merged onto the current values. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: preferences: $ref: '#/components/schemas/Preferences' example: preferences: locale: en timeFormat: H24 receivePromotionalContent: false notifications: eventsEmail: true postsEmail: false announcementsEmail: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: Unsupported locale' value: error: Unsupported locale code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: locale: type: - string - 'null' enum: - en - pt-PT - pt-BR - es - fr - de - it - nl - pl - ca - null timeFormat: type: - string - 'null' enum: - H12 - H24 - null receivePromotionalContent: type: boolean notifications: type: object properties: eventsEmail: type: boolean postsEmail: type: boolean announcementsEmail: type: boolean example: notifications: postsEmail: false /api/v1/communities/{communityTag}/me/password: post: operationId: postMePassword summary: Change the password description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Signs out every session, including the one making the request. `token` is a fresh 30-day session: store it in place of the old one so the member stays signed in on this device. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: ok: type: boolean token: type: string example: ok: true token: eyJhbGciOi... '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: WEAK_PASSWORD: summary: 'WEAK_PASSWORD: Password must be at least 10 characters' value: error: Password must be at least 10 characters code: WEAK_PASSWORD SAME_PASSWORD: summary: 'SAME_PASSWORD: The new password is the current one' value: error: The new password is the current one code: SAME_PASSWORD '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: BAD_PASSWORD: summary: 'BAD_PASSWORD: Current password is wrong' value: error: Current password is wrong code: BAD_PASSWORD SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NO_PASSWORD: summary: 'NO_PASSWORD: This account has no password; use password reset' value: error: This account has no password; use password reset code: NO_PASSWORD '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: currentPassword: type: string newPassword: type: string minLength: 10 required: - currentPassword - newPassword example: currentPassword: old-password newPassword: a-new-long-password /api/v1/communities/{communityTag}/me/export: get: operationId: getMeExport summary: Export the member's data description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. The whole account (every community), as JSON in the response body. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object additionalProperties: true example: profile: id: usr_123 name: Alex Doe '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/account: delete: operationId: deleteMeAccount summary: Delete the account description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Erases the whole account, not only this membership. Accounts with a password must send it. Accounts without one are deleted on the session alone, so show your own confirmation step first. `status` is `pending` while erasure finishes in the background. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: ok: type: boolean status: type: string enum: - done - pending example: ok: true status: done '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: BAD_PASSWORD: summary: 'BAD_PASSWORD: Password is wrong' value: error: Password is wrong code: BAD_PASSWORD SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: password: type: string example: password: current-password /api/v1/communities/{communityTag}/me/friends: get: operationId: getMeFriends summary: The member's friends description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Accepted friendships. Pass `nextCursor` back as `cursor`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: limit schema: type: integer minimum: 1 maximum: 100 default: 50 - in: query required: false name: cursor schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string name: type: string usertag: type: - string - 'null' avatarUrl: type: - string - 'null' nextCursor: type: - string - 'null' example: items: - id: usr_456 name: Sam Lee usertag: sam avatarUrl: null nextCursor: null '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: limit must be between 1 and 100' value: error: limit must be between 1 and 100 code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/notes: get: operationId: getMeNotes summary: The member's notes description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. In display order. Notes belong to the account, so every community shows the same set. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Note' example: items: - id: note_1 content: Looking for a cofounder category: LOOKING_FOR sortOrder: 0 freshSince: null createdAt: '2026-10-01T10:00:00Z' updatedAt: '2026-10-01T10:00:00Z' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable post: operationId: postMeNotes summary: Add a note description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Free accounts hold up to 2 notes. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '201': description: Success. content: application/json: schema: type: object properties: note: $ref: '#/components/schemas/Note' example: note: id: note_1 content: Looking for a cofounder category: LOOKING_FOR sortOrder: 0 freshSince: null createdAt: '2026-10-01T10:00:00Z' updatedAt: '2026-10-01T10:00:00Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: Note limit reached' value: error: Note limit reached code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: content: type: string minLength: 1 maxLength: 280 category: type: string enum: - LOOKING_FOR - OFFERING - OPEN_TO - WORKING_ON - CUSTOM default: CUSTOM required: - content example: content: Looking for a cofounder category: LOOKING_FOR /api/v1/communities/{communityTag}/me/notes/{noteId}: delete: operationId: deleteMeNotesNoteId summary: Delete a note description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Answers 204 with no body. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: noteId in: path required: true description: noteId schema: type: string responses: '204': description: Success. content: application/json: schema: type: 'null' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NOT_FOUND: summary: 'NOT_FOUND: Note not found' value: error: Note not found code: NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/directory: get: operationId: getMeDirectory summary: The members directory description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. Accepted members only: a valid session that is not an accepted member is `403 MEMBERS_ONLY`. The privacy rules of the community's members page apply: a location shows only when its visibility allows, and members who chose to hide from the directory are left out (the viewer always sees their own card). Search and filters run over visible values only. Ordered by name. `facets` are counted over the whole visible roster, not the filtered page. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: q schema: type: string description: >- Every whitespace-separated term must appear in the name, handle, role, tier names, location or languages. Case- and accent-insensitive. - in: query required: false name: tier schema: type: string description: A tier id from `facets.tiers`. - in: query required: false name: location schema: type: string description: Exact, case- and accent-insensitive. - in: query required: false name: language schema: type: string description: Exact, case- and accent-insensitive. - in: query required: false name: role schema: type: string description: Exact, case- and accent-insensitive. - in: query required: false name: cursor schema: type: string description: Opaque. Pass back `nextCursor`. - in: query required: false name: limit schema: type: integer minimum: 1 maximum: 100 default: 24 responses: '200': description: Success. content: application/json: schema: type: object properties: members: type: array items: $ref: '#/components/schemas/DirectoryMember' facets: type: object properties: tiers: type: array items: type: object properties: id: type: string name: type: string color: type: - string - 'null' count: type: integer locations: type: array items: $ref: '#/components/schemas/FacetCount' languages: type: array items: $ref: '#/components/schemas/FacetCount' roles: type: array items: $ref: '#/components/schemas/FacetCount' nextCursor: type: - string - 'null' example: members: - userId: usr_123 usertag: alex name: Alex Doe profileImage: null bio: Designer. pronouns: they/them socials: [] location: Lisbon languages: - English - Português tiers: - id: seg_pro name: Pro color: '#123456' role: member isFounder: false verified: false joinedAt: '2026-05-01T10:00:00Z' facets: tiers: - id: seg_pro name: Pro color: '#123456' count: 12 locations: - value: Lisbon count: 4 languages: - value: English count: 20 roles: - value: member count: 30 nextCursor: eyJvIjoyNH0 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: limit must be between 1 and 100' value: error: limit must be between 1 and 100 code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED MEMBERS_ONLY: summary: 'MEMBERS_ONLY: This is for members of the community' value: error: This is for members of the community code: MEMBERS_ONLY API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND PAGE_DISABLED: summary: 'PAGE_DISABLED: The members page is switched off' value: error: The members page is switched off code: PAGE_DISABLED '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/members/{usertag}: get: operationId: getMeMembersUsertag summary: A member's profile description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. `usertag` is a handle or a user id. Accepted members only, as for the directory. A member who hid from the directory still opens by handle. `hostedEvents`: the upcoming public events of this community the member hosts, soonest first, at most 20. `friendship` is the viewer's relationship; `friendRequestId` is set while a request is pending. `contact` follows each field's visibility (a missing key means hidden) and is `null` on your own profile. `notes` is `[]` outside the member's circle. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: usertag in: path required: true description: Member handle or user id. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: member: allOf: - $ref: '#/components/schemas/DirectoryMember' - type: object properties: hostedEvents: type: array items: type: object properties: slug: type: string name: type: string startDate: type: string format: date-time bannerUrl: type: - string - 'null' signature: type: - string - 'null' gender: type: - string - 'null' friendsCount: type: integer mutualFriendsCount: type: integer friendship: type: string enum: - none - friends - outgoing - incoming - self friendRequestId: type: - string - 'null' contact: type: - object - 'null' properties: inCircle: type: boolean location: type: - string - 'null' languages: type: array items: type: string emails: type: array items: type: string phone: type: string discord: type: string slack: type: string birthday: type: object properties: month: type: integer day: type: integer notes: type: array items: $ref: '#/components/schemas/Note' example: member: userId: usr_123 usertag: alex name: Alex Doe profileImage: null bio: Designer. pronouns: they/them socials: [] location: Lisbon languages: - English - Português tiers: - id: seg_pro name: Pro color: '#123456' role: member isFounder: false verified: false joinedAt: '2026-05-01T10:00:00Z' hostedEvents: - slug: summer-meetup name: Summer Meetup startDate: '2026-11-20T18:00:00Z' bannerUrl: null '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED MEMBERS_ONLY: summary: 'MEMBERS_ONLY: This is for members of the community' value: error: This is for members of the community code: MEMBERS_ONLY API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND PAGE_DISABLED: summary: 'PAGE_DISABLED: The members page is switched off' value: error: The members page is switched off code: PAGE_DISABLED MEMBER_NOT_FOUND: summary: 'MEMBER_NOT_FOUND: Member not found' value: error: Member not found code: MEMBER_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/notifications: get: operationId: getMeNotifications summary: The member's notifications description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Rows that belong to this community, plus friendship rows (friendships are platform-wide). Newest first. Pass `nextCursor` back as `cursor`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: limit schema: type: integer minimum: 1 maximum: 100 default: 20 - in: query required: false name: cursor schema: type: string - in: query required: false name: unread schema: type: string enum: - '1' - 'true' description: Unread rows only. responses: '200': description: Success. content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string type: type: string title: type: string description: Plain text. body: type: - string - 'null' createdAt: type: string format: date-time readAt: type: - string - 'null' format: date-time actor: type: - object - 'null' properties: id: type: - string - 'null' name: type: string usertag: type: - string - 'null' avatarUrl: type: - string - 'null' link: type: - object - 'null' description: >- The entity the row points at. `kind` is `member` (`usertag`), `post` (`id`), `feed_message` (`id`, `chapterId`), `community` (no fields) or `url` (`url`, from an installed app). Map it to your own pages. properties: kind: type: string enum: - member - post - feed_message - community - url usertag: type: string id: type: string chapterId: type: string url: type: string data: type: object additionalProperties: true description: The raw payload. nextCursor: type: - string - 'null' example: items: - id: ntf_1 type: FRIEND_REQUEST_INBOUND title: Sam sent you a friend request body: null createdAt: '2026-10-21T10:00:00Z' readAt: null actor: id: usr_456 name: Sam Lee usertag: sam avatarUrl: null link: kind: member usertag: sam data: {} nextCursor: null '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: Invalid cursor' value: error: Invalid cursor code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/notifications/unread-count: get: operationId: getMeNotificationsUnreadCount summary: Unread notification count description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Rows that belong to this community, plus friendship rows (friendships are platform-wide). Cheap: poll this every 30 to 60 seconds and fetch the list only when it changes. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: count: type: integer example: count: 3 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/notifications/read: post: operationId: postMeNotificationsRead summary: Mark notifications read description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Send `ids` (1-200) or `all: true`, never both. Only rows in this community's scope are marked; other ids are ignored. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: updated: type: integer example: updated: 1 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: Send ids or all' value: error: Send ids or all code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: ids: type: array minItems: 1 maxItems: 200 items: type: string all: type: boolean enum: - true example: ids: - ntf_1 /api/v1/communities/{communityTag}/me/notifications/mute-thread: post: operationId: postMeNotificationsMuteThread summary: Mute a post thread description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Reaction and comment rows for the post stop (or resume). Mentions always come through. Idempotent, and shared with the community app. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: muted: type: boolean example: muted: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: postId is required' value: error: postId is required code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: postId: type: string required: - postId example: postId: post_1 delete: operationId: deleteMeNotificationsMuteThread summary: Unmute a post thread description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Reaction and comment rows for the post stop (or resume). Mentions always come through. Idempotent, and shared with the community app. `postId` may also be sent as a query parameter. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: muted: type: boolean example: muted: false '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: postId is required' value: error: postId is required code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: postId: type: string required: - postId example: postId: post_1 /api/v1/communities/{communityTag}/me/friends/requests: get: operationId: getMeFriendsRequests summary: Pending friend requests description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Newest first. Platform-wide, not narrowed to this community. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: direction schema: type: string enum: - incoming - outgoing default: incoming responses: '200': description: Success. content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string user: type: object properties: id: type: string name: type: string usertag: type: - string - 'null' avatarUrl: type: - string - 'null' createdAt: type: string format: date-time example: items: - id: fr_1 user: id: usr_456 name: Sam Lee usertag: sam avatarUrl: null createdAt: '2026-10-21T10:00:00Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: direction must be incoming or outgoing' value: error: direction must be incoming or outgoing code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable post: operationId: postMeFriendsRequests summary: Send a friend request description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. The target must be an accepted member of this community. `accepted` when the target does not require approval. If the other person already sent a request, accept theirs instead. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '201': description: Success. content: application/json: schema: type: object properties: status: type: string enum: - pending - accepted example: status: pending '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: usertag is required' value: error: usertag is required code: INVALID_INPUT SELF_REQUEST: summary: 'SELF_REQUEST: You cannot befriend yourself' value: error: You cannot befriend yourself code: SELF_REQUEST '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: MEMBER_NOT_FOUND: summary: 'MEMBER_NOT_FOUND: Member not found' value: error: Member not found code: MEMBER_NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: ALREADY_EXISTS: summary: 'ALREADY_EXISTS: A friendship or request already exists' value: error: A friendship or request already exists code: ALREADY_EXISTS '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: usertag: type: string required: - usertag example: usertag: sam /api/v1/communities/{communityTag}/me/friends/requests/{requestId}/accept: post: operationId: postMeFriendsRequestsRequestIdAccept summary: Accept a friend request description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Receiver only. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: requestId in: path required: true description: Application (membership request) id. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: status: type: string enum: - accepted example: status: accepted '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: REQUEST_NOT_FOUND: summary: 'REQUEST_NOT_FOUND: Request not found' value: error: Request not found code: REQUEST_NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/friends/requests/{requestId}/decline: post: operationId: postMeFriendsRequestsRequestIdDecline summary: Decline a friend request description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Receiver only. Answers 204 with no body. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: requestId in: path required: true description: Application (membership request) id. schema: type: string responses: '204': description: Success. content: application/json: schema: type: 'null' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: REQUEST_NOT_FOUND: summary: 'REQUEST_NOT_FOUND: Request not found' value: error: Request not found code: REQUEST_NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/friends/requests/{requestId}: delete: operationId: deleteMeFriendsRequestsRequestId summary: Cancel an outgoing friend request description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Answers 204 with no body. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: requestId in: path required: true description: Application (membership request) id. schema: type: string responses: '204': description: Success. content: application/json: schema: type: 'null' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: REQUEST_NOT_FOUND: summary: 'REQUEST_NOT_FOUND: Request not found' value: error: Request not found code: REQUEST_NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/friends/{usertag}: delete: operationId: deleteMeFriendsUsertag summary: Unfriend description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Either side can end a friendship. Answers 204 with no body. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: usertag in: path required: true description: Member handle or user id. schema: type: string responses: '204': description: Success. content: application/json: schema: type: 'null' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: FRIENDSHIP_NOT_FOUND: summary: 'FRIENDSHIP_NOT_FOUND: Not friends' value: error: Not friends code: FRIENDSHIP_NOT_FOUND MEMBER_NOT_FOUND: summary: 'MEMBER_NOT_FOUND: Member not found' value: error: Member not found code: MEMBER_NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/members/{usertag}/events: get: operationId: getMeMembersUsertagEvents summary: A member's events description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. The member profile Events tab: for anyone but the owner, only live events in this community that the viewer may see. Same event shape as the member's own profile events. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: usertag in: path required: true description: Member handle or user id. schema: type: string responses: '200': description: Success. content: application/json: schema: type: array items: $ref: '#/components/schemas/ProfileEvent' example: - id: evt_1 slug: summer-meetup name: Summer Meetup startDate: '2026-11-20T18:00:00Z' endDate: '2026-11-20T21:00:00Z' timezone: Europe/Lisbon bannerUrl: null physicalLocation: Main Hall, Lisbon isOnline: false status: PUBLISHED catalogStatus: LIVE isDraft: false draftStep: null '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: MEMBER_NOT_FOUND: summary: 'MEMBER_NOT_FOUND: Member not found' value: error: Member not found code: MEMBER_NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/profile/events: get: operationId: getMeProfileEvents summary: The member's own profile events description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. The owner's profile Events tab: every event the member hosts, newest first, drafts and pending or declined listings included, each with `catalogStatus` and, for a draft, `isDraft: true` and the wizard `draftStep` to resume at. Only ever the caller's own rows (there is no usertag in the path). A draft owned by another community is left out. A member with no usertag gets `[]`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: array items: $ref: '#/components/schemas/ProfileEvent' example: - id: evt_1 slug: summer-meetup name: Summer Meetup startDate: '2026-11-20T18:00:00Z' endDate: '2026-11-20T21:00:00Z' timezone: Europe/Lisbon bannerUrl: null physicalLocation: Main Hall, Lisbon isOnline: false status: DRAFT catalogStatus: DRAFT isDraft: true draftStep: tickets '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/members/{usertag}/friends: get: operationId: getMeMembersUsertagFriends summary: A member's friends description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Pass `nextCursor` back as `cursor`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: usertag in: path required: true description: Member handle or user id. schema: type: string - in: query required: false name: limit schema: type: integer minimum: 1 maximum: 100 default: 24 - in: query required: false name: cursor schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string name: type: string usertag: type: - string - 'null' avatarUrl: type: - string - 'null' nextCursor: type: - string - 'null' example: items: - id: usr_456 name: Sam Lee usertag: sam avatarUrl: null nextCursor: null '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: MEMBER_NOT_FOUND: summary: 'MEMBER_NOT_FOUND: Member not found' value: error: Member not found code: MEMBER_NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/referrals: get: operationId: getMeReferrals summary: The member's referral program description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Creates the member's program link on first read when the program is on. `link` is a code: build the full URL on your own domain. A link stays `PENDING_STRIPE`, and attributes nobody, until the member connects payouts (`GET /me/stripe` `connectUrl`). Referred people are never identified. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: programEnabled: type: boolean payoutsConnected: type: boolean link: type: - object - 'null' properties: code: type: string status: type: string suggestedPath: type: string links: type: array items: type: object properties: id: type: string code: type: string kind: type: string enum: - PROGRAM - CUSTOM status: type: string label: type: - string - 'null' commissionPct: type: number durationPayments: type: - integer - 'null' joinCount: type: integer createdAt: type: string format: date-time joins: type: array items: type: object properties: id: type: string referralLinkId: type: string commissionPct: type: number durationPayments: type: - integer - 'null' paidCount: type: integer status: type: string enum: - ACTIVE - ENDED startedAt: type: string format: date-time endedAt: type: - string - 'null' format: date-time counts: type: object properties: totalJoins: type: integer activeJoins: type: integer example: programEnabled: true payoutsConnected: false link: code: k3m9x status: PENDING_STRIPE suggestedPath: /?ref=k3m9x links: [] joins: [] counts: totalJoins: 0 activeJoins: 0 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/referrals/earnings: get: operationId: getMeReferralsEarnings summary: The member's referral earnings description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Per currency, in cents. `earnedCents` is paid out; `pendingCents` is in escrow or eligible. Blocked and clawed-back rows are listed but not counted. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: totals: type: array items: type: object properties: currency: type: string earnedCents: type: integer pendingCents: type: integer nextEligibleAt: type: - string - 'null' format: date-time payments: type: integer payments: type: array items: type: object properties: id: type: string amount: type: integer description: In the smallest currency unit (cents). currency: type: string status: type: string createdAt: type: string format: date-time eligibleForPayoutAt: type: - string - 'null' format: date-time paidOut: type: boolean example: totals: - currency: EUR earnedCents: 500 pendingCents: 500 nextEligibleAt: null payments: 2 payments: [] '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/emails: get: operationId: getMeEmails summary: The member's email addresses description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Primary first, then oldest. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: emails: type: array items: type: object properties: id: type: string email: type: string isPrimary: type: boolean verified: type: boolean verifiedAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time example: emails: - id: em_1 email: alex@example.com isPrimary: false verified: false verifiedAt: null createdAt: '2026-10-21T10:00:00Z' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable post: operationId: postMeEmails summary: Add an email address description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Stored unverified. The verification link points at your site's `/verify-email?token=`; that page calls `POST /auth/verify-email`. **Rate limit:** 10 per 15 min per key + member session. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 10 per 15 min per key + member session. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '201': description: Success. content: application/json: schema: type: object properties: email: type: object properties: id: type: string email: type: string isPrimary: type: boolean verified: type: boolean verifiedAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time example: email: id: em_1 email: alex@example.com isPrimary: false verified: false verifiedAt: null createdAt: '2026-10-21T10:00:00Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_EMAIL: summary: 'INVALID_EMAIL: Invalid email' value: error: Invalid email code: INVALID_EMAIL '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: EMAIL_TAKEN: summary: 'EMAIL_TAKEN: This email is used by another account' value: error: This email is used by another account code: EMAIL_TAKEN EMAIL_ALREADY_YOURS: summary: 'EMAIL_ALREADY_YOURS: This email is already on your account' value: error: This email is already on your account code: EMAIL_ALREADY_YOURS '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED RATE_LIMITED_2: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email required: - email example: email: alex@example.com /api/v1/communities/{communityTag}/me/emails/{emailId}/resend-verification: post: operationId: postMeEmailsEmailIdResendVerification summary: Resend an email verification link description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. A fresh 24-hour link; older links stop working. **Rate limit:** 10 per 15 min per key + member session. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 10 per 15 min per key + member session. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: emailId in: path required: true description: emailId schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: sent: type: boolean example: sent: true '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: EMAIL_NOT_FOUND: summary: 'EMAIL_NOT_FOUND: Email not found' value: error: Email not found code: EMAIL_NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: ALREADY_VERIFIED: summary: 'ALREADY_VERIFIED: Email is already verified' value: error: Email is already verified code: ALREADY_VERIFIED '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED RATE_LIMITED_2: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/emails/{emailId}/make-primary: post: operationId: postMeEmailsEmailIdMakePrimary summary: Make an email primary description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: emailId in: path required: true description: emailId schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: email: type: object properties: id: type: string email: type: string isPrimary: type: boolean verified: type: boolean verifiedAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time example: email: id: em_1 email: alex@example.com isPrimary: true verified: true verifiedAt: '2026-10-21T10:05:00Z' createdAt: '2026-10-21T10:00:00Z' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: EMAIL_NOT_FOUND: summary: 'EMAIL_NOT_FOUND: Email not found' value: error: Email not found code: EMAIL_NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: EMAIL_NOT_VERIFIED: summary: 'EMAIL_NOT_VERIFIED: Verify this email first' value: error: Verify this email first code: EMAIL_NOT_VERIFIED '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/emails/{emailId}: delete: operationId: deleteMeEmailsEmailId summary: Remove an email description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: emailId in: path required: true description: emailId schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: removed: type: boolean example: removed: true '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: EMAIL_NOT_FOUND: summary: 'EMAIL_NOT_FOUND: Email not found' value: error: Email not found code: EMAIL_NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: REMOVE_PRIMARY: summary: 'REMOVE_PRIMARY: The primary email cannot be removed' value: error: The primary email cannot be removed code: REMOVE_PRIMARY '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/phone/send-otp: post: operationId: postMePhoneSendOtp summary: Send a phone verification code description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. E.164 number with a country code. Each call sends one SMS. **Rate limit:** 5 per 15 min per key + member session. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 5 per 15 min per key + member session. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: sent: type: boolean example: sent: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_PHONE: summary: 'INVALID_PHONE: Invalid phone number' value: error: Invalid phone number code: INVALID_PHONE '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED RATE_LIMITED_2: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: PHONE_UNAVAILABLE: summary: 'PHONE_UNAVAILABLE: Phone verification is unavailable' value: error: Phone verification is unavailable code: PHONE_UNAVAILABLE Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: phoneNumber: type: string required: - phoneNumber example: phoneNumber: '+351912345678' /api/v1/communities/{communityTag}/me/phone/verify: post: operationId: postMePhoneVerify summary: Verify and set the phone number description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Replaces any previous phone. There is no remove-phone route. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: phoneNumber: type: string phoneVerified: type: boolean example: phoneNumber: '+351912345678' phoneVerified: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_CODE: summary: 'INVALID_CODE: Wrong or expired code' value: error: Wrong or expired code code: INVALID_CODE INVALID_INPUT: summary: 'INVALID_INPUT: code must be 6 digits' value: error: code must be 6 digits code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: PHONE_TAKEN: summary: 'PHONE_TAKEN: This phone number is used by another account' value: error: This phone number is used by another account code: PHONE_TAKEN '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: OTP_THROTTLED: summary: 'OTP_THROTTLED: Too many attempts' value: error: Too many attempts code: OTP_THROTTLED RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: PHONE_UNAVAILABLE: summary: 'PHONE_UNAVAILABLE: Phone verification is unavailable' value: error: Phone verification is unavailable code: PHONE_UNAVAILABLE Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: phoneNumber: type: string code: type: string pattern: ^[0-9]{6}$ required: - phoneNumber - code example: phoneNumber: '+351912345678' code: '123456' /api/v1/communities/{communityTag}/me/connected-accounts: get: operationId: getMeConnectedAccounts summary: Connected sign-in accounts description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: accounts: type: array items: type: object properties: id: type: string provider: type: string enum: - google - slack - discord email: type: - string - 'null' displayName: type: - string - 'null' connectedAt: type: string format: date-time google: type: object properties: linked: type: boolean email: type: - string - 'null' connectedAt: type: - string - 'null' format: date-time example: accounts: [] google: linked: false email: null connectedAt: null '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/connected-accounts/google: delete: operationId: deleteMeConnectedAccountsGoogle summary: Disconnect Google description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Refused when Google is the account's last way to sign in. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: removed: type: boolean example: removed: true '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NOT_LINKED: summary: 'NOT_LINKED: Google is not connected' value: error: Google is not connected code: NOT_LINKED COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LAST_CREDENTIAL: summary: 'LAST_CREDENTIAL: This is your only way to sign in' value: error: This is your only way to sign in code: LAST_CREDENTIAL '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/connected-accounts/google/link: post: operationId: postMeConnectedAccountsGoogleLink summary: Start connecting Google description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Your server makes a PKCE pair and a CSRF `state`, then sends the browser to `authUrl`. Google returns to `returnUrl?code=&state=`, or `?error=IDENTITY_TAKEN` / `?error=account_suspended`. `returnUrl` must be on the community's embed site (or loopback while developing). **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: authUrl: type: string example: authUrl: https://accounts.google.com/o/oauth2/v2/auth?... '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RETURN_URL_NOT_ALLOWED: summary: 'RETURN_URL_NOT_ALLOWED: returnUrl is not allowed' value: error: returnUrl is not allowed code: RETURN_URL_NOT_ALLOWED INVALID_INPUT: summary: 'INVALID_INPUT: Invalid codeChallenge' value: error: Invalid codeChallenge code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: returnUrl: type: string format: uri codeChallenge: type: string description: PKCE S256 challenge. state: type: string required: - returnUrl - codeChallenge example: returnUrl: https://your-site.example/api/google-link/callback codeChallenge: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM state: r4nd0m /api/v1/communities/{communityTag}/me/connected-accounts/google/confirm: post: operationId: postMeConnectedAccountsGoogleConfirm summary: Finish connecting Google description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Call with the SAME session that started the link. The code is single-use and expires in 60 seconds. Every code failure is `400 INVALID_CODE`. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: google: type: object properties: linked: type: boolean email: type: - string - 'null' example: google: linked: true email: alex@gmail.com '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_CODE: summary: 'INVALID_CODE: Invalid or expired code' value: error: Invalid or expired code code: INVALID_CODE '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: IDENTITY_TAKEN: summary: 'IDENTITY_TAKEN: This Google account belongs to another account' value: error: This Google account belongs to another account code: IDENTITY_TAKEN '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: code: type: string codeVerifier: type: string required: - code - codeVerifier example: code: one-time-code codeVerifier: the-pkce-verifier /api/v1/communities/{communityTag}/me/seller-vat: get: operationId: getMeSellerVat summary: The member's seller VAT details description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: vatRegistered: type: boolean vatCountry: type: - string - 'null' vatNumber: type: - string - 'null' example: vatRegistered: true vatCountry: PT vatNumber: PT123456789 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable put: operationId: putMeSellerVat summary: Update the member's seller VAT details description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Country is ISO-2 (uppercased); the number is normalised (spaces stripped, uppercased). `vatRegistered: false` clears both. A country needs a number. No VIES check. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: vatRegistered: type: boolean vatCountry: type: - string - 'null' vatNumber: type: - string - 'null' example: vatRegistered: true vatCountry: PT vatNumber: PT123456789 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_VAT_COUNTRY: summary: 'INVALID_VAT_COUNTRY: Invalid country' value: error: Invalid country code: INVALID_VAT_COUNTRY VAT_NUMBER_REQUIRED: summary: 'VAT_NUMBER_REQUIRED: A VAT number is required' value: error: A VAT number is required code: VAT_NUMBER_REQUIRED INVALID_INPUT: summary: 'INVALID_INPUT: Unknown field' value: error: Unknown field code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED NOT_MEMBER: summary: 'NOT_MEMBER: You are not a member of this community' value: error: You are not a member of this community code: NOT_MEMBER API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: vatRegistered: type: boolean vatCountry: type: - string - 'null' vatNumber: type: - string - 'null' example: vatRegistered: true vatCountry: pt vatNumber: PT 123 456 789 /api/v1/communities/{communityTag}/me/segments/{segmentId}/apply: post: operationId: postMeSegmentsSegmentIdApply summary: Apply to (or join) a membership tier description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. A live session is required but membership is not (the person is applying). The applicant email is always the account email. Outcomes: `JOINED` (open tier, joined now), `PENDING` (awaiting review) or `PAYMENT_REQUIRED` (continue with `POST /me/applications/{requestId}/checkout`). **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: segmentId in: path required: true description: Membership tier id. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: status: type: string enum: - JOINED segmentId: type: string requestId: type: - string - 'null' example: status: JOINED segmentId: seg_free requestId: null '201': description: Application recorded (pending review or payment). content: application/json: schema: type: object properties: status: type: string enum: - PENDING - PAYMENT_REQUIRED segmentId: type: string requestId: type: string reservation: type: boolean example: status: PAYMENT_REQUIRED segmentId: seg_pro requestId: req_123 reservation: false '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: answers must be an object' value: error: answers must be an object code: INVALID_INPUT NO_EMAIL: summary: 'NO_EMAIL: This account has no email' value: error: This account has no email code: NO_EMAIL NOT_OPEN: summary: 'NOT_OPEN: This tier is not open' value: error: This tier is not open code: NOT_OPEN JOIN_FAILED: summary: 'JOIN_FAILED: Could not join this tier' value: error: Could not join this tier code: JOIN_FAILED '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED BANNED: summary: 'BANNED: You cannot join this community' value: error: You cannot join this community code: BANNED INVITE_ONLY: summary: 'INVITE_ONLY: This tier is invite-only' value: error: This tier is invite-only code: INVITE_ONLY API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND SEGMENT_NOT_FOUND: summary: 'SEGMENT_NOT_FOUND: Tier not found' value: error: Tier not found code: SEGMENT_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: APPLICATION_PENDING: summary: 'APPLICATION_PENDING: You already have a pending application' value: error: You already have a pending application code: APPLICATION_PENDING ALREADY_MEMBER: summary: 'ALREADY_MEMBER: Already a member; use /me/membership/checkout to change paid tier' value: error: Already a member; use /me/membership/checkout to change paid tier code: ALREADY_MEMBER '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: answers: type: object additionalProperties: true default: {} billingCycle: type: string currency: type: string minLength: 3 maxLength: 3 source: type: string enum: - embed_site - event_join_upsell default: embed_site description: Where the application came from. Send `event_join_upsell` from the Join to Save flow. referralCode: type: string description: 'The visitor''s `?ref` code. Best effort: an unknown code never fails the apply.' example: answers: f_why: I love the events billingCycle: MONTHLY currency: EUR /api/v1/communities/{communityTag}/me/applications: get: operationId: getMeApplications summary: The person's applications description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. Newest first. Membership is not required. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: applications: type: array items: $ref: '#/components/schemas/Application' example: applications: - requestId: req_123 segmentId: seg_pro segmentName: Pro status: PAYMENT_PENDING submittedAt: '2026-10-01T10:00:00Z' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/applications/{requestId}/checkout: post: operationId: postMeApplicationsRequestIdCheckout summary: Pay for an application description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. For an application in `PAYMENT_PENDING`. Membership is not required. Return URLs must be https on your site's registered origin. **Rate limit:** 100 requests per 15 min per client IP, plus the per-key ceilings. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 100 requests per 15 min per client IP, plus the per-key ceilings. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: requestId in: path required: true description: Application (membership request) id. schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/CheckoutRedirect' example: checkoutUrl: https://checkout.stripe.com/c/pay/cs_test_123 sessionId: cs_test_123 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_RETURN_URL: summary: 'INVALID_RETURN_URL: successUrl and cancelUrl must be https URLs on your site' value: error: successUrl and cancelUrl must be https URLs on your site code: INVALID_RETURN_URL NO_PRICE: summary: 'NO_PRICE: This tier has no price' value: error: This tier has no price code: NO_PRICE '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_KEY_REQUIRED: summary: 'API_KEY_REQUIRED: API key required' value: error: API key required code: API_KEY_REQUIRED INVALID_API_KEY: summary: 'INVALID_API_KEY: Invalid API key' value: error: Invalid API key code: INVALID_API_KEY INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing or not valid' value: error: Session is missing or not valid code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED MISSING_SCOPE: summary: 'MISSING_SCOPE: API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' code: MISSING_SCOPE WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY BANNED: summary: 'BANNED: You cannot join this community' value: error: You cannot join this community code: BANNED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND APPLICATION_NOT_FOUND: summary: 'APPLICATION_NOT_FOUND: Application not found' value: error: Application not found code: APPLICATION_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NOT_AWAITING_PAYMENT: summary: 'NOT_AWAITING_PAYMENT: This application is not awaiting payment' value: error: This application is not awaiting payment code: NOT_AWAITING_PAYMENT COMMUNITY_NOT_LIVE: summary: 'COMMUNITY_NOT_LIVE: This community is not accepting payments yet' value: error: This community is not accepting payments yet code: COMMUNITY_NOT_LIVE '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: successUrl: type: string format: uri cancelUrl: type: string format: uri required: - successUrl - cancelUrl example: successUrl: https://example.com/welcome cancelUrl: https://example.com/join /api/v1/communities/{communityTag}/me/reminder-preferences: get: operationId: getMeReminderPreferences summary: Event reminder preferences description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: emailReminders: type: boolean example: emailReminders: true '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing or expired' value: error: Session is missing or expired code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable patch: operationId: patchMeReminderPreferences summary: Update event reminder preferences description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: emailReminders: type: boolean example: emailReminders: false '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: emailReminders must be a boolean' value: error: emailReminders must be a boolean code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing or expired' value: error: Session is missing or expired code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: emailReminders: type: boolean required: - emailReminders example: emailReminders: false /api/v1/communities/{communityTag}/me/membership: get: operationId: getMeMembership summary: The member's paid membership description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. `membership` is null when there is none. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: membership: $ref: '#/components/schemas/Membership' example: membership: segmentId: seg_pro segmentName: Pro status: ACTIVE billingCycle: MONTHLY currentPeriodEnd: '2026-11-13T00:00:00Z' cancelAtPeriodEnd: false '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_KEY_REQUIRED: summary: 'API_KEY_REQUIRED: API key required' value: error: API key required code: API_KEY_REQUIRED INVALID_API_KEY: summary: 'INVALID_API_KEY: Invalid API key' value: error: Invalid API key code: INVALID_API_KEY INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing or not valid' value: error: Session is missing or not valid code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED MISSING_SCOPE: summary: 'MISSING_SCOPE: API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' code: MISSING_SCOPE WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/membership/checkout: post: operationId: postMeMembershipCheckout summary: Start a paid membership checkout description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Return URLs must be https on your site's registered origin. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/CheckoutRedirect' example: checkoutUrl: https://checkout.stripe.com/c/pay/cs_test_123 sessionId: cs_test_123 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: segmentId is required' value: error: segmentId is required code: INVALID_INPUT INVALID_RETURN_URL: summary: 'INVALID_RETURN_URL: Return URLs must be https on your site' value: error: Return URLs must be https on your site code: INVALID_RETURN_URL NOT_A_PAID_TIER: summary: 'NOT_A_PAID_TIER: This tier is free' value: error: This tier is free code: NOT_A_PAID_TIER CYCLE_NOT_OFFERED: summary: 'CYCLE_NOT_OFFERED: This billing cycle is not offered' value: error: This billing cycle is not offered code: CYCLE_NOT_OFFERED '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_KEY_REQUIRED: summary: 'API_KEY_REQUIRED: API key required' value: error: API key required code: API_KEY_REQUIRED INVALID_API_KEY: summary: 'INVALID_API_KEY: Invalid API key' value: error: Invalid API key code: INVALID_API_KEY INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing or not valid' value: error: Session is missing or not valid code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED MISSING_SCOPE: summary: 'MISSING_SCOPE: API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' code: MISSING_SCOPE WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY BANNED: summary: 'BANNED: You cannot join this community' value: error: You cannot join this community code: BANNED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND SEGMENT_NOT_FOUND: summary: 'SEGMENT_NOT_FOUND: Tier not found' value: error: Tier not found code: SEGMENT_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: ALREADY_SUBSCRIBED: summary: 'ALREADY_SUBSCRIBED: Already subscribed to this tier' value: error: Already subscribed to this tier code: ALREADY_SUBSCRIBED COMMUNITY_NOT_LIVE: summary: 'COMMUNITY_NOT_LIVE: This community is not accepting payments yet' value: error: This community is not accepting payments yet code: COMMUNITY_NOT_LIVE '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: segmentId: type: string billingCycle: type: string description: A recurring cadence the tier offers (for example MONTHLY, YEARLY) or ONE_TIME. successUrl: type: string format: uri cancelUrl: type: string format: uri required: - segmentId - billingCycle - successUrl - cancelUrl example: segmentId: seg_pro billingCycle: MONTHLY successUrl: https://example.com/thanks cancelUrl: https://example.com/plans /api/v1/communities/{communityTag}/me/membership/change-tier: post: operationId: postMeMembershipChangeTier summary: Change to another tier description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Moves a live subscription to another tier. `CHECKOUT_REQUIRED` (free to paid, or a cycle or currency change) returns a checkout; the current subscription stays active until that payment succeeds, then is replaced. `CHANGED` (same cycle, higher paid tier) is prorated and immediate. `SCHEDULED` (same cycle, lower tier) takes effect at the next renewal. Return URLs must be https on your site's registered origin; query strings are fine. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: oneOf: - type: object properties: status: type: string enum: - CHECKOUT_REQUIRED checkoutUrl: type: string format: uri sessionId: type: string - type: object properties: status: type: string enum: - CHANGED - SCHEDULED membership: $ref: '#/components/schemas/Membership' example: status: CHECKOUT_REQUIRED checkoutUrl: https://checkout.stripe.com/c/pay/cs_test_123 sessionId: cs_test_123 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: segmentId and billingCycle are required' value: error: segmentId and billingCycle are required code: INVALID_INPUT INVALID_RETURN_URL: summary: 'INVALID_RETURN_URL: Return URLs must be https on your site' value: error: Return URLs must be https on your site code: INVALID_RETURN_URL CYCLE_NOT_OFFERED: summary: 'CYCLE_NOT_OFFERED: This billing cycle is not offered' value: error: This billing cycle is not offered code: CYCLE_NOT_OFFERED '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_KEY_REQUIRED: summary: 'API_KEY_REQUIRED: API key required' value: error: API key required code: API_KEY_REQUIRED INVALID_API_KEY: summary: 'INVALID_API_KEY: Invalid API key' value: error: Invalid API key code: INVALID_API_KEY INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing or not valid' value: error: Session is missing or not valid code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED MISSING_SCOPE: summary: 'MISSING_SCOPE: API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' code: MISSING_SCOPE WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY BANNED: summary: 'BANNED: You cannot join this community' value: error: You cannot join this community code: BANNED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND SEGMENT_NOT_FOUND: summary: 'SEGMENT_NOT_FOUND: Tier not found' value: error: Tier not found code: SEGMENT_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NO_LIVE_MEMBERSHIP: summary: 'NO_LIVE_MEMBERSHIP: No live subscription; use /me/membership/checkout' value: error: No live subscription; use /me/membership/checkout code: NO_LIVE_MEMBERSHIP ALREADY_ON_TIER: summary: 'ALREADY_ON_TIER: Already on this tier' value: error: Already on this tier code: ALREADY_ON_TIER COMMUNITY_NOT_LIVE: summary: 'COMMUNITY_NOT_LIVE: This community is not accepting payments yet' value: error: This community is not accepting payments yet code: COMMUNITY_NOT_LIVE '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: segmentId: type: string billingCycle: type: string description: A recurring cadence the tier offers (for example MONTHLY, YEARLY) or ONE_TIME. successUrl: type: string format: uri cancelUrl: type: string format: uri required: - segmentId - billingCycle - successUrl - cancelUrl example: segmentId: seg_circle billingCycle: MONTHLY successUrl: https://example.com/events/supper?jts=tier_1 cancelUrl: https://example.com/plans /api/v1/communities/{communityTag}/me/membership/cancel: post: operationId: postMeMembershipCancel summary: Cancel at period end description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. The membership stays active until `currentPeriodEnd`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: membership: $ref: '#/components/schemas/Membership' example: membership: segmentId: seg_pro segmentName: Pro status: ACTIVE billingCycle: MONTHLY currentPeriodEnd: '2026-11-13T00:00:00Z' cancelAtPeriodEnd: true '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_KEY_REQUIRED: summary: 'API_KEY_REQUIRED: API key required' value: error: API key required code: API_KEY_REQUIRED INVALID_API_KEY: summary: 'INVALID_API_KEY: Invalid API key' value: error: Invalid API key code: INVALID_API_KEY INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing or not valid' value: error: Session is missing or not valid code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED MISSING_SCOPE: summary: 'MISSING_SCOPE: API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' code: MISSING_SCOPE WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND NO_MEMBERSHIP: summary: 'NO_MEMBERSHIP: No membership' value: error: No membership code: NO_MEMBERSHIP '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: ALREADY_CANCELLED: summary: 'ALREADY_CANCELLED: Already cancelled' value: error: Already cancelled code: ALREADY_CANCELLED '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/membership/reactivate: post: operationId: postMeMembershipReactivate summary: Undo a pending cancellation description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: membership: $ref: '#/components/schemas/Membership' example: membership: segmentId: seg_pro segmentName: Pro status: ACTIVE billingCycle: MONTHLY currentPeriodEnd: '2026-11-13T00:00:00Z' cancelAtPeriodEnd: false '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_KEY_REQUIRED: summary: 'API_KEY_REQUIRED: API key required' value: error: API key required code: API_KEY_REQUIRED INVALID_API_KEY: summary: 'INVALID_API_KEY: Invalid API key' value: error: Invalid API key code: INVALID_API_KEY INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing or not valid' value: error: Session is missing or not valid code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED MISSING_SCOPE: summary: 'MISSING_SCOPE: API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' code: MISSING_SCOPE WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND NO_MEMBERSHIP: summary: 'NO_MEMBERSHIP: No membership' value: error: No membership code: NO_MEMBERSHIP '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NOT_PENDING_CANCELLATION: summary: 'NOT_PENDING_CANCELLATION: Membership is not pending cancellation' value: error: Membership is not pending cancellation code: NOT_PENDING_CANCELLATION '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/membership/billing-portal: post: operationId: postMeMembershipBillingPortal summary: Open the billing portal description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Returns a short-lived URL where the member manages payment methods and invoices. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: url: type: string format: uri example: url: https://billing.stripe.com/p/session/test_123 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_RETURN_URL: summary: 'INVALID_RETURN_URL: returnUrl must be https on your site' value: error: returnUrl must be https on your site code: INVALID_RETURN_URL '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_KEY_REQUIRED: summary: 'API_KEY_REQUIRED: API key required' value: error: API key required code: API_KEY_REQUIRED INVALID_API_KEY: summary: 'INVALID_API_KEY: Invalid API key' value: error: Invalid API key code: INVALID_API_KEY INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing or not valid' value: error: Session is missing or not valid code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED MISSING_SCOPE: summary: 'MISSING_SCOPE: API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' code: MISSING_SCOPE WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND NO_MEMBERSHIP: summary: 'NO_MEMBERSHIP: No membership' value: error: No membership code: NO_MEMBERSHIP '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NO_STRIPE_CUSTOMER: summary: 'NO_STRIPE_CUSTOMER: No billing account yet' value: error: No billing account yet code: NO_STRIPE_CUSTOMER '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: returnUrl: type: string format: uri required: - returnUrl example: returnUrl: https://example.com/account /api/v1/communities/{communityTag}/me/sales/{saleId}/refund-eligibility: get: operationId: getMeSalesSaleIdRefundEligibility summary: Can this purchase be refunded description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Only the member's own purchases in this community; anything else is `404`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: saleId in: path required: true description: Sale id. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: eligible: type: boolean reason: type: - string - 'null' windowEndsAt: type: - string - 'null' format: date-time example: eligible: true reason: null windowEndsAt: '2026-11-13T18:00:00Z' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_KEY_REQUIRED: summary: 'API_KEY_REQUIRED: API key required' value: error: API key required code: API_KEY_REQUIRED INVALID_API_KEY: summary: 'INVALID_API_KEY: Invalid API key' value: error: Invalid API key code: INVALID_API_KEY INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing or not valid' value: error: Session is missing or not valid code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED MISSING_SCOPE: summary: 'MISSING_SCOPE: API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' code: MISSING_SCOPE WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND SALE_NOT_FOUND: summary: 'SALE_NOT_FOUND: Sale not found' value: error: Sale not found code: SALE_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/events: get: operationId: getEvents summary: List events description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Optionally identify a member with `X-Cobuntu-Auth-Token` (or `X-Cobuntu-Member-Token`) to get member prices and attendance state; an invalid token silently falls back to anonymous. Cursor-paginated. Every filter is applied before paging, so each page is full. Invalid parameters are `400 INVALID_INPUT` with the offending `field`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Events x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: upcoming schema: type: boolean description: Not ended. Cannot be combined with `past`. - in: query required: false name: past schema: type: boolean description: Ended. Sorted newest first. - in: query required: false name: q schema: type: string maxLength: 200 description: >- Every whitespace-separated term must appear (case- and accent-insensitive) in the name, description text, location, tag names or host name. - in: query required: false name: from schema: type: string description: ISO 8601 date or date-time. Events overlapping `[from, to]`. Undated events never match. - in: query required: false name: to schema: type: string description: >- ISO 8601 date or date-time. A bare date means the end of that day (UTC), so `from=to=YYYY-MM-DD` is one calendar day. - in: query required: false name: featured schema: type: boolean description: '`true` returns only the featured event; `false` applies no filter.' - in: query required: false name: category schema: type: string description: Category id. An unknown id returns an empty page. - in: query required: false name: subcategory schema: type: string description: Sub-category id. - in: query required: false name: sort schema: type: string enum: - soonest - name default: soonest description: '`soonest`: start date ascending (descending with `past=true`). `name`: name ascending.' - in: query required: false name: price schema: type: string enum: - free - paid description: '`paid`: any live tier has a price above 0. `free`: otherwise, including events with no tiers.' - in: query required: false name: format schema: type: string enum: - in_person - online - hybrid description: 'Inclusive: `in_person` and `online` both include hybrid events; `hybrid` is hybrid only.' - in: query required: false name: limit schema: type: integer minimum: 1 maximum: 100 default: 20 - in: query required: false name: cursor schema: type: string description: The `nextCursor` of the previous page, with the same `sort`. A cursor from the other sort is `400`. responses: '200': description: Success. content: application/json: schema: type: object properties: events: type: array items: $ref: '#/components/schemas/Event' hasMore: type: boolean nextCursor: type: - string - 'null' example: events: - id: evt_123 slug: summer-meetup createdAt: '2026-05-01T10:00:00Z' name: Summer Meetup description: An evening with the community. bannerUrl: https://example.com/banner.jpg cardImageUrl: null startDate: '2026-11-20T18:00:00Z' endDate: '2026-11-20T21:00:00Z' timezone: Europe/Lisbon physicalLocation: Main Hall, Lisbon locationFormat: PHYSICAL viewability: PUBLIC requiresApproval: false featured: true tiers: - id: tier_1 name: General price: 1500 currency: EUR capacity: 100 remaining: 42 soldOut: false hasForm: true isOnSale: true memberPrice: null publicMemberOffers: - segmentName: Members price: 1000 mode: FIXED_PRICE attendeeCount: 58 isAttending: false categoryId: cat_workshops subCategoryId: null category: id: cat_workshops name: Workshops subcategory: null hasMore: false nextCursor: null '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: CONFLICTING_DATE_FILTERS: summary: 'CONFLICTING_DATE_FILTERS: upcoming=true and past=true cannot be combined' value: error: upcoming=true and past=true cannot be combined code: CONFLICTING_DATE_FILTERS INVALID_INPUT: summary: 'INVALID_INPUT: from must be before to' value: error: from must be before to code: INVALID_INPUT field: from '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Community_not_found: summary: Community not found value: error: Community not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/events/facets: get: operationId: getEventsFacets summary: Event filter counts description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Optionally identify a member with `X-Cobuntu-Auth-Token` (or `X-Cobuntu-Member-Token`) to get member prices and attendance state; an invalid token silently falls back to anonymous. Counts for building filters, over the same visible set as the list. Not narrowed by category, sub-category, price or format: those are the counted dimensions, and each count equals what that filter returns. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Events x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: upcoming schema: type: boolean description: Not ended. Cannot be combined with `past`. - in: query required: false name: past schema: type: boolean description: Ended. Sorted newest first. - in: query required: false name: q schema: type: string maxLength: 200 description: >- Every whitespace-separated term must appear (case- and accent-insensitive) in the name, description text, location, tag names or host name. - in: query required: false name: from schema: type: string description: ISO 8601 date or date-time. Events overlapping `[from, to]`. Undated events never match. - in: query required: false name: to schema: type: string description: >- ISO 8601 date or date-time. A bare date means the end of that day (UTC), so `from=to=YYYY-MM-DD` is one calendar day. - in: query required: false name: featured schema: type: boolean description: '`true` returns only the featured event; `false` applies no filter.' responses: '200': description: Success. content: application/json: schema: type: object properties: facets: $ref: '#/components/schemas/EventFacets' example: facets: total: 4 categories: - id: cat_workshops name: Workshops count: 2 subcategories: - id: sub_pottery name: Pottery count: 1 uncategorized: 1 price: free: 2 paid: 2 format: in_person: 2 online: 2 hybrid: 1 tba: 1 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: CONFLICTING_DATE_FILTERS: summary: 'CONFLICTING_DATE_FILTERS: upcoming=true and past=true cannot be combined' value: error: upcoming=true and past=true cannot be combined code: CONFLICTING_DATE_FILTERS INVALID_INPUT: summary: 'INVALID_INPUT: from must be before to' value: error: from must be before to code: INVALID_INPUT field: from '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Community_not_found: summary: Community not found value: error: Community not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/events/{idOrSlug}: get: operationId: getEventsIdOrSlug summary: Get an event description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Optionally identify a member with `X-Cobuntu-Auth-Token` (or `X-Cobuntu-Member-Token`) to get member prices and attendance state; an invalid token silently falls back to anonymous. Accepts the event id or slug. Adds `eventChat` and `refundPolicy` to the list shape. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Events x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSlug in: path required: true description: Event id or slug. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: event: $ref: '#/components/schemas/Event' example: event: id: evt_123 slug: summer-meetup createdAt: '2026-05-01T10:00:00Z' name: Summer Meetup description: An evening with the community. bannerUrl: https://example.com/banner.jpg cardImageUrl: null startDate: '2026-11-20T18:00:00Z' endDate: '2026-11-20T21:00:00Z' timezone: Europe/Lisbon physicalLocation: Main Hall, Lisbon locationFormat: PHYSICAL viewability: PUBLIC requiresApproval: false featured: true tiers: - id: tier_1 name: General price: 1500 currency: EUR capacity: 100 remaining: 42 soldOut: false hasForm: true isOnSale: true memberPrice: null publicMemberOffers: - segmentName: Members price: 1000 mode: FIXED_PRICE attendeeCount: 58 isAttending: false categoryId: cat_workshops subCategoryId: null category: id: cat_workshops name: Workshops subcategory: null '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: MEMBERS_ONLY: summary: 'MEMBERS_ONLY: This event is for community members only' value: error: This event is for community members only code: MEMBERS_ONLY API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Event_not_found: summary: Event not found value: error: Event not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable patch: operationId: patchEventsIdOrSlug summary: Update an event by id description: >- **Required scope:** `WRITE_EVENTS` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Pass the event **id** in the path. Send any subset of the fields. Events that are live or have ended cannot be edited. Dates are ISO 8601; `startDate` must be before `endDate`; `timezone` is an IANA name. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Events x-required-scope: WRITE_EVENTS x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSlug in: path required: true description: Event id or slug. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object additionalProperties: true example: id: evt_123 name: Summer Meetup (moved) '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: No_editable_fields_in_request_body: summary: No editable fields in request body value: error: No editable fields in request body startDate_must_be_before_endDate: summary: startDate must be before endDate value: error: startDate must be before endDate '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_EVENTS: summary: 'API key missing required scope: WRITE_EVENTS' value: error: 'API key missing required scope: WRITE_EVENTS' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Event_not_found: summary: Event not found value: error: Event not found Community_not_found: summary: Community not found value: error: Community not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EventWrite' example: name: Summer Meetup (moved) startDate: '2026-11-21T18:00:00Z' endDate: '2026-11-21T21:00:00Z' /api/v1/communities/{communityTag}/events/{idOrSlug}/tiers: get: operationId: getEventsIdOrSlugTiers summary: List an event's tiers description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Optionally identify a member with `X-Cobuntu-Auth-Token` (or `X-Cobuntu-Member-Token`) to get member prices and attendance state; an invalid token silently falls back to anonymous. Members-only events return `404`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Events x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSlug in: path required: true description: Event id or slug. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: tiers: type: array items: $ref: '#/components/schemas/Tier' example: tiers: - id: tier_1 name: General price: 1500 currency: EUR capacity: 100 remaining: 42 soldOut: false hasForm: true isOnSale: true memberPrice: null publicMemberOffers: - segmentName: Members price: 1000 mode: FIXED_PRICE '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Event_not_found: summary: Event not found value: error: Event not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/tiers/{tierId}/form: get: operationId: getTiersTierIdForm summary: A tier's registration form description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Render these fields before RSVP or checkout, then send the answers as `formAnswers`. `form` is null when the tier has none. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Events x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: tierId in: path required: true description: Ticket tier id. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: form: type: - object - 'null' additionalProperties: true example: form: fields: - id: f_diet type: select label: Dietary needs required: true options: - id: none label: None - id: veg label: Vegetarian '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Tier_not_found: summary: Tier not found value: error: Tier not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/tiers/{tierId}/member-pricing/preview: get: operationId: getTiersTierIdMemberPricingPreview summary: Member pricing preview description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. The "join to save" preview for an event tier or a product variant tier: list price, member offers and the best offer for the viewer. Pass `X-Cobuntu-Auth-Token` to evaluate for a signed-in viewer. `joinMode` says how to get an offer: `free` (join now), `paid` (buy the membership first; `membership` has its prices and `joinPath` the call that fits this viewer), `apply` (link to your apply page, no price promise) or null (never offered). After a paid join, poll with the session until `buyerOverride` is set before starting checkout. Amounts in cents. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Events x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: tierId in: path required: true description: Ticket tier id. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: listPrice: type: integer description: In the smallest currency unit (cents). currency: type: string overrides: type: array items: type: object properties: segmentName: type: string finalPrice: type: integer description: In the smallest currency unit (cents). saving: type: integer description: In the smallest currency unit (cents). joinable: type: boolean segmentId: type: string joinMode: type: - string - 'null' enum: - free - paid - apply - null membership: type: - object - 'null' description: Paid offers only. properties: currency: type: string prices: type: array items: type: object properties: billingCycle: type: string amount: type: - integer - 'null' description: Cents. null for an installment-only cadence. installment: type: - object - 'null' properties: totalPrice: type: integer description: In the smallest currency unit (cents). count: type: integer intervalMonths: type: integer trial: type: 'null' joinPath: type: - string - 'null' enum: - apply - checkout - changeTier - null description: Paid offers only. Anonymous viewers always get apply. buyerOverride: type: - object - 'null' viewerHasRoleAccess: type: boolean bestOffer: type: - object - 'null' properties: segmentName: type: string finalPrice: type: integer description: In the smallest currency unit (cents). saving: type: integer description: In the smallest currency unit (cents). joinable: type: boolean segmentId: type: string joinMode: type: - string - 'null' enum: - free - paid - apply - null membership: type: - object - 'null' description: Paid offers only. properties: currency: type: string prices: type: array items: type: object properties: billingCycle: type: string amount: type: - integer - 'null' description: Cents. null for an installment-only cadence. installment: type: - object - 'null' properties: totalPrice: type: integer description: In the smallest currency unit (cents). count: type: integer intervalMonths: type: integer trial: type: 'null' joinPath: type: - string - 'null' enum: - apply - checkout - changeTier - null description: Paid offers only. Anonymous viewers always get apply. example: listPrice: 1500 currency: EUR overrides: [] buyerOverride: null viewerHasRoleAccess: false bestOffer: segmentName: Members finalPrice: 1000 saving: 500 joinable: true segmentId: seg_free '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: TIER_UNPRICED: summary: 'TIER_UNPRICED: This tier has no price' value: error: This tier has no price code: TIER_UNPRICED '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: TIER_NOT_FOUND: summary: 'TIER_NOT_FOUND: Tier not found' value: error: Tier not found code: TIER_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/events/{idOrSlug}/rsvp: post: operationId: postEventsIdOrSlugRsvp summary: RSVP to a free event description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Free tiers only (paid tiers: use checkout). Either one place (`tierId`, `formAnswers`) or several places with `items[]` (max 10 places in total; per-ticket answers go inside `items[].attendees[]`). An optional `donation` turns the RSVP into a Stripe checkout and requires `successUrl`/`cancelUrl`. Identify a member with `X-Cobuntu-Member-Token`. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Events x-required-scope: WRITE_SALES x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: optional security: - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSlug in: path required: true description: Event id or slug. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: attendanceId: type: string status: type: string alreadyRegistered: type: boolean places: type: array items: type: object properties: attendanceId: type: string tierId: type: string status: type: string companion: type: boolean attendeeName: type: - string - 'null' attendeeEmail: type: - string - 'null' checkoutUrl: type: string description: Only when a donation was sent. sessionId: type: string example: attendanceId: att_1 status: CONFIRMED alreadyRegistered: false '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: EMAIL_REQUIRED: summary: 'EMAIL_REQUIRED: email is required' value: error: email is required code: EMAIL_REQUIRED INVALID_DONATION_AMOUNT: summary: 'INVALID_DONATION_AMOUNT: donation.amount must be a positive integer (smallest unit)' value: error: donation.amount must be a positive integer (smallest unit) code: INVALID_DONATION_AMOUNT DONATION_REQUIRES_REDIRECT_URLS: summary: >- DONATION_REQUIRES_REDIRECT_URLS: successUrl and cancelUrl are required (absolute URLs) when sending a donation value: error: successUrl and cancelUrl are required (absolute URLs) when sending a donation code: DONATION_REQUIRES_REDIRECT_URLS NO_TIERS: summary: 'NO_TIERS: Event has no tiers' value: error: Event has no tiers code: NO_TIERS PAID_TIER_REQUIRES_CHECKOUT: summary: 'PAID_TIER_REQUIRES_CHECKOUT: This event has a paid tier. Use /checkout instead of /rsvp.' value: error: This event has a paid tier. Use /checkout instead of /rsvp. code: PAID_TIER_REQUIRES_CHECKOUT FORM_ANSWERS_REQUIRED: summary: 'FORM_ANSWERS_REQUIRED: Required form answers are missing' value: error: Required form answers are missing code: FORM_ANSWERS_REQUIRED missingFields: - f_diet AMBIGUOUS_BODY: summary: 'AMBIGUOUS_BODY: Send either tierId (one place) or items[], not both' value: error: Send either tierId (one place) or items[], not both code: AMBIGUOUS_BODY DONATION_NOT_SUPPORTED_WITH_ITEMS: summary: >- DONATION_NOT_SUPPORTED_WITH_ITEMS: A donation rides on /checkout with items[], not on a multi-ticket RSVP value: error: A donation rides on /checkout with items[], not on a multi-ticket RSVP code: DONATION_NOT_SUPPORTED_WITH_ITEMS INVALID_ITEMS: summary: 'INVALID_ITEMS: items must be a non-empty array' value: error: items must be a non-empty array code: INVALID_ITEMS DUPLICATE_TIER: summary: 'DUPLICATE_TIER: Each tier may appear once in items' value: error: Each tier may appear once in items code: DUPLICATE_TIER INVALID_QUANTITY: summary: 'INVALID_QUANTITY: quantity must be a positive integer' value: error: quantity must be a positive integer code: INVALID_QUANTITY INVALID_ATTENDEES: summary: 'INVALID_ATTENDEES: attendees must match quantity' value: error: attendees must match quantity code: INVALID_ATTENDEES TOO_MANY_TICKETS: summary: 'TOO_MANY_TICKETS: At most 10 places per order' value: error: At most 10 places per order code: TOO_MANY_TICKETS max: 10 CUSTOM_AMOUNT_NOT_ACCEPTED: summary: 'CUSTOM_AMOUNT_NOT_ACCEPTED: This ticket has a fixed price' value: error: This ticket has a fixed price code: CUSTOM_AMOUNT_NOT_ACCEPTED '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: MEMBERS_ONLY: summary: 'MEMBERS_ONLY: Members only' value: error: Members only code: MEMBERS_ONLY API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Event_not_found: summary: Event not found value: error: Event not found TIER_NOT_FOUND: summary: 'TIER_NOT_FOUND: Tier not found for this event' value: error: Tier not found for this event code: TIER_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: TIER_FULL: summary: 'TIER_FULL: This tier is full' value: error: This tier is full code: TIER_FULL remaining: 0 ALREADY_REGISTERED: summary: 'ALREADY_REGISTERED: Already registered' value: error: Already registered code: ALREADY_REGISTERED attendanceId: att_1 '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email tierId: type: string description: Defaults to the event's default tier. formAnswers: type: object additionalProperties: true donation: type: object properties: amount: type: integer description: In the smallest currency unit (cents). required: - amount successUrl: type: string format: uri cancelUrl: type: string format: uri items: type: array items: type: object properties: tierId: type: string quantity: type: integer minimum: 1 default: 1 customAmount: type: integer description: Pay-what-you-want only. In the smallest currency unit (cents). attendees: type: array items: type: object properties: name: type: string maxLength: 200 email: type: string formAnswers: type: object additionalProperties: true required: - tierId required: - email examples: single: value: email: alex@example.com tierId: tier_free formAnswers: f_diet: veg multi: value: email: alex@example.com items: - tierId: tier_free quantity: 2 attendees: - name: Alex Doe - name: Sam Roe email: sam@example.com /api/v1/communities/{communityTag}/events/{idOrSlug}/leave: post: operationId: postEventsIdOrSlugLeave summary: Leave an event description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). A member leaves with their session header; a guest passes the manage-link `token` from their confirmation email. For paid tickets a refund is attempted; if not eligible you get `400 REFUND_NOT_ELIGIBLE` and may retry with `forceWithoutRefund: true` to leave without one. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Events x-required-scope: WRITE_SALES x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSlug in: path required: true description: Event id or slug. schema: type: string - in: query required: false name: forceWithoutRefund schema: type: boolean responses: '200': description: Success. content: application/json: schema: type: object properties: message: type: string wasPaidAttendee: type: boolean refundProcessed: type: boolean refundAmount: type: - integer - 'null' description: In cents. example: message: You have left the event wasPaidAttendee: true refundProcessed: true refundAmount: 1500 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: REFUND_NOT_ELIGIBLE: summary: 'REFUND_NOT_ELIGIBLE: This purchase is outside the refund window' value: error: This purchase is outside the refund window code: REFUND_NOT_ELIGIBLE saleId: sale_1 saleAmount: 1500 canForceLeave: true '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: TOKEN_REQUIRED: summary: 'TOKEN_REQUIRED: A member session or a manage-link token is required' value: error: A member session or a manage-link token is required code: TOKEN_REQUIRED API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Event_not_found: summary: Event not found value: error: Event not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '500': description: Server error. content: application/json: schema: $ref: '#/components/schemas/Error' examples: REFUND_FAILED: summary: 'REFUND_FAILED: The refund could not be processed' value: error: The refund could not be processed code: REFUND_FAILED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: false content: application/json: schema: type: object properties: token: type: string description: Guest manage-link token. forceWithoutRefund: type: boolean example: token: eyJhbGciOi... /api/v1/communities/{communityTag}/events/{idOrSlug}/attendees/me/cancel-pending: post: operationId: postEventsIdOrSlugAttendeesMeCancelPending summary: Withdraw a pending reservation description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). For events that require approval: withdraws the member's pending reservation. A held payment is returned minus processing fees. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Events x-required-scope: WRITE_SALES x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSlug in: path required: true description: Event id or slug. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object additionalProperties: true example: cancelled: true '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Authentication_required_X_Cobuntu_Member_Token_o: summary: 'Authentication required: X-Cobuntu-Member-Token or X-Cobuntu-Auth-Token' value: error: 'Authentication required: X-Cobuntu-Member-Token or X-Cobuntu-Auth-Token' API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: No_PENDING_reservation_found_for_this_buyer_even: summary: No PENDING reservation found for this buyer + event value: error: No PENDING reservation found for this buyer + event '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/events/{idOrSlug}/attendance-status: get: operationId: getEventsIdOrSlugAttendanceStatus summary: Attendance status description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Three modes. **Member** (session header): the status plus labelled form answers. **Guest token** (`?token=`, the `event-cancel` / `sale-manage` token from the guest's email): that guest's full status, `lookupMode: guest_token`. **Email** (`?email=`): a yes/no only. `registered` is true for a live PENDING or APPROVED registration and every other field is null; limited to 10 lookups per minute per IP. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Events x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSlug in: path required: true description: Event id or slug. schema: type: string - in: query required: false name: token schema: type: string description: 'Guest manage-link token: full status.' - in: query required: false name: email schema: type: string format: email description: 'Yes/no lookup: returns `registered` only.' responses: '200': description: Success. content: application/json: schema: type: object properties: attendanceId: type: - string - 'null' status: type: - string - 'null' cancellationReason: type: - string - 'null' registered: type: boolean description: Email lookups only. formAnswersLabelled: type: - array - 'null' items: type: object properties: fieldId: type: string label: type: string value: type: string lookupMode: type: string enum: - member - guest_token - guest example: attendanceId: null status: null cancellationReason: null registered: true formAnswersLabelled: null lookupMode: guest '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Provide_a_member_token_token_manage_link_token_o: summary: Provide a member token, ?token=, or ?email= value: error: Provide a member token, ?token=, or ?email= API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Event_not_found: summary: Event not found value: error: Event not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Too_many_lookups_Try_again_later: summary: Too many lookups. Try again later. value: error: Too many lookups. Try again later. RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/events/{idOrSlug}/invitations/check: get: operationId: getEventsIdOrSlugInvitationsCheck summary: Check an invitation token description: |- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Events x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSlug in: path required: true description: Event id or slug. schema: type: string - in: query required: true name: token schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: valid: type: boolean status: type: string enum: - PENDING - ACCEPTED - CANCELLED - EXPIRED email: type: string eventSlug: type: - string - 'null' requiresPayment: type: boolean example: valid: true status: PENDING email: alex@example.com eventSlug: summer-meetup requiresPayment: false '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: token is required' value: error: token is required code: INVALID_INPUT INVALID_INVITATION_TOKEN: summary: 'INVALID_INVITATION_TOKEN: Invitation token is not valid' value: error: Invitation token is not valid code: INVALID_INVITATION_TOKEN '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: EVENT_NOT_FOUND: summary: 'EVENT_NOT_FOUND: Event not found' value: error: Event not found code: EVENT_NOT_FOUND INVITATION_NOT_FOUND: summary: 'INVITATION_NOT_FOUND: Invitation not found' value: error: Invitation not found code: INVITATION_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/events/{idOrSlug}/invitations/accept: post: operationId: postEventsIdOrSlugInvitationsAccept summary: Accept an invitation description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Free invitations register the attendee immediately. Paid ones answer `needs_payment`: pass the returned `invitationToken` to checkout to skip approval. `email` is required without a session and must match the invitation. **Rate limit:** 100 requests per 15 min per client IP, plus the per-key ceilings. tags: - Events x-required-scope: WRITE_SALES x-key-type: secret x-rate-limit: 100 requests per 15 min per client IP, plus the per-key ceilings. x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSlug in: path required: true description: Event id or slug. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: status: type: string enum: - attended - needs_payment eventSlug: type: string invitationToken: type: string example: status: needs_payment eventSlug: summer-meetup invitationToken: eyJhbGciOi... '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: token is required' value: error: token is required code: INVALID_INPUT INVALID_INVITATION_TOKEN: summary: 'INVALID_INVITATION_TOKEN: Invitation token is not valid' value: error: Invitation token is not valid code: INVALID_INVITATION_TOKEN '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is not valid' value: error: Session is not valid code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: EMAIL_MISMATCH: summary: 'EMAIL_MISMATCH: This invitation was sent to another email' value: error: This invitation was sent to another email code: EMAIL_MISMATCH API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVITATION_NOT_FOUND: summary: 'INVITATION_NOT_FOUND: Invitation not found' value: error: Invitation not found code: INVITATION_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVITATION_CANCELLED: summary: 'INVITATION_CANCELLED: Invitation was cancelled' value: error: Invitation was cancelled code: INVITATION_CANCELLED INVITATION_EXPIRED: summary: 'INVITATION_EXPIRED: Invitation has expired' value: error: Invitation has expired code: INVITATION_EXPIRED EVENT_FULL: summary: 'EVENT_FULL: Event is full' value: error: Event is full code: EVENT_FULL '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: token: type: string email: type: string format: email required: - token example: token: eyJhbGciOi... email: alex@example.com /api/v1/communities/{communityTag}/magic-links/verify: get: operationId: getMagicLinksVerify summary: Verify a guest manage link description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Verifies the token in a guest's "manage / cancel registration" email link and returns what to show. Use the same token with `POST /events/{idOrSlug}/leave`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Events x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: true name: token schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: purpose: type: string eventSlug: type: string eventName: type: string startDate: type: string format: date-time email: type: string saleId: type: - string - 'null' attendanceId: type: - string - 'null' refundEligible: type: - boolean - 'null' refundReason: type: - string - 'null' example: purpose: event-cancel eventSlug: summer-meetup eventName: Summer Meetup startDate: '2026-11-20T18:00:00Z' email: alex@example.com saleId: null attendanceId: att_1 refundEligible: null refundReason: null '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: token is required' value: error: token is required code: INVALID_INPUT UNSUPPORTED_LINK: summary: 'UNSUPPORTED_LINK: This link type is not supported here' value: error: This link type is not supported here code: UNSUPPORTED_LINK '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_LINK: summary: 'INVALID_LINK: This link is not valid' value: error: This link is not valid code: INVALID_LINK API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LINK_MISMATCH: summary: 'LINK_MISMATCH: This link does not match' value: error: This link does not match code: LINK_MISMATCH API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LINK_NOT_FOUND: summary: 'LINK_NOT_FOUND: Registration not found' value: error: Registration not found code: LINK_NOT_FOUND '410': description: Gone. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LINK_EXPIRED: summary: 'LINK_EXPIRED: This link has expired' value: error: This link has expired code: LINK_EXPIRED '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/events/external/{platform}/{externalId}: get: operationId: getEventsExternalPlatformExternalId summary: Find an imported event by external id description: |- **Required scope:** `WRITE_EVENTS` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). For importers and sync jobs: answers "have I already imported this?". **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Events x-required-scope: WRITE_EVENTS x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: platform in: path required: true schema: type: string enum: - luma - shotgun - sanity - name: externalId in: path required: true description: The event id on the external platform. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: event: type: object additionalProperties: true externalListings: type: array items: type: object properties: platform: type: string externalId: type: string externalUrl: type: - string - 'null' example: event: id: evt_123 name: Summer Meetup externalListings: - platform: LUMA externalId: evt-abc externalUrl: https://lu.ma/abc '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Unknown_platform: summary: Unknown platform value: error: Unknown platform allowed: - luma - shotgun - sanity '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_does_not_belong_to_this_community: summary: API key does not belong to this community value: error: API key does not belong to this community API_key_missing_required_scope_WRITE_EVENTS: summary: 'API key missing required scope: WRITE_EVENTS' value: error: 'API key missing required scope: WRITE_EVENTS' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Community_not_found: summary: Community not found value: error: Community not found No_event_with_this_external_id_in_this_community: summary: No event with this external id in this community value: error: No event with this external id in this community '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable put: operationId: putEventsExternalPlatformExternalId summary: Create or update an event by external id description: >- **Required scope:** `WRITE_EVENTS` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Idempotent upsert keyed on the external platform id: re-running updates instead of duplicating. `201` on create, `200` on update. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Events x-required-scope: WRITE_EVENTS x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: platform in: path required: true schema: type: string enum: - luma - shotgun - sanity - name: externalId in: path required: true description: The event id on the external platform. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object additionalProperties: true properties: created: type: boolean example: created: false event: id: evt_123 '201': description: Created. content: application/json: schema: type: object additionalProperties: true properties: created: type: boolean example: created: true event: id: evt_124 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Unknown_platform: summary: Unknown platform value: error: Unknown platform allowed: - luma - shotgun - sanity name_is_required: summary: name is required value: error: name is required timezone_is_required_IANA_name_e_g_Europe_Lisbon: summary: timezone is required (IANA name, e.g. Europe/Lisbon) value: error: timezone is required (IANA name, e.g. Europe/Lisbon) '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_does_not_belong_to_this_community: summary: API key does not belong to this community value: error: API key does not belong to this community API_key_missing_required_scope_WRITE_EVENTS: summary: 'API key missing required scope: WRITE_EVENTS' value: error: 'API key missing required scope: WRITE_EVENTS' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Community_not_found: summary: Community not found value: error: Community not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/EventWrite' - type: object properties: externalUrl: type: - string - 'null' format: uri tiers: type: array items: type: object additionalProperties: true publish: type: boolean links: type: array items: type: object properties: platform: type: string enum: - LUMA - SHOTGUN - SANITY externalId: type: string externalUrl: type: - string - 'null' required: - platform - externalId required: - name - startDate - endDate - timezone example: name: Summer Meetup startDate: '2026-11-20T18:00:00Z' endDate: '2026-11-20T21:00:00Z' timezone: Europe/Lisbon physicalLocation: Main Hall, Lisbon externalUrl: https://lu.ma/abc publish: true /api/v1/communities/{communityTag}/events/{idOrSlug}/checkout: post: operationId: postEventsIdOrSlugCheckout summary: Create a ticket checkout description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. Returns a Stripe Checkout URL. One tier (`tierId`, `quantity` up to 10) or several with `items[]` (max 10 places, one currency). All amounts are in cents. `customAmount` only for pay-what-you-want tiers (at least `pwywMinAmount`). `paymentPlan: INSTALLMENTS` needs a signed-in member and quantity 1. `invitationToken` (from invitations/accept) skips the approval queue. Attendance is created when payment completes, not by this call. **Rate limit:** 100 requests per 15 min per client IP, plus the per-key ceilings. tags: - Checkout x-required-scope: WRITE_SALES x-required-scope-note: >- The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. x-key-type: publishable x-rate-limit: 100 requests per 15 min per client IP, plus the per-key ceilings. x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSlug in: path required: true description: Event id or slug. schema: type: string responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/CheckoutRedirect' - type: object properties: tickets: type: integer description: Places in the order (items[] only). example: checkoutUrl: https://checkout.stripe.com/c/pay/cs_test_123 sessionId: cs_test_123 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: tierId_is_required: summary: tierId is required value: error: tierId is required successUrl_and_cancelUrl_are_required_and_must_b: summary: successUrl and cancelUrl are required and must be absolute URLs value: error: successUrl and cancelUrl are required and must be absolute URLs Quantity_capped_at_10_per_checkout_session: summary: Quantity capped at 10 per checkout session value: error: Quantity capped at 10 per checkout session INVALID_CUSTOM_AMOUNT: summary: 'INVALID_CUSTOM_AMOUNT: customAmount must be a positive integer in the smallest currency unit' value: error: customAmount must be a positive integer in the smallest currency unit code: INVALID_CUSTOM_AMOUNT INVALID_PAYMENT_PLAN: summary: 'INVALID_PAYMENT_PLAN: paymentPlan must be FULL or INSTALLMENTS' value: error: paymentPlan must be FULL or INSTALLMENTS code: INVALID_PAYMENT_PLAN INVALID_INVITATION_TOKEN: summary: 'INVALID_INVITATION_TOKEN: invitationToken must be a string' value: error: invitationToken must be a string code: INVALID_INVITATION_TOKEN CUSTOM_AMOUNT_REQUIRED: summary: 'CUSTOM_AMOUNT_REQUIRED: This ticket is pay-what-you-want: send customAmount' value: error: 'This ticket is pay-what-you-want: send customAmount' code: CUSTOM_AMOUNT_REQUIRED CUSTOM_AMOUNT_TOO_LOW: summary: 'CUSTOM_AMOUNT_TOO_LOW: customAmount is below the minimum' value: error: customAmount is below the minimum code: CUSTOM_AMOUNT_TOO_LOW minAmount: 500 CUSTOM_AMOUNT_NOT_ACCEPTED: summary: 'CUSTOM_AMOUNT_NOT_ACCEPTED: This ticket has a fixed price; customAmount is not accepted' value: error: This ticket has a fixed price; customAmount is not accepted code: CUSTOM_AMOUNT_NOT_ACCEPTED INSTALLMENTS_NOT_OFFERED: summary: 'INSTALLMENTS_NOT_OFFERED: This ticket is not offered in instalments' value: error: This ticket is not offered in instalments code: INSTALLMENTS_NOT_OFFERED FULL_PAYMENT_NOT_OFFERED: summary: 'FULL_PAYMENT_NOT_OFFERED: This ticket is only sold in instalments' value: error: This ticket is only sold in instalments code: FULL_PAYMENT_NOT_OFFERED QUANTITY_LOCKED: summary: 'QUANTITY_LOCKED: An instalment plan is bought one at a time' value: error: An instalment plan is bought one at a time code: QUANTITY_LOCKED DONATION_NOT_ALLOWED: summary: 'DONATION_NOT_ALLOWED: A donation cannot ride along with an instalment plan' value: error: A donation cannot ride along with an instalment plan code: DONATION_NOT_ALLOWED FORM_ANSWERS_REQUIRED: summary: 'FORM_ANSWERS_REQUIRED: Required form answers are missing' value: error: Required form answers are missing code: FORM_ANSWERS_REQUIRED missingFields: - f_diet AMBIGUOUS_BODY: summary: 'AMBIGUOUS_BODY: Send either tierId or items[], not both' value: error: Send either tierId or items[], not both code: AMBIGUOUS_BODY MIXED_CURRENCY: summary: 'MIXED_CURRENCY: All tiers in one order must share a currency' value: error: All tiers in one order must share a currency code: MIXED_CURRENCY TOO_MANY_TICKETS: summary: 'TOO_MANY_TICKETS: At most 10 places per order' value: error: At most 10 places per order code: TOO_MANY_TICKETS max: 10 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SESSION_REQUIRED: summary: 'SESSION_REQUIRED: An instalment plan needs a signed-in member (X-Cobuntu-Auth-Token)' value: error: An instalment plan needs a signed-in member (X-Cobuntu-Auth-Token) code: SESSION_REQUIRED API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: MEMBERS_ONLY: summary: 'MEMBERS_ONLY: Event is members-only: checkout requires a member token' value: error: 'Event is members-only: checkout requires a member token' code: MEMBERS_ONLY API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: TIER_NOT_FOUND: summary: 'TIER_NOT_FOUND: Tier not found' value: error: Tier not found code: TIER_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: TIER_NOT_ON_SALE: summary: 'TIER_NOT_ON_SALE: Tier is not currently on sale' value: error: Tier is not currently on sale code: TIER_NOT_ON_SALE state: scheduled opensAt: '2026-11-01T09:00:00Z' TIER_FULL: summary: 'TIER_FULL: This tier is sold out' value: error: This tier is sold out code: TIER_FULL ALREADY_HAS_TICKET: summary: 'ALREADY_HAS_TICKET: You already have a ticket' value: error: You already have a ticket code: ALREADY_HAS_TICKET EVENT_CLOSED: summary: 'EVENT_CLOSED: This event is closed' value: error: This event is closed code: EVENT_CLOSED '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: tierId: type: string quantity: type: integer minimum: 1 maximum: 10 default: 1 customer: type: object properties: email: type: string format: email name: type: string successUrl: type: string format: uri cancelUrl: type: string format: uri formAnswers: type: object additionalProperties: true donation: type: object properties: amount: type: integer description: In the smallest currency unit (cents). customAmount: type: integer description: Pay-what-you-want only. In the smallest currency unit (cents). paymentPlan: type: string enum: - FULL - INSTALLMENTS invitationToken: type: string maxLength: 4096 items: type: array items: type: object properties: tierId: type: string quantity: type: integer minimum: 1 default: 1 customAmount: type: integer description: Pay-what-you-want only. In the smallest currency unit (cents). attendees: type: array items: type: object properties: name: type: string maxLength: 200 email: type: string formAnswers: type: object additionalProperties: true required: - tierId required: - successUrl - cancelUrl examples: single: value: tierId: tier_1 quantity: 2 customer: email: alex@example.com successUrl: https://example.com/thanks cancelUrl: https://example.com/event multi: value: items: - tierId: tier_1 quantity: 1 - tierId: tier_vip quantity: 1 successUrl: https://example.com/thanks cancelUrl: https://example.com/event payWhatYouWant: value: tierId: tier_pwyw customAmount: 2000 successUrl: https://example.com/thanks cancelUrl: https://example.com/event /api/v1/communities/{communityTag}/checkout/sessions/{sessionId}: get: operationId: getCheckoutSessionsSessionId summary: Checkout session status description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. Call it when Stripe returns the buyer to your `successUrl` (`?session_id=...`). Amounts in cents. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Checkout x-required-scope: WRITE_SALES x-required-scope-note: >- The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: sessionId in: path required: true description: The Stripe Checkout session id (starts with `cs_`). schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: status: type: string enum: - pending - paid totalAmount: type: integer description: In the smallest currency unit (cents). currency: type: string items: type: array items: type: object properties: name: type: string type: type: string amount: type: integer description: In the smallest currency unit (cents). example: status: paid totalAmount: 3000 currency: EUR items: - name: General type: EVENT amount: 1500 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION_ID: summary: 'INVALID_SESSION_ID: sessionId must be a Stripe checkout session id' value: error: sessionId must be a Stripe checkout session id code: INVALID_SESSION_ID '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND SESSION_NOT_FOUND: summary: 'SESSION_NOT_FOUND: Checkout session not found' value: error: Checkout session not found code: SESSION_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/events/{idOrSlug}/sales/me/refund: post: operationId: postEventsIdOrSlugSalesMeRefund summary: Buyer refunds their own ticket description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. **Amount unit quirk:** unlike every other amount in this API, `amount` here is in **major units** (euros, not cents): `12.5` means EUR 12.50. Omit it for a full refund. Refund eligibility (refund window, payment state) is enforced; a member session is required. **Rate limit:** 100 requests per 15 min per client IP, plus the per-key ceilings. tags: - Checkout x-required-scope: WRITE_SALES x-required-scope-note: >- The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. x-key-type: publishable x-rate-limit: 100 requests per 15 min per client IP, plus the per-key ceilings. x-member-session: required security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSlug in: path required: true description: Event id or slug. schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/RefundResult' example: id: ref_1 status: PENDING amount: 1500 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: saleId_is_required: summary: saleId is required value: error: saleId is required reason_is_required: summary: reason is required value: error: reason is required Invalid_refund_amount: summary: Invalid refund amount value: error: Invalid refund amount Sale_is_not_for_an_event: summary: Sale is not for an event value: error: Sale is not for an event Not_eligible_for_a_refund_the_refund_window_has_: summary: 'Not eligible for a refund: the refund window has closed' value: error: 'Not eligible for a refund: the refund window has closed' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Authentication_required_X_Cobuntu_Member_Token_o: summary: 'Authentication required: X-Cobuntu-Member-Token or X-Cobuntu-Auth-Token' value: error: 'Authentication required: X-Cobuntu-Member-Token or X-Cobuntu-Auth-Token' API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not_authorized_to_refund_this_purchase: summary: Not authorized to refund this purchase value: error: Not authorized to refund this purchase API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Sale_not_found: summary: Sale not found value: error: Sale not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: saleId: type: string reason: type: string amount: type: number exclusiveMinimum: 0 maximum: 1000000 description: MAJOR units (not cents). Omit for a full refund. refundType: type: string default: BUYER_REQUEST required: - saleId - reason example: saleId: sale_1 reason: Cannot attend /api/v1/communities/{communityTag}/apply/checkout: post: operationId: postApplyCheckout summary: Pay for an anonymous application description: >- **Required scope:** `WRITE_APPLICATIONS` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Second step of a paid public application: after `POST /segments/{segmentId}/submit` returns a request awaiting payment, create its Stripe checkout. `successUrl`/`cancelUrl` are optional but come together, and must be https on the community's allowed origin. **Rate limit:** 100 requests per 15 min per client IP, plus the per-key ceilings. tags: - Checkout x-required-scope: WRITE_APPLICATIONS x-key-type: publishable x-rate-limit: 100 requests per 15 min per client IP, plus the per-key ceilings. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/CheckoutRedirect' example: checkoutUrl: https://checkout.stripe.com/c/pay/cs_test_123 sessionId: cs_test_123 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: requestId_is_required: summary: requestId is required value: error: requestId is required INVALID_RETURN_URL: summary: 'INVALID_RETURN_URL: successUrl and cancelUrl must be https URLs on the allowed origin' value: error: successUrl and cancelUrl must be https URLs on the allowed origin code: INVALID_RETURN_URL Application_is_not_awaiting_payment: summary: Application is not awaiting payment value: error: Application is not awaiting payment '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Application_does_not_belong_to_this_community: summary: Application does not belong to this community value: error: Application does not belong to this community API_key_missing_required_scope_WRITE_APPLICATION: summary: 'API key missing required scope: WRITE_APPLICATIONS' value: error: 'API key missing required scope: WRITE_APPLICATIONS' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Application_not_found: summary: Application not found value: error: Application not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: requestId: type: string origin: type: string successUrl: type: string format: uri cancelUrl: type: string format: uri required: - requestId example: requestId: req_123 successUrl: https://example.com/welcome cancelUrl: https://example.com/join /api/v1/communities/{communityTag}/events/{idOrSlug}/donate: post: operationId: postEventsIdOrSlugDonate summary: Donate to an event description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. A standalone donation without buying a ticket. `customer.email` is required without a member session. Send `X-Idempotency-Key` to make retries safe. **Rate limit:** 30 requests per hour per client IP, plus the per-key ceilings. tags: - Checkout x-required-scope: WRITE_SALES x-required-scope-note: >- The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. x-key-type: publishable x-rate-limit: 30 requests per hour per client IP, plus the per-key ceilings. x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSlug in: path required: true description: Event id or slug. schema: type: string - $ref: '#/components/parameters/IdempotencyKey' responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/CheckoutRedirect' example: checkoutUrl: https://checkout.stripe.com/c/pay/cs_test_123 sessionId: cs_test_123 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_DONATION_AMOUNT: summary: 'INVALID_DONATION_AMOUNT: donation.amount must be a positive integer (smallest unit)' value: error: donation.amount must be a positive integer (smallest unit) code: INVALID_DONATION_AMOUNT successUrl_and_cancelUrl_are_required_absolute_U: summary: successUrl and cancelUrl are required (absolute URLs) value: error: successUrl and cancelUrl are required (absolute URLs) customer_email_is_required_for_anonymous_donatio: summary: customer.email is required for anonymous donations value: error: customer.email is required for anonymous donations '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Event_is_members_only_donations_require_a_member: summary: 'Event is members-only: donations require a member token' value: error: 'Event is members-only: donations require a member token' API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Event_not_found: summary: Event not found value: error: Event not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: donation: type: object properties: amount: type: integer description: In the smallest currency unit (cents). required: - amount customer: type: object properties: email: type: string format: email successUrl: type: string format: uri cancelUrl: type: string format: uri required: - donation - successUrl - cancelUrl example: donation: amount: 1000 customer: email: alex@example.com successUrl: https://example.com/thanks cancelUrl: https://example.com/support /api/v1/communities/{communityTag}/products/{idOrSku}/donate: post: operationId: postProductsIdOrSkuDonate summary: Donate to a product description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. A standalone donation to a product. `customer.email` is required without a member session. Send `X-Idempotency-Key` to make retries safe. **Rate limit:** 30 requests per hour per client IP, plus the per-key ceilings. tags: - Checkout x-required-scope: WRITE_SALES x-required-scope-note: >- The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. x-key-type: publishable x-rate-limit: 30 requests per hour per client IP, plus the per-key ceilings. x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSku in: path required: true description: Product id or SKU. schema: type: string - $ref: '#/components/parameters/IdempotencyKey' responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/CheckoutRedirect' example: checkoutUrl: https://checkout.stripe.com/c/pay/cs_test_123 sessionId: cs_test_123 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_DONATION_AMOUNT: summary: 'INVALID_DONATION_AMOUNT: donation.amount must be a positive integer (smallest unit)' value: error: donation.amount must be a positive integer (smallest unit) code: INVALID_DONATION_AMOUNT successUrl_and_cancelUrl_are_required_absolute_U: summary: successUrl and cancelUrl are required (absolute URLs) value: error: successUrl and cancelUrl are required (absolute URLs) customer_email_is_required_for_anonymous_donatio: summary: customer.email is required for anonymous donations value: error: customer.email is required for anonymous donations '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Product_not_found: summary: Product not found value: error: Product not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: donation: type: object properties: amount: type: integer description: In the smallest currency unit (cents). required: - amount customer: type: object properties: email: type: string format: email successUrl: type: string format: uri cancelUrl: type: string format: uri required: - donation - successUrl - cancelUrl example: donation: amount: 1000 customer: email: alex@example.com successUrl: https://example.com/thanks cancelUrl: https://example.com/support /api/v1/communities/{communityTag}/events/{idOrSlug}/donations/summary: get: operationId: getEventsIdOrSlugDonationsSummary summary: An event's donation totals description: |- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Aggregates only; no donor identity. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Checkout x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSlug in: path required: true description: Event id or slug. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: total: type: integer description: Sum of donations. In the smallest currency unit (cents). count: type: integer currency: type: - string - 'null' example: total: 45000 count: 31 currency: EUR '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Event_not_found: summary: Event not found value: error: Event not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/products/{idOrSku}/donations/summary: get: operationId: getProductsIdOrSkuDonationsSummary summary: A product's donation totals description: |- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Aggregates only; no donor identity. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Checkout x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSku in: path required: true description: Product id or SKU. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: total: type: integer description: Sum of donations. In the smallest currency unit (cents). count: type: integer currency: type: - string - 'null' example: total: 45000 count: 31 currency: EUR '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Product_not_found: summary: Product not found value: error: Product not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/segments/public: get: operationId: getSegmentsPublic summary: List public membership tiers description: |- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Prices in cents. Optional `X-Source` header labels the traffic source for funnel analytics. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: array items: $ref: '#/components/schemas/Segment' example: - id: seg_pro name: Pro description: Full access hasForm: true priceMonthly: 1500 priceYearly: 15000 currency: EUR '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_does_not_belong_to_this_community: summary: API key does not belong to this community value: error: API key does not belong to this community API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Community_not_found: summary: Community not found value: error: Community not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/segments/{segmentId}/check-email: get: operationId: getSegmentsSegmentIdCheckEmail summary: Check an email against a tier description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Tells you whether the email already has an account, membership or pending application, so a form can branch before submit. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: segmentId in: path required: true description: Membership tier id. schema: type: string - in: query required: true name: email schema: type: string format: email responses: '200': description: Success. content: application/json: schema: type: object additionalProperties: true example: exists: true isMember: false hasPendingApplication: false '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Valid_email_is_required: summary: Valid email is required value: error: Valid email is required '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_does_not_belong_to_this_community: summary: API key does not belong to this community value: error: API key does not belong to this community API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Community_not_found: summary: Community not found value: error: Community not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/segments/{segmentId}/form: get: operationId: getSegmentsSegmentIdForm summary: A tier's application form description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. The form schema to render; submit answers to `/submit`. Only tiers of the key's community; an unknown tag is `404`. A hidden (invite-only) tier needs `?invitationToken=` for that tier, otherwise `404`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: segmentId in: path required: true description: Membership tier id. schema: type: string - in: query required: false name: invitationToken schema: type: string description: Required for a hidden tier. responses: '200': description: Success. content: application/json: schema: type: object additionalProperties: true properties: fields: type: array items: $ref: '#/components/schemas/FormField' example: title: Join Acme fields: - id: f_why type: text label: Why do you want to join? required: true '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_does_not_belong_to_this_community: summary: API key does not belong to this community value: error: API key does not belong to this community API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Form_not_found: summary: Form not found value: error: Form not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/segments/{segmentId}/submit: post: operationId: postSegmentsSegmentIdSubmit summary: Submit an application description: >- **Required scope:** `WRITE_APPLICATIONS` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Browser-safe (publishable key). Only active tiers; a hidden tier needs `invitationToken` (a pending invitation to that tier; a personal one must match the email), otherwise `404 Segment not found`. For a paid tier the response indicates payment is required; continue with `POST /apply/checkout`. A publishable-key submit that would auto-approve (free tier, open community) stays PENDING with `awaitingEmailConfirmation: true` until the applicant clicks the emailed confirmation link; a secret-key submit skips that step. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. Also 10 submissions per hour per IP. tags: - Members x-required-scope: WRITE_APPLICATIONS x-key-type: publishable x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. Also 10 submissions per hour per IP. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: segmentId in: path required: true description: Membership tier id. schema: type: string responses: '201': description: Success. content: application/json: schema: type: object additionalProperties: true properties: success: type: boolean requestId: type: string paymentRequired: type: boolean autoApproved: type: boolean awaitingEmailConfirmation: type: boolean example: success: true requestId: req_123 awaitingEmailConfirmation: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: answers_object_is_required: summary: answers object is required value: error: answers object is required '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_does_not_belong_to_this_community: summary: API key does not belong to this community value: error: API key does not belong to this community API_key_missing_required_scope_WRITE_APPLICATION: summary: 'API key missing required scope: WRITE_APPLICATIONS' value: error: 'API key missing required scope: WRITE_APPLICATIONS' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Community_not_found: summary: Community not found value: error: Community not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Too_many_submissions_Try_again_later: summary: Too many submissions. Try again later. value: error: Too many submissions. Try again later. RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: answers: type: object additionalProperties: true description: Field id to answer; must include the email field. invitationToken: type: string description: Required for a hidden tier. source: type: string billingCycle: type: string currency: type: string minLength: 3 maxLength: 3 referralCode: type: string required: - answers example: answers: email: alex@example.com name: Alex Doe f_why: Events billingCycle: MONTHLY currency: EUR /api/v1/communities/{communityTag}/segments/{segmentId}: patch: operationId: patchSegmentsSegmentId summary: Update a membership tier description: >- **Required scope:** `WRITE_SEGMENTS` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Change name, description, color, active status or prices (cents). Creating and deleting tiers is not available over the API. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: WRITE_SEGMENTS x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: segmentId in: path required: true description: Membership tier id. schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Segment' example: id: seg_pro name: Pro priceMonthly: 1800 currency: EUR '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: No_updatable_fields_supplied: summary: No updatable fields supplied value: error: No updatable fields supplied allowed: - name - description - color - isActive - priceMonthly - priceYearly - priceOneTime - currency Connect_a_Stripe_account_before_setting_prices: summary: Connect a Stripe account before setting prices value: error: Connect a Stripe account before setting prices '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_does_not_belong_to_this_community: summary: API key does not belong to this community value: error: API key does not belong to this community API_key_missing_required_scope_WRITE_SEGMENTS: summary: 'API key missing required scope: WRITE_SEGMENTS' value: error: 'API key missing required scope: WRITE_SEGMENTS' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Segment_not_found: summary: Segment not found value: error: Segment not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: type: string color: type: string isActive: type: boolean priceMonthly: type: integer description: In the smallest currency unit (cents). priceYearly: type: integer description: In the smallest currency unit (cents). priceOneTime: type: integer description: In the smallest currency unit (cents). currency: type: string example: priceMonthly: 1800 isActive: true /api/v1/communities/{communityTag}/applications/{requestId}/approve: post: operationId: postApplicationsRequestIdApprove summary: Approve an application description: |- **Required scope:** `WRITE_MEMBERS` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: WRITE_MEMBERS x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: requestId in: path required: true description: Application (membership request) id. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object additionalProperties: true example: success: true '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_does_not_belong_to_this_community: summary: API key does not belong to this community value: error: API key does not belong to this community API_key_missing_required_scope_WRITE_MEMBERS: summary: 'API key missing required scope: WRITE_MEMBERS' value: error: 'API key missing required scope: WRITE_MEMBERS' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Membership_request_not_found: summary: Membership request not found value: error: Membership request not found Community_not_found: summary: Community not found value: error: Community not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/applications/{requestId}/reject: post: operationId: postApplicationsRequestIdReject summary: Reject an application description: |- **Required scope:** `WRITE_MEMBERS` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: WRITE_MEMBERS x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: requestId in: path required: true description: Application (membership request) id. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object additionalProperties: true example: success: true '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_does_not_belong_to_this_community: summary: API key does not belong to this community value: error: API key does not belong to this community API_key_missing_required_scope_WRITE_MEMBERS: summary: 'API key missing required scope: WRITE_MEMBERS' value: error: 'API key missing required scope: WRITE_MEMBERS' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Membership_request_not_found: summary: Membership request not found value: error: Membership request not found Community_not_found: summary: Community not found value: error: Community not found '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Cannot_resolve_a_founder_user_for_this_community: summary: Cannot resolve a founder user for this community value: error: Cannot resolve a founder user for this community '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: false content: application/json: schema: type: object properties: reason: type: string example: reason: Not a fit right now /api/v1/communities/{communityTag}/rules: get: operationId: getRules summary: Community rules description: |- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: rules: type: array items: type: object properties: id: type: string title: type: string description: type: - string - 'null' linkUrl: type: - string - 'null' linkLabel: type: - string - 'null' order: type: integer example: rules: - id: r1 title: Be kind description: Treat everyone with respect. order: 1 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_does_not_belong_to_this_community: summary: API key does not belong to this community value: error: API key does not belong to this community API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Community_not_found: summary: Community not found value: error: Community not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/co-creation: get: operationId: getCoCreation summary: Co-creation eligibility description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. May this viewer create an event, a product or a course in the community, and if not, why not. Optionally identify a member with `X-Cobuntu-Auth-Token`; without one, an enabled surface answers `signin`. States in the order they are decided: `disabled` (show nothing), `signin`, `join`, `locked` (the member's tier may not create this kind), `allowed`. An affordance hint: the create flow is the authoritative gate. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: event: allOf: - type: object properties: enabled: type: boolean description: The community takes member listings of this kind. requireApproval: type: boolean description: New listings wait for approval before going live. feeModel: type: - string - 'null' enum: - FLAT - DYNAMIC - null state: type: string enum: - disabled - signin - join - locked - allowed reason: type: - string - 'null' enum: - ok - role_grant - not_member - toggle_off - tier_locked - null required: - enabled - requireApproval - feeModel - state - reason - type: object properties: allowMemberEventListings: type: boolean memberEventFeeModel: type: - string - 'null' enum: - FLAT - DYNAMIC - null memberEventRequireApproval: type: boolean platformFees: type: object properties: events: type: number description: What Cobuntu charges the community, as a fraction (0.08 = 8%). payments: type: object properties: connected: type: boolean chargesEnabled: type: boolean description: The community's own Stripe. product: type: object properties: enabled: type: boolean description: The community takes member listings of this kind. requireApproval: type: boolean description: New listings wait for approval before going live. feeModel: type: - string - 'null' enum: - FLAT - DYNAMIC - null state: type: string enum: - disabled - signin - join - locked - allowed reason: type: - string - 'null' enum: - ok - role_grant - not_member - toggle_off - tier_locked - null required: - enabled - requireApproval - feeModel - state - reason course: type: object properties: enabled: type: boolean description: The community takes member listings of this kind. requireApproval: type: boolean description: New listings wait for approval before going live. feeModel: type: - string - 'null' enum: - FLAT - DYNAMIC - null state: type: string enum: - disabled - signin - join - locked - allowed reason: type: - string - 'null' enum: - ok - role_grant - not_member - toggle_off - tier_locked - null required: - enabled - requireApproval - feeModel - state - reason required: - event - product - course example: event: enabled: true requireApproval: false feeModel: FLAT state: allowed reason: ok product: enabled: true requireApproval: false feeModel: FLAT state: locked reason: tier_locked course: enabled: false requireApproval: false feeModel: null state: disabled reason: toggle_off '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/rules/accept: post: operationId: postRulesAccept summary: Record rules acceptance by email description: |- **Required scope:** `WRITE_MEMBERS` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Server-side only: the caller names the email. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: WRITE_MEMBERS x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object additionalProperties: true example: success: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Valid_email_is_required: summary: Valid email is required value: error: Valid email is required '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_MEMBERS: summary: 'API key missing required scope: WRITE_MEMBERS' value: error: 'API key missing required scope: WRITE_MEMBERS' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email required: - email example: email: alex@example.com /api/v1/communities/{communityTag}/members: get: operationId: getMembers summary: List members description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Without `MEMBERS_ADMIN` (any key type, no member session) this follows the community's Members page setting: switched off is `404 PAGE_DISABLED`; members-only or private is `403 MEMBERS_ONLY` (use `GET /me/directory` with a member session, or a secret key with `MEMBERS_ADMIN`); public returns the roster without members who chose to hide from the directory. With `MEMBERS_ADMIN` (or `ADMIN`, secret keys only) the full roster is returned, hidden members included. Reads are audited. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: READ_PUBLIC x-required-scope-note: or `MEMBERS_ADMIN` for the full roster x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: usertags schema: type: string description: Comma-separated usertags to filter by. - in: query required: false name: limit schema: type: integer - in: query required: false name: offset schema: type: integer responses: '200': description: Success. content: application/json: schema: type: object properties: members: type: array items: $ref: '#/components/schemas/Member' pagination: $ref: '#/components/schemas/Pagination' example: members: - userId: usr_123 name: Alex Doe usertag: alex profileImage: null roleGroups: - name: Member color: '#888888' joinedAt: '2026-01-10T12:00:00Z' profileUrl: https://your-community.cobuntu.com/members/alex pagination: total: 1 limit: 20 offset: 0 hasMore: false '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: MEMBERS_ONLY: summary: 'MEMBERS_ONLY: The members page is for members only' value: error: The members page is for members only code: MEMBERS_ONLY reason: members_page_members_only hint: Use GET /me/directory with a member session, or a secret key with MEMBERS_ADMIN. API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: PAGE_DISABLED: summary: 'PAGE_DISABLED: The members page is switched off' value: error: The members page is switched off code: PAGE_DISABLED '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/members/{userId}: get: operationId: getMembersUserId summary: Get a member description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. `userId` accepts a user id or usertag. Without `MEMBERS_ADMIN` (any key type, no member session) this follows the community's Members page setting: switched off is `404 PAGE_DISABLED`; members-only or private is `403 MEMBERS_ONLY` (use `GET /me/directory` with a member session, or a secret key with `MEMBERS_ADMIN`); public returns the roster without members who chose to hide from the directory. With `MEMBERS_ADMIN` (or `ADMIN`, secret keys only) the full roster is returned, hidden members included. Without `MEMBERS_ADMIN`, a member who hides from the directory is `404`. Reads are audited. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: READ_PUBLIC x-required-scope-note: or `MEMBERS_ADMIN` to see hidden members x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: userId in: path required: true description: User id or usertag. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: member: $ref: '#/components/schemas/Member' example: member: userId: usr_123 name: Alex Doe usertag: alex profileImage: null roleGroups: - name: Member color: '#888888' joinedAt: '2026-01-10T12:00:00Z' profileUrl: https://your-community.cobuntu.com/members/alex '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: MEMBERS_ONLY: summary: 'MEMBERS_ONLY: The members page is for members only' value: error: The members page is for members only code: MEMBERS_ONLY reason: members_page_members_only hint: Use GET /me/directory with a member session, or a secret key with MEMBERS_ADMIN. API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Member_not_found: summary: Member not found value: error: Member not found PAGE_DISABLED: summary: 'PAGE_DISABLED: The members page is switched off' value: error: The members page is switched off code: PAGE_DISABLED '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/members/{userId}/membership: get: operationId: getMembersUserIdMembership summary: A member's authoritative membership description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Status, roles, and (for a secret key with `APP_ONBOARDING` or `MEMBERS_ADMIN` only) flattened permissions and active tiers. For other keys `permissions` and `segments` are absent, not empty. Follows the Members page setting; members hidden from the directory are `404`. Re-verify here before granting anything privileged. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: userId in: path required: true description: User id or usertag. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: membership: $ref: '#/components/schemas/MemberMembership' example: membership: userId: usr_123 usertag: alex status: ACCEPTED joinedAt: '2026-01-10T12:00:00Z' roleGroups: - name: Member color: null isSystem: true permissions: - events.view segments: - segmentId: seg_pro name: Pro isDefault: false currentPeriodEnd: '2026-11-13T00:00:00Z' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Forbidden: summary: Forbidden value: error: Forbidden reason: members_page_not_public hint: Use a secret key, or make the members page public. API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Member_not_found: summary: Member not found value: error: Member not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/members/{userId}/onboarding: get: operationId: getMembersUserIdOnboarding summary: A member's onboarding status description: |- **Required scope:** `APP_ONBOARDING` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). For installed apps. Reads are audited. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Apps x-required-scope: APP_ONBOARDING x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: userId in: path required: true description: User id or usertag. schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Onboarding' example: complete: false nextStep: rules steps: rules: required: true done: false data: required: true done: false rules: - id: r1 title: Be kind description: null order: 1 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_does_not_belong_to_this_community: summary: API key does not belong to this community value: error: API key does not belong to this community API_key_missing_required_scope_APP_ONBOARDING: summary: 'API key missing required scope: APP_ONBOARDING' value: error: 'API key missing required scope: APP_ONBOARDING' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Member_not_found: summary: Member not found value: error: Member not found Community_not_found: summary: Community not found value: error: Community not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/members/{userId}/onboarding/data: post: operationId: postMembersUserIdOnboardingData summary: Submit a member's onboarding answers description: |- **Required scope:** `APP_ONBOARDING` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Apps x-required-scope: APP_ONBOARDING x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: userId in: path required: true description: User id or usertag. schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Onboarding' example: complete: false nextStep: rules steps: rules: required: true done: false data: required: true done: false rules: - id: r1 title: Be kind description: null order: 1 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: segmentId_is_required: summary: segmentId is required value: error: segmentId is required answers_must_be_an_object_keyed_by_field_id: summary: answers must be an object keyed by field id value: error: answers must be an object keyed by field id '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_APP_ONBOARDING: summary: 'API key missing required scope: APP_ONBOARDING' value: error: 'API key missing required scope: APP_ONBOARDING' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Tier_not_found_in_this_community: summary: Tier not found in this community value: error: Tier not found in this community '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: segmentId: type: string answers: type: object additionalProperties: true required: - segmentId example: segmentId: seg_pro answers: f_city: Lisbon /api/v1/communities/{communityTag}/members/{userId}/onboarding/rules: post: operationId: postMembersUserIdOnboardingRules summary: Accept the rules for a member description: |- **Required scope:** `APP_ONBOARDING` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). The acceptance is recorded as made through your app. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Apps x-required-scope: APP_ONBOARDING x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: userId in: path required: true description: User id or usertag. schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Onboarding' example: complete: false nextStep: rules steps: rules: required: true done: false data: required: true done: false rules: - id: r1 title: Be kind description: null order: 1 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_APP_ONBOARDING: summary: 'API key missing required scope: APP_ONBOARDING' value: error: 'API key missing required scope: APP_ONBOARDING' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Member_not_found: summary: Member not found value: error: Member not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/articles: get: operationId: getArticles summary: List published articles description: |- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Content x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: category schema: type: string - in: query required: false name: limit schema: type: integer - in: query required: false name: offset schema: type: integer responses: '200': description: Success. content: application/json: schema: type: object properties: articles: type: array items: $ref: '#/components/schemas/Article' pagination: $ref: '#/components/schemas/Pagination' example: articles: - id: art_1 title: Welcome to Acme slug: welcome-to-acme excerpt: What we are about. status: PUBLISHED bannerUrl: https://example.com/a.jpg publishedAt: '2026-09-01T09:00:00Z' pagination: total: 1 limit: 20 offset: 0 hasMore: false '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Community_not_found: summary: Community not found value: error: Community not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable post: operationId: postArticles summary: Create an article description: |- **Required scope:** `WRITE_ARTICLES` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Created as a draft, authored by the community founder. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Content x-required-scope: WRITE_ARTICLES x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '201': description: Success. content: application/json: schema: $ref: '#/components/schemas/Article' example: id: art_1 title: Welcome to Acme slug: welcome-to-acme excerpt: What we are about. status: DRAFT bannerUrl: https://example.com/a.jpg publishedAt: '2026-09-01T09:00:00Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Title_is_required_non_empty_string: summary: Title is required (non-empty string) value: error: Title is required (non-empty string) '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_does_not_belong_to_this_community: summary: API key does not belong to this community value: error: API key does not belong to this community API_key_missing_required_scope_WRITE_ARTICLES: summary: 'API key missing required scope: WRITE_ARTICLES' value: error: 'API key missing required scope: WRITE_ARTICLES' grantedScopes: - READ_PUBLIC '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Cannot_resolve_a_founder_user_for_this_community: summary: Cannot resolve a founder user for this community value: error: Cannot resolve a founder user for this community '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: title: type: string content: type: string description: HTML. excerpt: type: string metaTitle: type: string category: type: string bannerUrl: type: string keywords: type: array items: type: string references: type: array items: type: object properties: label: type: string url: type: string required: - label required: - title example: title: Welcome to Acme content:

Hello

bannerUrl: https://example.com/a.jpg /api/v1/communities/{communityTag}/articles/{articleId}: patch: operationId: patchArticlesArticleId summary: Update an article description: |- **Required scope:** `WRITE_ARTICLES` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Any subset of the fields. Setting `status` here skips the banner check that `/publish` enforces. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Content x-required-scope: WRITE_ARTICLES x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: articleId in: path required: true description: Article id. schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Article' example: id: art_1 title: Welcome to Acme slug: welcome-to-acme excerpt: What we are about. status: PUBLISHED bannerUrl: https://example.com/a.jpg publishedAt: '2026-09-01T09:00:00Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: No_editable_fields_in_request_body: summary: No editable fields in request body value: error: No editable fields in request body '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_ARTICLES: summary: 'API key missing required scope: WRITE_ARTICLES' value: error: 'API key missing required scope: WRITE_ARTICLES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Article_not_found_in_this_community: summary: Article not found in this community value: error: Article not found in this community '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: title: type: string content: type: string description: HTML. excerpt: type: string metaTitle: type: string category: type: string bannerUrl: type: string keywords: type: array items: type: string references: type: array items: type: object properties: label: type: string url: type: string required: - label status: type: string enum: - DRAFT - PUBLISHED example: excerpt: A shorter intro. /api/v1/communities/{communityTag}/articles/{articleId}/publish: post: operationId: postArticlesArticleIdPublish summary: Publish an article description: |- **Required scope:** `WRITE_ARTICLES` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Idempotent. Requires a `bannerUrl`. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Content x-required-scope: WRITE_ARTICLES x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: articleId in: path required: true description: Article id. schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Article' example: id: art_1 title: Welcome to Acme slug: welcome-to-acme excerpt: What we are about. status: PUBLISHED bannerUrl: https://example.com/a.jpg publishedAt: '2026-09-01T09:00:00Z' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_ARTICLES: summary: 'API key missing required scope: WRITE_ARTICLES' value: error: 'API key missing required scope: WRITE_ARTICLES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Article_not_found_in_this_community: summary: Article not found in this community value: error: Article not found in this community '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Article_must_have_a_bannerUrl_before_it_can_be_p: summary: Article must have a bannerUrl before it can be published value: error: Article must have a bannerUrl before it can be published '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/articles/{articleId}/unpublish: post: operationId: postArticlesArticleIdUnpublish summary: Unpublish an article description: |- **Required scope:** `WRITE_ARTICLES` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Idempotent; returns the article as a draft. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Content x-required-scope: WRITE_ARTICLES x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: articleId in: path required: true description: Article id. schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Article' example: id: art_1 title: Welcome to Acme slug: welcome-to-acme excerpt: What we are about. status: DRAFT bannerUrl: https://example.com/a.jpg publishedAt: '2026-09-01T09:00:00Z' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_ARTICLES: summary: 'API key missing required scope: WRITE_ARTICLES' value: error: 'API key missing required scope: WRITE_ARTICLES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Article_not_found_in_this_community: summary: Article not found in this community value: error: Article not found in this community '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/categories: get: operationId: getCategories summary: Community categories description: |- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. The taxonomy for one content type, with subcategories nested. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Content x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: true name: type schema: type: string enum: - PRODUCT - EVENT - COURSE - ARTICLE responses: '200': description: Success. content: application/json: schema: type: object properties: categories: type: array items: $ref: '#/components/schemas/Category' example: categories: - id: cat_1 name: Workshops sortOrder: 1 subcategories: [] '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: type_must_be_one_of_PRODUCT_EVENT_COURSE_ARTICLE: summary: 'type must be one of: PRODUCT, EVENT, COURSE, ARTICLE' value: error: 'type must be one of: PRODUCT, EVENT, COURSE, ARTICLE' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/courses: get: operationId: getCourses summary: List courses description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Courses share the product shape; fetch one with `GET /products/{idOrSku}`. `404` when courses are not enabled for the community. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Content x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: category schema: type: string - in: query required: false name: limit schema: type: integer - in: query required: false name: offset schema: type: integer responses: '200': description: Success. content: application/json: schema: type: object properties: courses: type: array items: $ref: '#/components/schemas/Product' pagination: $ref: '#/components/schemas/Pagination' example: courses: - id: prd_1 name: Acme Notebook sku: acme-notebook price: 2500 currency: EUR productType: COURSE seller: type: community name: Your Community usertag: null imageUrl: null variants: - id: tier_a5 name: A5 isOnSale: true state: on-sale capacity: 50 remaining: 12 soldOut: false memberPrice: null memberPriceMode: null publicMemberOffers: - segmentName: Pro price: 2000 mode: FLAT_OFF product: id: prd_1a sku: acme-notebook-a5 price: 2500 currency: EUR isRecurring: false recurringInterval: null pageUrl: https://your-community.cobuntu.com/marketplace/acme-notebook pagination: total: 1 limit: 20 offset: 0 hasMore: false '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not_found: summary: Not found value: error: Not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/branding: get: operationId: getBranding summary: Brand tokens description: |- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Content x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: branding: type: object properties: name: type: string iconUrl: type: - string - 'null' theme: type: object additionalProperties: true communityUrl: type: string example: branding: name: Acme iconUrl: https://example.com/icon.png theme: primaryColor: '#1a1a1a' communityUrl: https://your-community.cobuntu.com '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Community_not_found: summary: Community not found value: error: Community not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/places/cities: get: operationId: getPlacesCities summary: City autocomplete description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. City suggestions for a profile or sign-up form, so your site needs no maps key of its own. No member session needed. Always answers `200` (a lookup problem degrades to `predictions: []`); a `q` shorter than 2 characters answers `[]`; at most 6 suggestions. Debounce keystrokes: the limit is per visitor IP. **Rate limit:** 60 requests/min per client IP (checked before the API key), plus the per-key ceilings. tags: - Content x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 60 requests/min per client IP (checked before the API key), plus the per-key ceilings. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: true name: q schema: type: string maxLength: 100 description: What the visitor typed. Trimmed; cut to 100 characters. - in: query required: false name: lang schema: type: string description: Language for the suggestions, for example `en` or `pt-PT`. Defaults to English. responses: '200': description: Success. content: application/json: schema: type: object properties: predictions: type: array items: type: object properties: placeId: type: string description: type: string mainText: type: string secondaryText: type: string countryCode: type: - string - 'null' description: ISO 3166-1 alpha-2, or null when the country could not be resolved. example: predictions: - placeId: ChIJO_PkYRozGQ0R0DaQ5L3rAAQ description: Lisbon, Portugal mainText: Lisbon secondaryText: Portugal countryCode: PT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Too_many_place_lookups_slow_down: summary: Too many place lookups, slow down value: error: Too many place lookups, slow down predictions: [] RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/atlas/hotspots: get: operationId: getAtlasHotspots summary: List map hotspots description: |- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Content x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: category schema: type: string - in: query required: false name: subcategory schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: hotspots: type: array items: type: object additionalProperties: true example: hotspots: - id: hs_1 name: Acme Cafe latitude: 38.72 longitude: -9.14 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Atlas_is_not_enabled_for_this_community: summary: Atlas is not enabled for this community value: error: Atlas is not enabled for this community API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/atlas/hotspots/{hotspotId}: get: operationId: getAtlasHotspotsHotspotId summary: Get a map hotspot description: |- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Content x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: hotspotId in: path required: true description: Hotspot id. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object additionalProperties: true example: id: hs_1 name: Acme Cafe latitude: 38.72 longitude: -9.14 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Atlas_is_not_enabled_for_this_community: summary: Atlas is not enabled for this community value: error: Atlas is not enabled for this community API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Hotspot_not_found: summary: Hotspot not found value: error: Hotspot not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/atlas/categories: get: operationId: getAtlasCategories summary: Map hotspot categories description: |- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Content x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: categories: type: array items: type: object additionalProperties: true example: categories: - id: c1 name: Food '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Atlas_is_not_enabled_for_this_community: summary: Atlas is not enabled for this community value: error: Atlas is not enabled for this community API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/notifications: post: operationId: postNotifications summary: Send a notification to a member's bell description: >- **Required scope:** `WRITE_NOTIFICATIONS` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Idempotent on `eventId`: a replay returns `200` with `created: false`. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. Also 200 notifications per community per hour. tags: - Content x-required-scope: WRITE_NOTIFICATIONS x-key-type: secret x-rate-limit: >- 120 writes/min per API key, inside the 600 requests/min per key ceiling. Also 200 notifications per community per hour. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Replay of an existing eventId. content: application/json: schema: type: object properties: notification: type: object additionalProperties: true created: type: boolean eventKey: type: string example: notification: id: ntf_1 created: false eventKey: report-2026-10-13-alex '201': description: Success. content: application/json: schema: type: object properties: notification: type: object additionalProperties: true created: type: boolean eventKey: type: string example: notification: id: ntf_1 created: true eventKey: report-2026-10-13-alex '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: title_is_required: summary: title is required value: error: title is required title_exceeds_140_characters: summary: title exceeds 140 characters value: error: title exceeds 140 characters eventId_is_required: summary: eventId is required value: error: eventId is required url_must_be_an_https_or_http_link_or_a_site_rela: summary: url must be an https:// or http:// link, or a site-relative path value: error: url must be an https:// or http:// link, or a site-relative path '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Publishable_keys_cannot_call_this_endpoint: summary: Publishable keys cannot call this endpoint value: error: Publishable keys cannot call this endpoint hint: Use a secret key with the required scope. API_key_missing_required_scope_WRITE_NOTIFICATIO: summary: 'API key missing required scope: WRITE_NOTIFICATIONS' value: error: 'API key missing required scope: WRITE_NOTIFICATIONS' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Member_not_found: summary: Member not found value: error: Member not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Notification_limit_reached: summary: Notification limit reached value: error: Notification limit reached limit: 200 windowMinutes: 60 recent: 200 RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '502': description: Upstream unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Notification_service_unavailable: summary: Notification service unavailable value: error: Notification service unavailable '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: userId: type: string description: User id or usertag. title: type: string maxLength: 140 body: type: string maxLength: 500 eventId: type: string maxLength: 200 description: Your idempotency key. url: type: string description: http(s) link or a site-relative path starting with a single /. required: - userId - title - eventId example: userId: alex title: Your report is ready eventId: report-2026-10-13-alex url: /apps/reports /api/v1/communities/{communityTag}/feed/posts: post: operationId: postFeedPosts summary: Post to the community feed description: >- **Required scope:** `WRITE_FEED` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Posted as the community and labelled "via ". **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. Also 20 posts per community per hour. tags: - Content x-required-scope: WRITE_FEED x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. Also 20 posts per community per hour. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '201': description: Success. content: application/json: schema: type: object properties: post: type: object additionalProperties: true example: post: id: post_1 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: content_is_required: summary: content is required value: error: content is required '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Publishable_keys_cannot_call_this_endpoint: summary: Publishable keys cannot call this endpoint value: error: Publishable keys cannot call this endpoint hint: Use a secret key with the required scope. API_key_missing_required_scope_WRITE_FEED: summary: 'API key missing required scope: WRITE_FEED' value: error: 'API key missing required scope: WRITE_FEED' grantedScopes: - READ_PUBLIC '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Cannot_resolve_a_community_author: summary: Cannot resolve a community author value: error: Cannot resolve a community author '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Feed_post_limit_reached: summary: Feed post limit reached value: error: Feed post limit reached limit: 20 windowMinutes: 60 recent: 20 RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: content: type: string maxLength: 2000 chapterId: type: string eventId: type: string maxLength: 200 description: Your idempotency key. required: - content - chapterId - eventId example: content: New workshop dates are up! chapterId: ch_general eventId: post-2026-10-13 /api/v1/communities/{communityTag}/broadcasts: post: operationId: postBroadcasts summary: Send an email broadcast description: >- **Required scope:** `WRITE_BROADCASTS` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Creates and sends a campaign in one call. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. Also 5 broadcasts per community per 24 hours (including ones sent from the dashboard). tags: - Content x-required-scope: WRITE_BROADCASTS x-key-type: secret x-rate-limit: >- 120 writes/min per API key, inside the 600 requests/min per key ceiling. Also 5 broadcasts per community per 24 hours (including ones sent from the dashboard). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '201': description: Success. content: application/json: schema: type: object additionalProperties: true example: campaignId: cmp_1 sent: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: subject_and_htmlContent_are_required: summary: subject and htmlContent are required value: error: subject and htmlContent are required No_recipients_found: summary: No recipients found value: error: No recipients found campaignId: cmp_1 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_BROADCASTS: summary: 'API key missing required scope: WRITE_BROADCASTS' value: error: 'API key missing required scope: WRITE_BROADCASTS' grantedScopes: - READ_PUBLIC '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Campaign_could_not_be_sent_already_sent_or_not_f: summary: Campaign could not be sent (already sent or not found) value: error: Campaign could not be sent (already sent or not found) '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Broadcast_limit_reached: summary: Broadcast limit reached value: error: Broadcast limit reached limit: 5 windowHours: 24 recentSends: 5 RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: subject: type: string htmlContent: type: string description: The email body as HTML. previewText: type: string audience: type: string enum: - all - approved - pending default: all description: 'Without `segmentIds`: which memberships receive it.' segmentIds: type: array items: type: string description: Send to these membership tiers. Combine with `includeApproved` / `includePending`. includeApproved: type: boolean includePending: type: boolean required: - subject - htmlContent example: subject: October news htmlContent:

Hello members

segmentIds: - seg_pro /api/v1/communities/{communityTag}/products: get: operationId: getProducts summary: List products description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Optionally identify a member with `X-Cobuntu-Auth-Token` (or `X-Cobuntu-Member-Token`): members also see members-only products and their own member prices. Filters and sorting run over the whole visible set before paging. Walk `nextCursor` until `hasMore` is false. Courses are listed at `/courses`. Invalid parameters are `400 INVALID_INPUT` with the offending `field`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Commerce x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: q schema: type: string maxLength: 200 description: Name, sku, description, category names, tags, seller. Case- and accent-insensitive; every word must match. - in: query required: false name: minPrice schema: type: integer minimum: 0 description: Inclusive, smallest currency unit, on the card price (the cheapest live variant, else the product price). - in: query required: false name: maxPrice schema: type: integer minimum: 0 description: Inclusive. Below `minPrice` is `400` on `maxPrice`. - in: query required: false name: sort schema: type: string enum: - newest - price_asc - price_desc - name default: newest - in: query required: false name: price schema: type: string enum: - free - paid description: On the card price. - in: query required: false name: seller schema: type: string enum: - community - member - in: query required: false name: type schema: type: string enum: - DIGITAL - PHYSICAL description: Case-insensitive. - in: query required: false name: category schema: type: string description: Category id. An unknown id returns an empty page. - in: query required: false name: subcategory schema: type: string - in: query required: false name: limit schema: type: integer minimum: 1 maximum: 100 default: 20 - in: query required: false name: offset schema: type: integer minimum: 0 - in: query required: false name: cursor schema: type: string description: The previous page's `nextCursor`. Wins over `offset`. responses: '200': description: Success. content: application/json: schema: type: object properties: products: type: array items: $ref: '#/components/schemas/Product' pagination: $ref: '#/components/schemas/Pagination' hasMore: type: boolean nextCursor: type: - string - 'null' example: products: - id: prd_1 name: Acme Notebook sku: acme-notebook price: 2500 currency: EUR productType: DIGITAL seller: type: community name: Your Community usertag: null imageUrl: null variants: - id: tier_a5 name: A5 isOnSale: true state: on-sale capacity: 50 remaining: 12 soldOut: false memberPrice: null memberPriceMode: null publicMemberOffers: - segmentName: Pro price: 2000 mode: FLAT_OFF product: id: prd_1a sku: acme-notebook-a5 price: 2500 currency: EUR isRecurring: false recurringInterval: null pageUrl: https://your-community.cobuntu.com/marketplace/acme-notebook pagination: total: 1 limit: 20 offset: 0 hasMore: false hasMore: false nextCursor: null '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: maxPrice must be at least minPrice' value: error: maxPrice must be at least minPrice code: INVALID_INPUT field: maxPrice '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Community_not_found: summary: Community not found value: error: Community not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/products/facets: get: operationId: getProductsFacets summary: Product filter counts description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Optionally identify a member with `X-Cobuntu-Auth-Token` (or `X-Cobuntu-Member-Token`): members also see members-only products and their own member prices. Counts over the same visible set as the list, narrowed by `q`, `minPrice` and `maxPrice` only. Category, type, price and seller are the counted dimensions, so each count equals what that filter returns. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Commerce x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: q schema: type: string maxLength: 200 description: Name, sku, description, category names, tags, seller. Case- and accent-insensitive; every word must match. - in: query required: false name: minPrice schema: type: integer minimum: 0 description: Inclusive, smallest currency unit, on the card price (the cheapest live variant, else the product price). - in: query required: false name: maxPrice schema: type: integer minimum: 0 description: Inclusive. Below `minPrice` is `400` on `maxPrice`. responses: '200': description: Success. content: application/json: schema: type: object properties: facets: $ref: '#/components/schemas/ProductFacets' example: facets: total: 4 categories: - id: cat_kitchen name: Kitchen count: 1 subcategories: - id: sub_mugs name: Mugs count: 1 uncategorized: 1 type: DIGITAL: 3 PHYSICAL: 1 price: free: 1 paid: 3 seller: community: 2 member: 2 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: maxPrice must be at least minPrice' value: error: maxPrice must be at least minPrice code: INVALID_INPUT field: maxPrice '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Community_not_found: summary: Community not found value: error: Community not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/products/{idOrSku}: get: operationId: getProductsIdOrSku summary: Get a product (or course) description: >- **Required scope:** `READ_PUBLIC` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Optionally identify a member with `X-Cobuntu-Auth-Token` (or `X-Cobuntu-Member-Token`): members also see members-only products and their own member prices. By id or SKU. Returns the product object directly (not wrapped). `404` for a miss and for a product the viewer may not see. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Commerce x-required-scope: READ_PUBLIC x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: idOrSku in: path required: true description: Product id or SKU. schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Product' example: id: prd_1 name: Acme Notebook sku: acme-notebook price: 2500 currency: EUR productType: DIGITAL seller: type: community name: Your Community usertag: null imageUrl: null variants: - id: tier_a5 name: A5 isOnSale: true state: on-sale capacity: 50 remaining: 12 soldOut: false memberPrice: null memberPriceMode: null publicMemberOffers: - segmentName: Pro price: 2000 mode: FLAT_OFF product: id: prd_1a sku: acme-notebook-a5 price: 2500 currency: EUR isRecurring: false recurringInterval: null pageUrl: https://your-community.cobuntu.com/marketplace/acme-notebook '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_PUBLIC: summary: 'API key missing required scope: READ_PUBLIC' value: error: 'API key missing required scope: READ_PUBLIC' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Product_not_found: summary: Product not found value: error: Product not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/checkout: post: operationId: postCheckout summary: Create a marketplace checkout description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. Send either `items` (max 20 lines) or a guest `cartToken`, never both. A product with one variant needs no `tierId`. Event tickets are lines too: send the tier as `tierId` (or its `productId`) with optional `attendees`, at most 10 places across all events. A basket that cannot be paid in one checkout (instalment or recurring tickets, a physical item) is `400 BASKET_NEEDS_SPLIT` with `groups`: send each group's items as its own checkout, MAIN first. Approval tiers are charged now and held until the host decides. `taxId` is attached to the buyer's Stripe customer when there is one. With a member session, member prices apply. Guests may send `customer.email` for the order email. Redirect to `checkoutUrl`; an all-free order is booked at once (`isFreeCheckout: true`, no URL). Physical items: the address is collected at payment and limited to the seller's country. **Rate limit:** 100 requests per 15 min per client IP, plus the per-key ceilings. tags: - Checkout x-required-scope: WRITE_SALES x-required-scope-note: >- The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. x-key-type: publishable x-rate-limit: 100 requests per 15 min per client IP, plus the per-key ceilings. x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: checkoutUrl: type: - string - 'null' sessionId: type: - string - 'null' transactionId: type: string isFreeCheckout: type: boolean requiresShipping: type: boolean tickets: type: array items: type: object description: The tickets created by this order. example: checkoutUrl: https://checkout.stripe.com/c/pay/cs_test_123 sessionId: cs_test_123 transactionId: txn_1 isFreeCheckout: false requiresShipping: false '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: ITEMS_REQUIRED: summary: 'ITEMS_REQUIRED: items or cartToken is required' value: error: items or cartToken is required code: ITEMS_REQUIRED AMBIGUOUS_BODY: summary: 'AMBIGUOUS_BODY: Send items or cartToken, not both' value: error: Send items or cartToken, not both code: AMBIGUOUS_BODY TIER_REQUIRED: summary: 'TIER_REQUIRED: This product has several variants: send tierId' value: error: 'This product has several variants: send tierId' code: TIER_REQUIRED INVALID_QUANTITY: summary: 'INVALID_QUANTITY: quantity must be 1-10' value: error: quantity must be 1-10 code: INVALID_QUANTITY MIXED_CURRENCY: summary: 'MIXED_CURRENCY: All items must share one currency' value: error: All items must share one currency code: MIXED_CURRENCY PHYSICAL_CART_MUST_BE_ALONE: summary: 'PHYSICAL_CART_MUST_BE_ALONE: A physical item is bought on its own' value: error: A physical item is bought on its own code: PHYSICAL_CART_MUST_BE_ALONE SHIPPING_COUNTRY_NOT_SERVED: summary: 'SHIPPING_COUNTRY_NOT_SERVED: The seller does not ship there' value: error: The seller does not ship there code: SHIPPING_COUNTRY_NOT_SERVED allowedCountries: - PT - ES INVALID_RETURN_URL: summary: 'INVALID_RETURN_URL: successUrl and cancelUrl must be absolute http(s) URLs' value: error: successUrl and cancelUrl must be absolute http(s) URLs code: INVALID_RETURN_URL FORM_ANSWERS_REQUIRED: summary: 'FORM_ANSWERS_REQUIRED: Missing required fields' value: error: Missing required fields code: FORM_ANSWERS_REQUIRED missingFields: - f_size BASKET_NEEDS_SPLIT: summary: 'BASKET_NEEDS_SPLIT: This basket is paid in steps' value: error: This basket is paid in steps code: BASKET_NEEDS_SPLIT groups: - lines: - 1 - 2 mode: payment reason: MAIN requiresAccount: false - lines: - 0 mode: subscription reason: INSTALMENTS requiresAccount: true TOO_MANY_TICKETS: summary: 'TOO_MANY_TICKETS: At most 10 places per order' value: error: At most 10 places per order code: TOO_MANY_TICKETS max: 10 INVALID_ATTENDEES: summary: 'INVALID_ATTENDEES: Invalid attendees' value: error: Invalid attendees code: INVALID_ATTENDEES index: 0 DUPLICATE_TIER: summary: 'DUPLICATE_TIER: Same tier twice: raise the quantity' value: error: 'Same tier twice: raise the quantity' code: DUPLICATE_TIER index: 1 INVALID_EVENTS: summary: 'INVALID_EVENTS: Invalid events' value: error: Invalid events code: INVALID_EVENTS eventId: evt_1 INVALID_INVITATION_TOKEN: summary: 'INVALID_INVITATION_TOKEN: Invalid invitation token' value: error: Invalid invitation token code: INVALID_INVITATION_TOKEN INVALID_DONATION: summary: 'INVALID_DONATION: Invalid donation' value: error: Invalid donation code: INVALID_DONATION QUANTITY_LOCKED: summary: 'QUANTITY_LOCKED: Instalment tickets are one per order' value: error: Instalment tickets are one per order code: QUANTITY_LOCKED index: 0 CUSTOM_AMOUNT_REQUIRED: summary: 'CUSTOM_AMOUNT_REQUIRED: Enter an amount' value: error: Enter an amount code: CUSTOM_AMOUNT_REQUIRED index: 0 CUSTOM_AMOUNT_TOO_LOW: summary: 'CUSTOM_AMOUNT_TOO_LOW: Below the minimum' value: error: Below the minimum code: CUSTOM_AMOUNT_TOO_LOW minAmount: 500 index: 0 CUSTOM_AMOUNT_NOT_ACCEPTED: summary: 'CUSTOM_AMOUNT_NOT_ACCEPTED: This tier has a fixed price' value: error: This tier has a fixed price code: CUSTOM_AMOUNT_NOT_ACCEPTED index: 0 INVALID_TAX_ID: summary: 'INVALID_TAX_ID: The VAT number was rejected' value: error: The VAT number was rejected code: INVALID_TAX_ID TAX_ID_COUNTRY_UNSUPPORTED: summary: 'TAX_ID_COUNTRY_UNSUPPORTED: No VAT number type for this country' value: error: No VAT number type for this country code: TAX_ID_COUNTRY_UNSUPPORTED '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SESSION_REQUIRED: summary: 'SESSION_REQUIRED: This product needs an account' value: error: This product needs an account code: SESSION_REQUIRED API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: MEMBERS_ONLY: summary: 'MEMBERS_ONLY: Members only' value: error: Members only code: MEMBERS_ONLY API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: PRODUCT_NOT_FOUND: summary: 'PRODUCT_NOT_FOUND: Product not found' value: error: Product not found code: PRODUCT_NOT_FOUND TIER_NOT_FOUND: summary: 'TIER_NOT_FOUND: Variant not found' value: error: Variant not found code: TIER_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SOLD_OUT: summary: 'SOLD_OUT: Sold out' value: error: Sold out code: SOLD_OUT tierId: tier_a5 ALREADY_PURCHASED: summary: 'ALREADY_PURCHASED: Already purchased' value: error: Already purchased code: ALREADY_PURCHASED TIER_NOT_ON_SALE: summary: 'TIER_NOT_ON_SALE: Not on sale' value: error: Not on sale code: TIER_NOT_ON_SALE state: SCHEDULED opensAt: '2026-11-01T10:00:00Z' index: 0 TIER_FULL: summary: 'TIER_FULL: Not enough places left' value: error: Not enough places left code: TIER_FULL remaining: 1 index: 0 '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/BasketItem' maxItems: 20 cartToken: type: string description: A guest cart token (`X-Cobuntu-Cart-Token`). customer: type: object properties: email: type: string format: email name: type: string shippingAddress: type: object properties: country: type: string description: ISO 3166-1 alpha-2. successUrl: type: string format: uri description: '`{CHECKOUT_SESSION_ID}` is expanded.' cancelUrl: type: string format: uri events: type: object additionalProperties: type: object properties: chatOptOut: type: boolean invitationToken: type: string description: Per-event options keyed by event id. Each event must have a ticket in the basket. donation: type: object properties: amount: type: integer description: In the smallest currency unit (cents). eventId: type: string description: Ties the donation to a ticket event in the basket. taxId: type: object properties: value: type: string country: type: string description: ISO 3166-1 alpha-2, any case. required: - successUrl - cancelUrl example: items: - sku: acme-notebook tierId: tier_a5 quantity: 2 customer: email: alex@example.com successUrl: https://example.com/thanks?session={CHECKOUT_SESSION_ID} cancelUrl: https://example.com/basket /api/v1/communities/{communityTag}/checkout/quote: post: operationId: postCheckoutQuote summary: Price a basket description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. Send either `items` (max 20 lines) or a guest `cartToken`, never both. A product with one variant needs no `tierId`. Event tickets are lines too: send the tier as `tierId` (or its `productId`) with optional `attendees`, at most 10 places across all events. Read-only: safe on every basket render. Never answers `BASKET_NEEDS_SPLIT`: it returns `groups`, and the totals are summed over them. `taxId` is accepted and ignored. `total` excludes tax. Any failure other than a basket error is `422` (a quote never breaks the basket). **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Checkout x-required-scope: WRITE_SALES x-required-scope-note: >- The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. x-key-type: publishable x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/Quote' example: lines: - productId: prd_1 sku: acme-notebook tierId: tier_a5 name: Acme Notebook tierName: A5 unitPrice: 2500 quantity: 2 lineTotal: 5000 currency: EUR appliedMemberPricingId: null listPrice: 2500 isCustomAmount: false offersDonation: false productType: DIGITAL maxQuantity: 10 index: 0 kind: PRODUCT eventId: null requiresApproval: false subtotal: 5000 shipping: 0 total: 5000 currency: EUR memberSavings: 0 offersDonation: false requiresShipping: false parcelClass: null allowedShippingCountries: null groups: - lines: - 0 mode: payment reason: MAIN requiresAccount: false subtotal: 5000 shipping: 0 total: 5000 currency: EUR '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: ITEMS_REQUIRED: summary: 'ITEMS_REQUIRED: items or cartToken is required' value: error: items or cartToken is required code: ITEMS_REQUIRED AMBIGUOUS_BODY: summary: 'AMBIGUOUS_BODY: Send items or cartToken, not both' value: error: Send items or cartToken, not both code: AMBIGUOUS_BODY TIER_REQUIRED: summary: 'TIER_REQUIRED: This product has several variants: send tierId' value: error: 'This product has several variants: send tierId' code: TIER_REQUIRED INVALID_QUANTITY: summary: 'INVALID_QUANTITY: quantity must be 1-10' value: error: quantity must be 1-10 code: INVALID_QUANTITY MIXED_CURRENCY: summary: 'MIXED_CURRENCY: All items must share one currency' value: error: All items must share one currency code: MIXED_CURRENCY PHYSICAL_CART_MUST_BE_ALONE: summary: 'PHYSICAL_CART_MUST_BE_ALONE: A physical item is bought on its own' value: error: A physical item is bought on its own code: PHYSICAL_CART_MUST_BE_ALONE SHIPPING_COUNTRY_NOT_SERVED: summary: 'SHIPPING_COUNTRY_NOT_SERVED: The seller does not ship there' value: error: The seller does not ship there code: SHIPPING_COUNTRY_NOT_SERVED allowedCountries: - PT - ES TOO_MANY_TICKETS: summary: 'TOO_MANY_TICKETS: At most 10 places per order' value: error: At most 10 places per order code: TOO_MANY_TICKETS max: 10 INVALID_ATTENDEES: summary: 'INVALID_ATTENDEES: Invalid attendees' value: error: Invalid attendees code: INVALID_ATTENDEES index: 0 DUPLICATE_TIER: summary: 'DUPLICATE_TIER: Same tier twice: raise the quantity' value: error: 'Same tier twice: raise the quantity' code: DUPLICATE_TIER index: 1 INVALID_EVENTS: summary: 'INVALID_EVENTS: Invalid events' value: error: Invalid events code: INVALID_EVENTS eventId: evt_1 INVALID_INVITATION_TOKEN: summary: 'INVALID_INVITATION_TOKEN: Invalid invitation token' value: error: Invalid invitation token code: INVALID_INVITATION_TOKEN INVALID_DONATION: summary: 'INVALID_DONATION: Invalid donation' value: error: Invalid donation code: INVALID_DONATION QUANTITY_LOCKED: summary: 'QUANTITY_LOCKED: Instalment tickets are one per order' value: error: Instalment tickets are one per order code: QUANTITY_LOCKED index: 0 CUSTOM_AMOUNT_REQUIRED: summary: 'CUSTOM_AMOUNT_REQUIRED: Enter an amount' value: error: Enter an amount code: CUSTOM_AMOUNT_REQUIRED index: 0 CUSTOM_AMOUNT_TOO_LOW: summary: 'CUSTOM_AMOUNT_TOO_LOW: Below the minimum' value: error: Below the minimum code: CUSTOM_AMOUNT_TOO_LOW minAmount: 500 index: 0 CUSTOM_AMOUNT_NOT_ACCEPTED: summary: 'CUSTOM_AMOUNT_NOT_ACCEPTED: This tier has a fixed price' value: error: This tier has a fixed price code: CUSTOM_AMOUNT_NOT_ACCEPTED index: 0 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: PRODUCT_NOT_FOUND: summary: 'PRODUCT_NOT_FOUND: Product not found' value: error: Product not found code: PRODUCT_NOT_FOUND TIER_NOT_FOUND: summary: 'TIER_NOT_FOUND: Variant not found' value: error: Variant not found code: TIER_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: TIER_NOT_ON_SALE: summary: 'TIER_NOT_ON_SALE: Not on sale' value: error: Not on sale code: TIER_NOT_ON_SALE state: SCHEDULED opensAt: '2026-11-01T10:00:00Z' index: 0 TIER_FULL: summary: 'TIER_FULL: Not enough places left' value: error: Not enough places left code: TIER_FULL remaining: 1 index: 0 '422': description: Error. content: application/json: schema: $ref: '#/components/schemas/Error' examples: QUOTE_FAILED: summary: 'QUOTE_FAILED: Could not quote this basket' value: error: Could not quote this basket code: QUOTE_FAILED '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/BasketItem' maxItems: 20 cartToken: type: string description: A guest cart token (`X-Cobuntu-Cart-Token`). shippingAddress: type: object properties: country: type: string customer: type: object properties: email: type: string format: email events: type: object additionalProperties: type: object properties: chatOptOut: type: boolean invitationToken: type: string description: Per-event options keyed by event id. Each event must have a ticket in the basket. donation: type: object properties: amount: type: integer description: In the smallest currency unit (cents). eventId: type: string description: Ties the donation to a ticket event in the basket. taxId: type: object properties: value: type: string country: type: string description: ISO 3166-1 alpha-2, any case. example: items: - sku: acme-notebook tierId: tier_a5 quantity: 2 - tierId: tier_general quantity: 2 attendees: - {} - name: Sam Lee email: sam@example.com /api/v1/communities/{communityTag}/me/purchases: get: operationId: getMePurchases summary: The member's product purchases description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Newest first. Tickets are in `me/tickets`, memberships in `me/membership`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: limit schema: type: integer minimum: 1 maximum: 50 default: 20 - in: query required: false name: offset schema: type: integer minimum: 0 responses: '200': description: Success. content: application/json: schema: type: object properties: purchases: type: array items: $ref: '#/components/schemas/Purchase' total: type: integer hasMore: type: boolean example: purchases: - saleId: sale_1 transactionId: txn_1 purchasedAt: '2026-10-01T10:00:00Z' product: id: prd_1 sku: acme-notebook name: Acme Notebook imageUrl: null productType: DIGITAL variant: tierId: tier_a5 name: A5 quantity: 1 amount: 2500 shippingAmount: 0 currency: EUR refundStatus: NONE approvalStatus: null shippedAt: null deliveredAt: null refundable: true refundReason: null refundWindowEndsAt: '2026-10-15T10:00:00Z' invoiceUrl: /api/v1/communities/your-community/me/sales/sale_1/invoice receiptUrl: /api/v1/communities/your-community/me/sales/sale_1/receipt downloads: - attachmentId: att_1 name: notebook.pdf kind: FILE mimeType: application/pdf fileSize: 1048576 maxDownloads: 5 downloadsUsed: 1 remainingDownloads: 4 url: null downloadUrl: /api/v1/communities/your-community/me/purchases/sale_1/attachments/att_1/download total: 1 hasMore: false '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Invalid session' value: error: Invalid session code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: A secret key is required' value: error: A secret key is required code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/purchases/{saleId}/attachments/{attachmentId}/download: get: operationId: getMePurchasesSaleIdAttachmentsAttachmentIdDownload summary: Download a purchased file description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Returns a signed URL valid for about 5 minutes. Each call counts one download against the variant's `maxDownloads`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: saleId in: path required: true description: Sale id. schema: type: string - name: attachmentId in: path required: true description: Attachment id from `downloads[]`. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: url: type: string expiresAt: type: string format: date-time maxDownloads: type: - integer - 'null' remainingDownloads: type: - integer - 'null' example: url: https://storage.example/signed expiresAt: '2026-10-14T12:05:00Z' maxDownloads: 5 remainingDownloads: 3 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NOT_A_FILE: summary: 'NOT_A_FILE: This deliverable is a link' value: error: This deliverable is a link code: NOT_A_FILE '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: ACCESS_REVOKED: summary: 'ACCESS_REVOKED: This purchase has been refunded' value: error: This purchase has been refunded code: ACCESS_REVOKED NOT_APPROVED: summary: 'NOT_APPROVED: This purchase is not approved yet' value: error: This purchase is not approved yet code: NOT_APPROVED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SALE_NOT_FOUND: summary: 'SALE_NOT_FOUND: Purchase not found' value: error: Purchase not found code: SALE_NOT_FOUND ATTACHMENT_NOT_FOUND: summary: 'ATTACHMENT_NOT_FOUND: File not found for this purchase' value: error: File not found for this purchase code: ATTACHMENT_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: DOWNLOAD_LIMIT_REACHED: summary: 'DOWNLOAD_LIMIT_REACHED: All downloads of this file have been used' value: error: All downloads of this file have been used code: DOWNLOAD_LIMIT_REACHED maxDownloads: 5 RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/sales/{saleId}/invoice: get: operationId: getMeSalesSaleIdInvoice summary: Invoice for a sale description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Products, tickets and memberships alike. The hosted invoice page URL; add `?redirect=1` for a `302` to it. Free orders have none. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: saleId in: path required: true description: Sale id. schema: type: string - in: query required: false name: redirect schema: type: string enum: - '1' responses: '200': description: Success. content: application/json: schema: type: object properties: url: type: string example: url: https://invoice.stripe.com/i/acct_1/inv_1 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVOICE_NOT_AVAILABLE: summary: 'INVOICE_NOT_AVAILABLE: The invoice is not available yet' value: error: The invoice is not available yet code: INVOICE_NOT_AVAILABLE SALE_NOT_FOUND: summary: 'SALE_NOT_FOUND: Sale not found' value: error: Sale not found code: SALE_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/sales/{saleId}/receipt: get: operationId: getMeSalesSaleIdReceipt summary: Receipt PDF for a sale description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. A PDF generated on request, naming the actual seller. Not cached. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: saleId in: path required: true description: Sale id. schema: type: string responses: '200': description: Success. content: application/pdf: schema: type: string format: binary '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SALE_NOT_FOUND: summary: 'SALE_NOT_FOUND: Sale not found' value: error: Sale not found code: SALE_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/events: get: operationId: getMeEvents summary: The member's events description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Events of this community (owned by it or listed in it), grouped. attending and attended: the member holds an APPROVED or PENDING place. hosting and hosted: the member is a host (drafts excluded). An event both hosted and attended is in both groups. Past means the end date (else the start date) is before now; an event with no date is upcoming. Upcoming groups are soonest first, past groups most recent first. A group excluded by `when` or `role` is `[]`. Per-place detail (companions, refundability) is in `me/tickets`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: when schema: type: string enum: - upcoming - past - in: query required: false name: role schema: type: string enum: - attending - hosting responses: '200': description: Success. content: application/json: schema: type: object properties: attending: type: array items: $ref: '#/components/schemas/MemberEvent' attended: type: array items: $ref: '#/components/schemas/MemberEvent' hosting: type: array items: $ref: '#/components/schemas/MemberEvent' hosted: type: array items: $ref: '#/components/schemas/MemberEvent' example: attending: - id: evt_1 slug: summer-meetup name: Summer Meetup startDate: '2026-11-20T18:00:00Z' endDate: '2026-11-20T21:00:00Z' bannerUrl: null status: PUBLISHED attendanceStatus: APPROVED transactionId: txn_1 isHosting: false attended: [] hosting: [] hosted: [] '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: when must be upcoming or past' value: error: when must be upcoming or past code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable post: operationId: postMeEvents summary: Create an event as the member description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. One of the routes behind the embedded create-event wizard (`@cobuntu/embed/event-wizard`). The wizard's create body. The event is always linked to this community. `requestListing` absent means true. `bannerUrl` is the cropped banner as a data URL. Paid tickets with a listing need the right Stripe: `400 STRIPE_REQUIRED` with `stripeScope`. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '201': description: Success. content: application/json: schema: type: object additionalProperties: true properties: id: type: string slug: type: string name: type: string example: id: evt_1 slug: summer-meetup name: Summer Meetup '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: STRIPE_REQUIRED: summary: 'STRIPE_REQUIRED: Connect Stripe to sell paid tickets' value: error: Connect Stripe to sell paid tickets code: STRIPE_REQUIRED stripeScope: personal INVALID_INPUT: summary: 'INVALID_INPUT: name is required' value: error: name is required code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: FORBIDDEN: summary: 'FORBIDDEN: You cannot host events in this community' value: error: You cannot host events in this community code: FORBIDDEN SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object additionalProperties: true properties: name: type: string description: type: string startDate: type: string format: date-time endDate: type: string format: date-time timezone: type: string locations: type: array items: type: object tiers: type: array items: type: object accessibility: type: string viewability: type: string viewTierIds: type: array items: type: string buyTierIds: type: array items: type: string categoryId: type: - string - 'null' tagIds: type: array items: type: string bannerUrl: type: - string - 'null' communityOwnership: type: boolean ownership: type: string enum: - personal publish: type: boolean requestListing: type: boolean packageId: type: - string - 'null' draftId: type: - string - 'null' asDraft: type: boolean draftStep: type: string required: - name example: name: Summer Meetup startDate: '2026-11-20T18:00:00Z' endDate: '2026-11-20T21:00:00Z' timezone: Europe/Lisbon tiers: - name: General price: 0 requestListing: true packageId: pkg_1 draftId: drf_1 /api/v1/communities/{communityTag}/me/ledger: get: operationId: getMeLedger summary: The member's ledger description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Purchases, refunds received and sales made through this community, newest first. A refunded sale keeps its entry, with `status` and `refund`. Payouts to a bank account are not listed (one payout can span several communities); each SALE carries its own `payout` state instead. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: type schema: type: string enum: - purchase - refund - sale - in: query required: false name: from schema: type: string format: date-time description: Inclusive. - in: query required: false name: to schema: type: string format: date-time description: Inclusive. - in: query required: false name: limit schema: type: integer minimum: 1 maximum: 100 default: 20 - in: query required: false name: offset schema: type: integer minimum: 0 default: 0 responses: '200': description: Success. content: application/json: schema: type: object properties: entries: type: array items: $ref: '#/components/schemas/LedgerEntry' total: type: integer description: After filters. hasMore: type: boolean summary: $ref: '#/components/schemas/LedgerSummary' example: entries: - id: purchase:sale_1 type: PURCHASE direction: out amount: 3000 currency: EUR date: '2026-10-01T10:00:00Z' saleId: sale_1 transactionId: txn_1 item: kind: product name: Acme Notebook counterpart: null status: NONE fees: null payout: null refund: null invoiceUrl: /api/v1/communities/your-community/me/sales/sale_1/invoice receiptUrl: /api/v1/communities/your-community/me/sales/sale_1/receipt invoiceAvailable: true total: 1 hasMore: false summary: totals: - currency: EUR spent: 3000 refunded: 0 earned: 0 fees: 0 pendingPayouts: 0 readyForPayout: 0 inEscrowPeriod: 0 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: type must be purchase, refund or sale' value: error: type must be purchase, refund or sale code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/library: get: operationId: getMeLibrary summary: The member's library description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. Items the member owns that live in this community, with their downloads. Refunded purchases are not included. File downloads go through `me/purchases/{saleId}/attachments/{attachmentId}/download`, where download limits apply. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/LibraryItem' total: type: integer example: items: - saleId: sale_1 purchasedAt: '2026-10-01T10:00:00Z' awaitingApproval: false product: id: prd_1 sku: acme-notebook name: Acme Notebook description: null imageUrl: null productType: DIGITAL creator: name: Alex Doe usertag: alex avatar: null downloads: - attachmentId: att_1 name: notebook.pdf kind: FILE mimeType: application/pdf fileSize: 1048576 url: null downloadUrl: /api/v1/communities/your-community/me/purchases/sale_1/attachments/att_1/download total: 1 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/drafts: get: operationId: getMeDrafts summary: The member's event drafts description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. One of the routes behind the embedded create-event wizard (`@cobuntu/embed/event-wizard`). Unfinished event wizards: personal drafts and this community's, never another community's. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: kind schema: type: string enum: - event description: Optional; anything else is 400. responses: '200': description: Success. content: application/json: schema: type: object properties: drafts: type: array items: $ref: '#/components/schemas/EventDraftSummary' example: drafts: - id: drf_1 kind: event name: Summer Meetup draftStep: details updatedAt: '2026-10-20T10:00:00Z' communityId: null productType: null '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: kind must be event' value: error: kind must be event code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/drafts/event/{id}: get: operationId: getMeDraftsEventId summary: Read an event draft description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. One of the routes behind the embedded create-event wizard (`@cobuntu/embed/event-wizard`). The stored draft row, as the wizard resumes it. 404 also for a draft of another community. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: id in: path required: true description: id schema: type: string responses: '200': description: Success. content: application/json: schema: type: object additionalProperties: true example: id: drf_1 name: Summer Meetup draftStep: details communityId: null '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: FORBIDDEN: summary: 'FORBIDDEN: Another member''s draft' value: error: Another member's draft code: FORBIDDEN SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NOT_FOUND: summary: 'NOT_FOUND: Draft not found' value: error: Draft not found code: NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: CONFLICT: summary: 'CONFLICT: No longer a draft' value: error: No longer a draft code: CONFLICT '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable put: operationId: putMeDraftsEventId summary: Save an event draft description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. One of the routes behind the embedded create-event wizard (`@cobuntu/embed/event-wizard`). Upsert: the caller mints the id. 409 means the draft has been created as an event: stop autosaving. `communityId` is this community (a community-owned draft, needs EVENTS_CREATE) or null. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: id in: path required: true description: id schema: type: string responses: '200': description: Success. content: application/json: schema: type: object additionalProperties: true example: id: drf_1 name: Summer Meetup '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: name is required' value: error: name is required code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: communityId must be this community' value: error: communityId must be this community code: WRONG_COMMUNITY FORBIDDEN: summary: 'FORBIDDEN: Another member''s draft' value: error: Another member's draft code: FORBIDDEN SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NOT_FOUND: summary: 'NOT_FOUND: Draft not found' value: error: Draft not found code: NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: CONFLICT: summary: 'CONFLICT: No longer a draft' value: error: No longer a draft code: CONFLICT '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: type: string draftStep: type: string startDate: type: string format: date-time endDate: type: string format: date-time timezone: type: string price: type: number currency: type: string communityId: type: - string - 'null' required: - name example: name: Summer Meetup draftStep: details communityId: null delete: operationId: deleteMeDraftsEventId summary: Discard an event draft description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. One of the routes behind the embedded create-event wizard (`@cobuntu/embed/event-wizard`). Answers 204 with no body. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: id in: path required: true description: id schema: type: string responses: '204': description: Success. content: application/json: schema: type: 'null' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: FORBIDDEN: summary: 'FORBIDDEN: Another member''s draft' value: error: Another member's draft code: FORBIDDEN SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NOT_FOUND: summary: 'NOT_FOUND: Draft not found' value: error: Draft not found code: NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: CONFLICT: summary: 'CONFLICT: No longer a draft' value: error: No longer a draft code: CONFLICT '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/packages: get: operationId: getMePackages summary: Fee packages the member may host under description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. One of the routes behind the embedded create-event wizard (`@cobuntu/embed/event-wizard`). The arrangements offered for a personal listing. Empty means the community proposes terms at review. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: productType schema: type: string enum: - EVENT default: EVENT responses: '200': description: Success. content: application/json: schema: type: object properties: packages: type: array items: $ref: '#/components/schemas/MemberPackage' example: packages: - id: pkg_1 name: Members description: The community keeps 20% of each sale. rate: 20 sortOrder: 0 segmentId: seg_pro '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/stripe: get: operationId: getMeStripe summary: The member's own Stripe description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. One of the routes behind the embedded create-event wizard (`@cobuntu/embed/event-wizard`). Live from Stripe. Ready for paid tickets means `connected && chargesEnabled`. `connectUrl` opens the community app's payouts hub, where the member connects or finishes their account. No account ids or bank details. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: connected: type: boolean chargesEnabled: type: boolean payoutsEnabled: type: boolean status: type: - string - 'null' connectionStage: type: - string - 'null' country: type: - string - 'null' currency: type: - string - 'null' connectUrl: type: string example: connected: false chargesEnabled: false payoutsEnabled: false status: null connectionStage: null country: null currency: null connectUrl: https://your-community.cobuntu.com/my-payouts/onboard '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/permissions: get: operationId: getMePermissions summary: The member's create permissions description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. One of the routes behind the embedded create-event wizard (`@cobuntu/embed/event-wizard`). `canCreateForCommunity` (EVENTS_CREATE) offers the choice to create on the community's behalf; `memberCreate` is the gate for hosting at all. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: permissions: type: array items: type: string canCreateForCommunity: type: boolean memberCreate: type: object properties: allowed: type: boolean reason: type: string enum: - ok - role_grant - toggle_off - tier_locked - not_member example: permissions: [] canCreateForCommunity: false memberCreate: allowed: true reason: ok '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/me/events/{eventId}/donations: put: operationId: putMeEventsEventIdDonations summary: Set donations on a hosted event description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. One of the routes behind the embedded create-event wizard (`@cobuntu/embed/event-wizard`). Donation settings, or `{ "enabled": false }`. The member must host the event. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: eventId in: path required: true description: eventId schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: donationConfig: type: - object - 'null' additionalProperties: true example: donationConfig: null '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: Invalid donation config' value: error: Invalid donation config code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: FORBIDDEN: summary: 'FORBIDDEN: Not a host of this event' value: error: Not a host of this event code: FORBIDDEN SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NOT_FOUND: summary: 'NOT_FOUND: Event not found' value: error: Event not found code: NOT_FOUND COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object additionalProperties: true properties: enabled: type: boolean example: enabled: false /api/v1/communities/{communityTag}/me/tags: get: operationId: getMeTags summary: Search event tags description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. One of the routes behind the embedded create-event wizard (`@cobuntu/embed/event-wizard`). At most 10. An empty `q` answers `[]`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: q schema: type: string responses: '200': description: Success. content: application/json: schema: type: array items: type: object properties: id: type: string name: type: string searchName: type: string example: - id: tag_1 name: Music searchName: music '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable post: operationId: postMeTags summary: Create an event tag description: >- **Required scope:** `MEMBER_AUTH` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Requires a **secret** key with `MEMBER_AUTH` and the member session in `X-Cobuntu-Auth-Token`. The member is identified only by the session, never by an id in the URL. The session must belong to an accepted member of the community. One of the routes behind the embedded create-event wizard (`@cobuntu/embed/event-wizard`). 201 with a new tag, or 200 with the existing one (case-insensitive). Up to 20 letters, digits and spaces. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Members x-required-scope: MEMBER_AUTH x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. x-member-session: required security: - ApiKey: [] MemberSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '201': description: Success. content: application/json: schema: type: object properties: id: type: string name: type: string searchName: type: string example: id: tag_1 name: Music searchName: music '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: Tag names are up to 20 letters, digits and spaces' value: error: Tag names are up to 20 letters, digits and spaces code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_SESSION: summary: 'INVALID_SESSION: Session is missing, expired or not valid for this community' value: error: Session is missing, expired or not valid for this community code: INVALID_SESSION API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_MEMBER_AUTH: summary: 'API key missing required scope: MEMBER_AUTH' value: error: 'API key missing required scope: MEMBER_AUTH' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: CONFLICT: summary: 'CONFLICT: Tag was created concurrently' value: error: Tag was created concurrently code: CONFLICT '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: name: type: string maxLength: 20 required: - name example: name: Music /api/v1/communities/{communityTag}/products/{sku}/sales/me/refund: post: operationId: postProductsSkuSalesMeRefund summary: Buyer refunds their own product purchase description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. Member session, or a guest's order-link `token`. The sale must be the buyer's, of this product (any variant), in this community. `amount` is in the smallest currency unit; omit it for a full refund. Stripe fees follow the refund policy. **Rate limit:** 100 requests per 15 min per client IP, plus the per-key ceilings. tags: - Checkout x-required-scope: WRITE_SALES x-required-scope-note: >- The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. x-key-type: publishable x-rate-limit: 100 requests per 15 min per client IP, plus the per-key ceilings. x-member-session: optional security: - ApiKey: [] MemberSession: [] - ApiKey: [] MemberToken: [] - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: sku in: path required: true description: Product SKU. schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/RefundResult' example: refundId: ref_1 status: PENDING amount: 2500 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: reason is required' value: error: reason is required code: INVALID_INPUT INVALID_AMOUNT: summary: 'INVALID_AMOUNT: amount must be a positive integer' value: error: amount must be a positive integer code: INVALID_AMOUNT NOT_ELIGIBLE: summary: 'NOT_ELIGIBLE: The refund window is over' value: error: The refund window is over code: NOT_ELIGIBLE '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SESSION_REQUIRED: summary: 'SESSION_REQUIRED: A member session or the order link token is required' value: error: A member session or the order link token is required code: SESSION_REQUIRED API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LINK_MISMATCH: summary: 'LINK_MISMATCH: This link is for another order' value: error: This link is for another order code: LINK_MISMATCH API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SALE_NOT_FOUND: summary: 'SALE_NOT_FOUND: Sale not found' value: error: Sale not found code: SALE_NOT_FOUND '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: REFUND_PENDING: summary: 'REFUND_PENDING: A refund is already pending' value: error: A refund is already pending code: REFUND_PENDING '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: saleId: type: string reason: type: string maxLength: 2000 amount: type: integer description: Omit for a full refund. In the smallest currency unit (cents). token: type: string description: Guest order-link token. required: - saleId - reason example: saleId: sale_1 reason: Wrong size /api/v1/communities/{communityTag}/sales/manage: get: operationId: getSalesManage summary: A guest's order from the order link description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. Guests (no account) get a "Manage your order" link in the order email carrying a signed token (valid 90 days). Read the order with it; refund with `POST /products/{sku}/sales/me/refund` and body `token`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Checkout x-required-scope: WRITE_SALES x-required-scope-note: >- The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: true name: token schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/GuestSale' example: saleId: sale_1 email: alex@example.com purchasedAt: '2026-10-01T10:00:00Z' product: id: prd_1 sku: acme-notebook name: Acme Notebook imageUrl: null productType: PHYSICAL variant: null quantity: 1 amount: 2500 shippingAmount: 400 currency: EUR refundStatus: NONE refundable: true refundReason: null refundWindowEndsAt: '2026-10-15T10:00:00Z' invoiceUrl: null hasReceipt: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: UNSUPPORTED_LINK: summary: 'UNSUPPORTED_LINK: This link is not an order link' value: error: This link is not an order link code: UNSUPPORTED_LINK '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_LINK: summary: 'INVALID_LINK: Invalid link' value: error: Invalid link code: INVALID_LINK API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LINK_MISMATCH: summary: 'LINK_MISMATCH: This link no longer matches the order' value: error: This link no longer matches the order code: LINK_MISMATCH API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LINK_NOT_FOUND: summary: 'LINK_NOT_FOUND: Order not found' value: error: Order not found code: LINK_NOT_FOUND '410': description: Gone. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LINK_EXPIRED: summary: 'LINK_EXPIRED: This link has expired' value: error: This link has expired code: LINK_EXPIRED '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/sales/manage/receipt: get: operationId: getSalesManageReceipt summary: A guest's receipt PDF description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. Same token and errors as `GET /sales/manage`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Checkout x-required-scope: WRITE_SALES x-required-scope-note: >- The default publishable key carries only READ_PUBLIC, WRITE_APPLICATIONS and WRITE_CART, so call this with a secret key from your server unless the community granted its publishable key WRITE_SALES. x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: true name: token schema: type: string responses: '200': description: Success. content: application/pdf: schema: type: string format: binary '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: UNSUPPORTED_LINK: summary: 'UNSUPPORTED_LINK: This link is not an order link' value: error: This link is not an order link code: UNSUPPORTED_LINK '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_LINK: summary: 'INVALID_LINK: Invalid link' value: error: Invalid link code: INVALID_LINK API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LINK_MISMATCH: summary: 'LINK_MISMATCH: This link no longer matches the order' value: error: This link no longer matches the order code: LINK_MISMATCH API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LINK_NOT_FOUND: summary: 'LINK_NOT_FOUND: Order not found' value: error: Order not found code: LINK_NOT_FOUND '410': description: Gone. content: application/json: schema: $ref: '#/components/schemas/Error' examples: LINK_EXPIRED: summary: 'LINK_EXPIRED: This link has expired' value: error: This link has expired code: LINK_EXPIRED '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/cart: post: operationId: postCart summary: Create a cart description: >- **Required scope:** `WRITE_CART` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Guests identify their cart with `X-Cobuntu-Cart-Token`; a signed-in user on the community app is identified by their session. A guest gets `201` with a `token`: store it and send it as `X-Cobuntu-Cart-Token`. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Commerce x-required-scope: WRITE_CART x-key-type: publishable x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - $ref: '#/components/parameters/CartToken' responses: '200': description: Signed-in user; no token. content: application/json: schema: type: object properties: cart: $ref: '#/components/schemas/Cart' token: type: 'null' example: cart: id: cart_1 communityId: com_1 items: [] subtotal: 0 currency: EUR totalItems: 0 token: null '201': description: Success. content: application/json: schema: type: object properties: cart: $ref: '#/components/schemas/Cart' token: type: - string - 'null' example: cart: id: cart_1 communityId: com_1 items: [] subtotal: 0 currency: EUR totalItems: 0 token: ct_abc123 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_CART: summary: 'API key missing required scope: WRITE_CART' value: error: 'API key missing required scope: WRITE_CART' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable get: operationId: getCart summary: Get the cart description: >- **Required scope:** `WRITE_CART` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Guests identify their cart with `X-Cobuntu-Cart-Token`; a signed-in user on the community app is identified by their session. Prices are resolved live on every read. An unknown or purged token is `404`: mint a new cart. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Commerce x-required-scope: WRITE_CART x-key-type: publishable x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - $ref: '#/components/parameters/CartToken' responses: '200': description: Success. content: application/json: schema: type: object properties: cart: $ref: '#/components/schemas/Cart' example: cart: id: cart_1 communityId: com_1 items: - id: ci_1 productId: prd_1 checkoutProductId: prd_1a tierId: tier_a5 quantity: 1 name: Acme Notebook tierName: A5 sku: acme-notebook unitPrice: 2500 lineTotal: 2500 currency: EUR imageUrl: null productType: DIGITAL unavailableReason: null subtotal: 2500 currency: EUR totalItems: 1 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_CART: summary: 'API key missing required scope: WRITE_CART' value: error: 'API key missing required scope: WRITE_CART' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Cart_not_found: summary: Cart not found value: error: Cart not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/cart/items: post: operationId: postCartItems summary: Add an item description: >- **Required scope:** `WRITE_CART` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Guests identify their cart with `X-Cobuntu-Cart-Token`; a signed-in user on the community app is identified by their session. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Commerce x-required-scope: WRITE_CART x-key-type: publishable x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - $ref: '#/components/parameters/CartToken' responses: '201': description: Success. content: application/json: schema: type: object properties: cart: $ref: '#/components/schemas/Cart' example: cart: id: cart_1 communityId: com_1 items: - id: ci_1 productId: prd_1 checkoutProductId: prd_1a tierId: tier_a5 quantity: 1 name: Acme Notebook tierName: A5 sku: acme-notebook unitPrice: 2500 lineTotal: 2500 currency: EUR imageUrl: null productType: DIGITAL unavailableReason: null subtotal: 2500 currency: EUR totalItems: 1 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: productId_is_required: summary: productId is required value: error: productId is required quantity_must_be_a_positive_whole_number: summary: quantity must be a positive whole number value: error: quantity must be a positive whole number quantity_must_be_99_or_fewer: summary: quantity must be 99 or fewer value: error: quantity must be 99 or fewer A_cart_may_hold_at_most_50_different_items: summary: A cart may hold at most 50 different items value: error: A cart may hold at most 50 different items That_option_is_not_available_for_this_product: summary: That option is not available for this product value: error: That option is not available for this product '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_CART: summary: 'API key missing required scope: WRITE_CART' value: error: 'API key missing required scope: WRITE_CART' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Product_not_found: summary: Product not found value: error: Product not found Cart_not_found: summary: Cart not found value: error: Cart not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: productId: type: string tierId: type: string quantity: type: integer minimum: 1 default: 1 required: - productId example: productId: prd_1 quantity: 1 /api/v1/communities/{communityTag}/cart/items/{itemId}: patch: operationId: patchCartItemsItemId summary: Set an item's quantity description: >- **Required scope:** `WRITE_CART` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Guests identify their cart with `X-Cobuntu-Cart-Token`; a signed-in user on the community app is identified by their session. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Commerce x-required-scope: WRITE_CART x-key-type: publishable x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: itemId in: path required: true description: Cart item id. schema: type: string - $ref: '#/components/parameters/CartToken' responses: '200': description: Success. content: application/json: schema: type: object properties: cart: $ref: '#/components/schemas/Cart' example: cart: id: cart_1 communityId: com_1 items: - id: ci_1 productId: prd_1 checkoutProductId: prd_1a tierId: tier_a5 quantity: 1 name: Acme Notebook tierName: A5 sku: acme-notebook unitPrice: 2500 lineTotal: 2500 currency: EUR imageUrl: null productType: DIGITAL unavailableReason: null subtotal: 2500 currency: EUR totalItems: 1 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: quantity_is_required: summary: quantity is required value: error: quantity is required quantity_must_be_a_whole_number_of_0_or_more: summary: quantity must be a whole number of 0 or more value: error: quantity must be a whole number of 0 or more quantity_must_be_99_or_fewer: summary: quantity must be 99 or fewer value: error: quantity must be 99 or fewer '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_CART: summary: 'API key missing required scope: WRITE_CART' value: error: 'API key missing required scope: WRITE_CART' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Item_not_found: summary: Item not found value: error: Item not found Cart_not_found: summary: Cart not found value: error: Cart not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: quantity: type: integer minimum: 0 maximum: 99 description: 0 removes the line. required: - quantity example: quantity: 3 delete: operationId: deleteCartItemsItemId summary: Remove an item description: >- **Required scope:** `WRITE_CART` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Guests identify their cart with `X-Cobuntu-Cart-Token`; a signed-in user on the community app is identified by their session. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Commerce x-required-scope: WRITE_CART x-key-type: publishable x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: itemId in: path required: true description: Cart item id. schema: type: string - $ref: '#/components/parameters/CartToken' responses: '200': description: Success. content: application/json: schema: type: object properties: cart: $ref: '#/components/schemas/Cart' example: cart: id: cart_1 communityId: com_1 items: - id: ci_1 productId: prd_1 checkoutProductId: prd_1a tierId: tier_a5 quantity: 1 name: Acme Notebook tierName: A5 sku: acme-notebook unitPrice: 2500 lineTotal: 2500 currency: EUR imageUrl: null productType: DIGITAL unavailableReason: null subtotal: 2500 currency: EUR totalItems: 1 '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_CART: summary: 'API key missing required scope: WRITE_CART' value: error: 'API key missing required scope: WRITE_CART' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Item_not_found: summary: Item not found value: error: Item not found Cart_not_found: summary: Cart not found value: error: Cart not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/cart/merge: post: operationId: postCartMerge summary: Merge a guest cart into the user's cart description: >- **Required scope:** `WRITE_CART` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Requires a signed-in Cobuntu app session (`Authorization: Bearer`, on the community app origin) and the guest `X-Cobuntu-Cart-Token`. An embed member session (`X-Cobuntu-Auth-Token`) is not accepted here, so from your own server this answers `401`. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Commerce x-required-scope: WRITE_CART x-key-type: publishable x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - $ref: '#/components/parameters/CartToken' responses: '200': description: Success. content: application/json: schema: type: object properties: cart: $ref: '#/components/schemas/Cart' example: cart: id: cart_1 communityId: com_1 items: - id: ci_1 productId: prd_1 checkoutProductId: prd_1a tierId: tier_a5 quantity: 1 name: Acme Notebook tierName: A5 sku: acme-notebook unitPrice: 2500 lineTotal: 2500 currency: EUR imageUrl: null productType: DIGITAL unavailableReason: null subtotal: 2500 currency: EUR totalItems: 1 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: A_guest_cart_token_is_required: summary: A guest cart token is required value: error: A guest cart token is required '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Sign_in_to_merge_a_cart: summary: Sign in to merge a cart value: error: Sign in to merge a cart API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_CART: summary: 'API key missing required scope: WRITE_CART' value: error: 'API key missing required scope: WRITE_CART' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/cart/handoff: post: operationId: postCartHandoff summary: Mint a cart handoff code description: >- **Required scope:** `WRITE_CART` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. A one-time code (valid 60 seconds) that carries the cart to another origin in a URL. Never put the cart token itself in a URL. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Commerce x-required-scope: WRITE_CART x-key-type: publishable x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - $ref: '#/components/parameters/CartToken' responses: '201': description: Success. content: application/json: schema: type: object properties: code: type: string expiresAt: type: string format: date-time example: code: hc_9f8e7d expiresAt: '2026-10-13T12:01:00Z' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_CART: summary: 'API key missing required scope: WRITE_CART' value: error: 'API key missing required scope: WRITE_CART' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Cart_not_found: summary: Cart not found value: error: Cart not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/cart/claim: post: operationId: postCartClaim summary: Claim a cart handoff code description: >- **Required scope:** `WRITE_CART` (`ADMIN` also satisfies it). **Key:** Publishable or secret key. Exchanges the one-time code for the cart on the receiving origin. A signed-in claimer absorbs it into their own cart (`token: null`); a guest gets a fresh token for this browser while the issuing browser's token keeps working. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Commerce x-required-scope: WRITE_CART x-key-type: publishable x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - $ref: '#/components/parameters/CartToken' responses: '200': description: Success. content: application/json: schema: type: object properties: cart: $ref: '#/components/schemas/Cart' token: type: - string - 'null' example: cart: id: cart_1 communityId: com_1 items: - id: ci_1 productId: prd_1 checkoutProductId: prd_1a tierId: tier_a5 quantity: 1 name: Acme Notebook tierName: A5 sku: acme-notebook unitPrice: 2500 lineTotal: 2500 currency: EUR imageUrl: null productType: DIGITAL unavailableReason: null subtotal: 2500 currency: EUR totalItems: 1 token: ct_abc123 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: code_is_required: summary: code is required value: error: code is required '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_WRITE_CART: summary: 'API key missing required scope: WRITE_CART' value: error: 'API key missing required scope: WRITE_CART' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: That_checkout_link_has_expired: summary: That checkout link has expired value: error: That checkout link has expired Cart_not_found: summary: Cart not found value: error: Cart not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: code: type: string required: - code example: code: hc_9f8e7d /api/v1/communities/{communityTag}/sales/{saleId}/refund: post: operationId: postSalesSaleIdRefund summary: Refund a sale (host-initiated) description: >- **Required scope:** `WRITE_SALES` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). **Amount unit quirk:** `amount` is in **major units** (euros, not cents). Omit it for a full refund. The sale must be sold by, or for an event hosted by, this community. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Commerce x-required-scope: WRITE_SALES x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: saleId in: path required: true description: Sale id. schema: type: string responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/RefundResult' example: id: ref_2 status: PENDING amount: 1500 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: reason_is_required: summary: reason is required value: error: reason is required Invalid_refund_amount: summary: Invalid refund amount value: error: Invalid refund amount '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Sale_does_not_belong_to_this_community: summary: Sale does not belong to this community value: error: Sale does not belong to this community SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_WRITE_SALES: summary: 'API key missing required scope: WRITE_SALES' value: error: 'API key missing required scope: WRITE_SALES' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Sale_not_found: summary: Sale not found value: error: Sale not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '500': description: Server error. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Failed_to_process_refund: summary: Failed to process refund value: error: Failed to process refund '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: reason: type: string amount: type: number exclusiveMinimum: 0 maximum: 1000000 description: MAJOR units (not cents). Omit for a full refund. refundType: type: string enum: - BUYER_REQUEST - HOST_CANCELLATION - CHARGEBACK default: HOST_CANCELLATION required: - reason example: reason: Event cancelled refundType: HOST_CANCELLATION /api/v1/communities/{communityTag}/segment-subscriptions/admin-cancel: post: operationId: postSegmentSubscriptionsAdminCancel summary: Cancel a member's subscription description: |- **Required scope:** `WRITE_SUBSCRIPTIONS` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Commerce x-required-scope: WRITE_SUBSCRIPTIONS x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object additionalProperties: true example: success: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: targetUserId_is_required: summary: targetUserId is required value: error: targetUserId is required '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_WRITE_SUBSCRIPTIO: summary: 'API key missing required scope: WRITE_SUBSCRIPTIONS' value: error: 'API key missing required scope: WRITE_SUBSCRIPTIONS' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Subscription_not_found: summary: Subscription not found value: error: Subscription not found '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Cannot_resolve_a_founder_user_for_this_community: summary: Cannot resolve a founder user for this community value: error: Cannot resolve a founder user for this community '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: targetUserId: type: string reason: type: string required: - targetUserId example: targetUserId: usr_123 reason: Requested by member /api/v1/communities/{communityTag}/segment-subscriptions/change-tier/{userId}: post: operationId: postSegmentSubscriptionsChangeTierUserId summary: Change a member's tier description: |- **Required scope:** `WRITE_SUBSCRIPTIONS` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Free changes apply immediately (`subscription`); paid upgrades return a `checkoutUrl` for the member. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Commerce x-required-scope: WRITE_SUBSCRIPTIONS x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: userId in: path required: true description: User id or usertag. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: subscription: type: - object - 'null' checkoutUrl: type: - string - 'null' example: subscription: null checkoutUrl: https://checkout.stripe.com/c/pay/cs_test_456 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: newSegmentId_and_billingCycle_are_required: summary: newSegmentId and billingCycle are required value: error: newSegmentId and billingCycle are required '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This endpoint requires a secret key' value: error: This endpoint requires a secret key code: SECRET_KEY_REQUIRED API_key_missing_required_scope_WRITE_SUBSCRIPTIO: summary: 'API key missing required scope: WRITE_SUBSCRIPTIONS' value: error: 'API key missing required scope: WRITE_SUBSCRIPTIONS' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Segment_not_found: summary: Segment not found value: error: Segment not found '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Already_on_this_tier: summary: Already on this tier value: error: Already on this tier '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: newSegmentId: type: string billingCycle: type: string description: A recurring cadence (for example MONTHLY, YEARLY) or ONE_TIME. required: - newSegmentId - billingCycle example: newSegmentId: seg_pro billingCycle: MONTHLY /api/v1/communities/{communityTag}/apps/{appKey}/handoff: post: operationId: postAppsAppKeyHandoff summary: Mint a "Sign in with Cobuntu" code description: >- **Required scope:** none (member session). **Key:** No API key. Called from the community app by the signed-in member (their Cobuntu session, no API key). Returns a 60-second one-time code to send to your app, which exchanges it server-side. Supports PKCE (S256). **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Apps x-required-scope: null x-key-type: none x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - CobuntuSession: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: appKey in: path required: true description: Your installed app's key. schema: type: string responses: '201': description: Success. content: application/json: schema: type: object properties: code: type: string expiresIn: type: integer example: code: hnd_abc expiresIn: 60 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: codeChallengeMethod_must_be_S256: summary: codeChallengeMethod must be S256 value: error: codeChallengeMethod must be S256 codeChallenge_is_required_with_codeChallengeMeth: summary: codeChallenge is required with codeChallengeMethod value: error: codeChallenge is required with codeChallengeMethod '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Authentication_required: summary: Authentication required value: error: Authentication required '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: App_not_installed_in_this_community: summary: App not installed in this community value: error: App not installed in this community '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED requestBody: required: false content: application/json: schema: type: object properties: codeChallenge: type: string codeChallengeMethod: type: string enum: - S256 example: codeChallenge: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM codeChallengeMethod: S256 /api/v1/apps/handoff/exchange: post: operationId: postAppsHandoffExchange summary: Exchange a handoff code description: >- **Required scope:** `APP_HANDOFF` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Server-to-server. Returns who the visitor is. `email` is included with `APP_IDENTITY_EMAIL`; `name`, `profileImage` and `locale` with `APP_IDENTITY_PROFILE`. Every failure is the same `400` so codes cannot be probed. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Apps x-required-scope: APP_HANDOFF x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: [] responses: '200': description: Success. content: application/json: schema: type: object properties: userId: type: string communityTag: type: string appKey: type: string email: type: string name: type: string profileImage: type: - string - 'null' locale: type: - string - 'null' example: userId: usr_123 communityTag: your-community appKey: acme-reports email: alex@example.com '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: code_and_appKey_are_required: summary: code and appKey are required value: error: code and appKey are required Invalid_or_expired_code: summary: Invalid or expired code value: error: Invalid or expired code '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Publishable_keys_cannot_call_this_endpoint: summary: Publishable keys cannot call this endpoint value: error: Publishable keys cannot call this endpoint hint: Use a secret key with the required scope. API_key_missing_required_scope_APP_HANDOFF: summary: 'API key missing required scope: APP_HANDOFF' value: error: 'API key missing required scope: APP_HANDOFF' grantedScopes: - READ_PUBLIC '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: code: type: string appKey: type: string codeVerifier: type: string description: Required when the code was minted with PKCE. required: - code - appKey example: code: hnd_abc appKey: acme-reports codeVerifier: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk /api/v1/communities/{communityTag}/apps/mint-member-token: post: operationId: postAppsMintMemberToken summary: Mint a member token for a known member description: >- **Required scope:** `APP_MINT_MEMBER_TOKEN` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Server-to-server. For an app that already holds a member's `userId` (from its own handoff exchange) and later needs to act for that member on the member-token endpoints (attendance status, RSVP, leave) without sending them through a redirect again. Returns a 5-minute token to send as `X-Cobuntu-Member-Token`. Accepted membership is re-checked on every mint, so a member who left stops being mintable at once. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Apps x-required-scope: APP_MINT_MEMBER_TOKEN x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community responses: '200': description: Success. content: application/json: schema: type: object properties: token: type: string description: Send as `X-Cobuntu-Member-Token`. expiresInSeconds: type: integer enum: - 300 example: token: eyJhbGciOi... expiresInSeconds: 300 '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: userId is required' value: error: userId is required code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: The publishable key cannot mint a member token' value: error: The publishable key cannot mint a member token code: SECRET_KEY_REQUIRED hint: Mint server-to-server with a secret key carrying APP_MINT_MEMBER_TOKEN. NOT_A_MEMBER: summary: 'NOT_A_MEMBER: Not a member of this community' value: error: Not a member of this community code: NOT_A_MEMBER API_key_missing_required_scope_APP_MINT_MEMBER_T: summary: 'API key missing required scope: APP_MINT_MEMBER_TOKEN' value: error: 'API key missing required scope: APP_MINT_MEMBER_TOKEN' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: userId: type: string required: - userId example: userId: usr_123 /api/v1/communities/{communityTag}/members/{userId}/app-data: get: operationId: getMembersUserIdAppData summary: List your app's data for a member description: |- **Required scope:** `APP_DATA` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Per-member key/value storage owned by your app, erased with the member. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Apps x-required-scope: APP_DATA x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: userId in: path required: true description: User id or usertag. schema: type: string - in: query required: true name: appKey schema: type: string description: Your installed app's key. responses: '200': description: Success. content: application/json: schema: type: object properties: userId: type: string appKey: type: string data: type: array items: $ref: '#/components/schemas/AppDataEntry' example: userId: usr_123 appKey: acme-reports data: - key: prefs value: theme: dark updatedAt: '2026-10-01T10:00:00Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: appKey_is_required: summary: appKey is required value: error: appKey is required '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Publishable_keys_cannot_call_this_endpoint: summary: Publishable keys cannot call this endpoint value: error: Publishable keys cannot call this endpoint hint: Use a secret key with the required scope. API_key_missing_required_scope_APP_DATA: summary: 'API key missing required scope: APP_DATA' value: error: 'API key missing required scope: APP_DATA' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: App_not_installed_in_this_community: summary: App not installed in this community value: error: App not installed in this community Member_not_found: summary: Member not found value: error: Member not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/members/{userId}/app-data/{key}: get: operationId: getMembersUserIdAppDataKey summary: Get one value description: |- **Required scope:** `APP_DATA` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Apps x-required-scope: APP_DATA x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: userId in: path required: true description: User id or usertag. schema: type: string - name: key in: path required: true schema: type: string maxLength: 128 pattern: ^[a-zA-Z0-9._:-]+$ - in: query required: true name: appKey schema: type: string description: Your installed app's key. responses: '200': description: Success. content: application/json: schema: type: object properties: userId: type: string appKey: type: string key: type: string value: {} updatedAt: type: string format: date-time example: userId: usr_123 appKey: acme-reports key: prefs value: theme: dark updatedAt: '2026-10-01T10:00:00Z' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: appKey_is_required: summary: appKey is required value: error: appKey is required '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Publishable_keys_cannot_call_this_endpoint: summary: Publishable keys cannot call this endpoint value: error: Publishable keys cannot call this endpoint hint: Use a secret key with the required scope. API_key_missing_required_scope_APP_DATA: summary: 'API key missing required scope: APP_DATA' value: error: 'API key missing required scope: APP_DATA' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: App_not_installed_in_this_community: summary: App not installed in this community value: error: App not installed in this community Member_not_found: summary: Member not found value: error: Member not found Key_not_found: summary: Key not found value: error: Key not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable put: operationId: putMembersUserIdAppDataKey summary: Set one value description: |- **Required scope:** `APP_DATA` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Max 16 KB per value and 100 keys per member per app. `appKey` may be sent in the query or the body. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Apps x-required-scope: APP_DATA x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: userId in: path required: true description: User id or usertag. schema: type: string - name: key in: path required: true schema: type: string maxLength: 128 pattern: ^[a-zA-Z0-9._:-]+$ - in: query required: false name: appKey schema: type: string description: Your installed app's key. responses: '200': description: Success. content: application/json: schema: type: object properties: userId: type: string appKey: type: string created: type: boolean key: type: string value: {} updatedAt: type: string format: date-time example: userId: usr_123 appKey: acme-reports created: false key: prefs value: theme: dark updatedAt: '2026-10-13T10:00:00Z' '201': description: Created. content: application/json: schema: type: object properties: created: type: boolean example: created: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: appKey_is_required: summary: appKey is required value: error: appKey is required value_is_required: summary: value is required value: error: value is required '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Publishable_keys_cannot_call_this_endpoint: summary: Publishable keys cannot call this endpoint value: error: Publishable keys cannot call this endpoint hint: Use a secret key with the required scope. API_key_missing_required_scope_APP_DATA: summary: 'API key missing required scope: APP_DATA' value: error: 'API key missing required scope: APP_DATA' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: App_not_installed_in_this_community: summary: App not installed in this community value: error: App not installed in this community Member_not_found: summary: Member not found value: error: Member not found '413': description: Payload too large. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Value_too_large: summary: Value too large value: error: Value too large bytes: 20000 limit: 16384 '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Too_many_keys_for_this_member: summary: Too many keys for this member value: error: Too many keys for this member limit: 100 RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: appKey: type: string value: description: Any JSON value; null stores null. required: - value example: appKey: acme-reports value: theme: dark delete: operationId: deleteMembersUserIdAppDataKey summary: Delete one value description: |- **Required scope:** `APP_DATA` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Apps x-required-scope: APP_DATA x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: userId in: path required: true description: User id or usertag. schema: type: string - name: key in: path required: true schema: type: string maxLength: 128 pattern: ^[a-zA-Z0-9._:-]+$ - in: query required: true name: appKey schema: type: string description: Your installed app's key. responses: '200': description: Success. content: application/json: schema: type: object properties: userId: type: string appKey: type: string key: type: string deleted: type: boolean example: userId: usr_123 appKey: acme-reports key: prefs deleted: true '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: appKey_is_required: summary: appKey is required value: error: appKey is required '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Publishable_keys_cannot_call_this_endpoint: summary: Publishable keys cannot call this endpoint value: error: Publishable keys cannot call this endpoint hint: Use a secret key with the required scope. API_key_missing_required_scope_APP_DATA: summary: 'API key missing required scope: APP_DATA' value: error: 'API key missing required scope: APP_DATA' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: App_not_installed_in_this_community: summary: App not installed in this community value: error: App not installed in this community Member_not_found: summary: Member not found value: error: Member not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/members/{userId}/locale: put: operationId: putMembersUserIdLocale summary: Write a member's language description: >- **Required scope:** `APP_IDENTITY_LOCALE_WRITE` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Null or empty string clears it. **Rate limit:** 120 writes/min per API key, inside the 600 requests/min per key ceiling. tags: - Apps x-required-scope: APP_IDENTITY_LOCALE_WRITE x-key-type: secret x-rate-limit: 120 writes/min per API key, inside the 600 requests/min per key ceiling. security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: userId in: path required: true description: User id or usertag. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: userId: type: string locale: type: - string - 'null' example: userId: usr_123 locale: pt-PT '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: locale_is_required: summary: locale is required value: error: locale is required Unsupported_locale: summary: Unsupported locale value: error: Unsupported locale '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Publishable_keys_cannot_call_this_endpoint: summary: Publishable keys cannot call this endpoint value: error: Publishable keys cannot call this endpoint hint: Use a secret key with the required scope. API_key_missing_required_scope_APP_IDENTITY_LOCA: summary: 'API key missing required scope: APP_IDENTITY_LOCALE_WRITE' value: error: 'API key missing required scope: APP_IDENTITY_LOCALE_WRITE' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Member_not_found: summary: Member not found value: error: Member not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable requestBody: required: true content: application/json: schema: type: object properties: locale: type: - string - 'null' description: A supported locale code, for example en, pt-PT, fr. required: - locale example: locale: pt-PT /api/v1/users/me/products: get: operationId: getUsersMeProducts summary: Your products and courses description: >- **Required scope:** `READ_OWN` (user key; no wildcard). **Key:** User key (`uk_`). Authenticated with a **user key** (`uk_...`, scope `READ_OWN`): the person the key belongs to is the owner, so there is no id in the path. A community key here is `401`. Use `type=COURSE` for courses. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - User keys x-required-scope: READ_OWN x-key-type: user x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - UserApiKey: [] parameters: - in: query required: false name: type schema: type: string - in: query required: false name: category schema: type: string - in: query required: false name: limit schema: type: integer - in: query required: false name: offset schema: type: integer responses: '200': description: Success. content: application/json: schema: type: object properties: products: type: array items: $ref: '#/components/schemas/Product' pagination: $ref: '#/components/schemas/Pagination' example: products: - id: prd_1 name: Acme Notebook sku: acme-notebook price: 2500 currency: EUR productType: DIGITAL seller: type: community name: Your Community usertag: null imageUrl: null variants: - id: tier_a5 name: A5 isOnSale: true state: on-sale capacity: 50 remaining: 12 soldOut: false memberPrice: null memberPriceMode: null publicMemberOffers: - segmentName: Pro price: 2000 mode: FLAT_OFF product: id: prd_1a sku: acme-notebook-a5 price: 2500 currency: EUR isRecurring: false recurringInterval: null pageUrl: https://your-community.cobuntu.com/marketplace/acme-notebook pagination: total: 1 limit: 20 offset: 0 hasMore: false '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_OWN: summary: 'API key missing required scope: READ_OWN' value: error: 'API key missing required scope: READ_OWN' grantedScopes: [] '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/users/me/products/{idOrSku}: get: operationId: getUsersMeProductsIdOrSku summary: One of your products description: >- **Required scope:** `READ_OWN` (user key; no wildcard). **Key:** User key (`uk_`). Authenticated with a **user key** (`uk_...`, scope `READ_OWN`): the person the key belongs to is the owner, so there is no id in the path. A community key here is `401`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - User keys x-required-scope: READ_OWN x-key-type: user x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - UserApiKey: [] parameters: - name: idOrSku in: path required: true description: Product id or SKU. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: product: $ref: '#/components/schemas/Product' example: product: id: prd_1 name: Acme Notebook sku: acme-notebook price: 2500 currency: EUR productType: DIGITAL seller: type: community name: Your Community usertag: null imageUrl: null variants: - id: tier_a5 name: A5 isOnSale: true state: on-sale capacity: 50 remaining: 12 soldOut: false memberPrice: null memberPriceMode: null publicMemberOffers: - segmentName: Pro price: 2000 mode: FLAT_OFF product: id: prd_1a sku: acme-notebook-a5 price: 2500 currency: EUR isRecurring: false recurringInterval: null pageUrl: https://your-community.cobuntu.com/marketplace/acme-notebook '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_OWN: summary: 'API key missing required scope: READ_OWN' value: error: 'API key missing required scope: READ_OWN' grantedScopes: [] '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Product_not_found: summary: Product not found value: error: Product not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/users/me/events: get: operationId: getUsersMeEvents summary: Your events description: >- **Required scope:** `READ_OWN` (user key; no wildcard). **Key:** User key (`uk_`). Authenticated with a **user key** (`uk_...`, scope `READ_OWN`): the person the key belongs to is the owner, so there is no id in the path. A community key here is `401`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - User keys x-required-scope: READ_OWN x-key-type: user x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - UserApiKey: [] parameters: - in: query required: false name: upcoming schema: type: boolean - in: query required: false name: category schema: type: string - in: query required: false name: limit schema: type: integer - in: query required: false name: offset schema: type: integer responses: '200': description: Success. content: application/json: schema: type: object properties: events: type: array items: $ref: '#/components/schemas/Event' pagination: $ref: '#/components/schemas/Pagination' example: events: - id: evt_123 slug: summer-meetup createdAt: '2026-05-01T10:00:00Z' name: Summer Meetup description: An evening with the community. bannerUrl: https://example.com/banner.jpg cardImageUrl: null startDate: '2026-11-20T18:00:00Z' endDate: '2026-11-20T21:00:00Z' timezone: Europe/Lisbon physicalLocation: Main Hall, Lisbon locationFormat: PHYSICAL viewability: PUBLIC requiresApproval: false featured: true tiers: - id: tier_1 name: General price: 1500 currency: EUR capacity: 100 remaining: 42 soldOut: false hasForm: true isOnSale: true memberPrice: null publicMemberOffers: - segmentName: Members price: 1000 mode: FIXED_PRICE attendeeCount: 58 isAttending: false categoryId: cat_workshops subCategoryId: null category: id: cat_workshops name: Workshops subcategory: null pagination: total: 1 limit: 20 offset: 0 hasMore: false '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_OWN: summary: 'API key missing required scope: READ_OWN' value: error: 'API key missing required scope: READ_OWN' grantedScopes: [] '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/users/me/events/{idOrSlug}: get: operationId: getUsersMeEventsIdOrSlug summary: One of your events description: >- **Required scope:** `READ_OWN` (user key; no wildcard). **Key:** User key (`uk_`). Authenticated with a **user key** (`uk_...`, scope `READ_OWN`): the person the key belongs to is the owner, so there is no id in the path. A community key here is `401`. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - User keys x-required-scope: READ_OWN x-key-type: user x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - UserApiKey: [] parameters: - name: idOrSlug in: path required: true description: Event id or slug. schema: type: string responses: '200': description: Success. content: application/json: schema: type: object properties: event: $ref: '#/components/schemas/Event' example: event: id: evt_123 slug: summer-meetup createdAt: '2026-05-01T10:00:00Z' name: Summer Meetup description: An evening with the community. bannerUrl: https://example.com/banner.jpg cardImageUrl: null startDate: '2026-11-20T18:00:00Z' endDate: '2026-11-20T21:00:00Z' timezone: Europe/Lisbon physicalLocation: Main Hall, Lisbon locationFormat: PHYSICAL viewability: PUBLIC requiresApproval: false featured: true tiers: - id: tier_1 name: General price: 1500 currency: EUR capacity: 100 remaining: 42 soldOut: false hasForm: true isOnSale: true memberPrice: null publicMemberOffers: - segmentName: Members price: 1000 mode: FIXED_PRICE attendeeCount: 58 isAttending: false categoryId: cat_workshops subCategoryId: null category: id: cat_workshops name: Workshops subcategory: null '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_missing_required_scope_READ_OWN: summary: 'API key missing required scope: READ_OWN' value: error: 'API key missing required scope: READ_OWN' grantedScopes: [] '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Event_not_found: summary: Event not found value: error: Event not found '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/finance/entries: get: operationId: getFinanceEntries summary: The community's ledger description: >- **Required scope:** `READ_FINANCE` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Sales the community made, commission it earned on members' sales, refunds and donations, oldest first. Amounts are integer cents. Read `role` before `net`: on a COMMISSION_RECIPIENT entry the community keeps only its commission, and `gross` is the member's sale value. Append-only: a refund arrives as its own negative entry rather than altering the sale. Figures can still be RESTATED in place when Stripe settles a fee differently from its estimate, so re-sync a full window periodically rather than relying only on the cursor. Buyer identity (`buyer`) is included only with READ_FINANCE_PII; otherwise entries carry the opaque `buyerRef` alone. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Finance x-required-scope: READ_FINANCE x-required-scope-note: READ_FINANCE_PII additionally returns buyer email and name. x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: limit schema: type: integer minimum: 1 maximum: 500 default: 100 description: Clamped to 500 rather than refused. - in: query required: false name: cursor schema: type: string description: The previous page's nextCursor. Malformed is a 400, never a silent restart. - in: query required: false name: from schema: type: string format: date-time description: Inclusive. - in: query required: false name: to schema: type: string format: date-time description: Inclusive. responses: '200': description: Success. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/FinanceEntry' nextCursor: type: - string - 'null' hasMore: type: boolean asOf: type: string format: date-time '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_CURSOR: summary: 'INVALID_CURSOR: Malformed cursor' value: error: Malformed cursor code: INVALID_CURSOR INVALID_INPUT: summary: 'INVALID_INPUT: from and to must be ISO-8601 dates' value: error: from and to must be ISO-8601 dates code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This route needs a secret server key' value: error: This route needs a secret server key code: SECRET_KEY_REQUIRED WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY API_key_missing_required_scope_READ_FINANCE: summary: 'API key missing required scope: READ_FINANCE' value: error: 'API key missing required scope: READ_FINANCE' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/finance/payouts: get: operationId: getFinancePayouts summary: Settlements to the community description: >- **Required scope:** `READ_FINANCE` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). What Cobuntu transferred into the community's Stripe balance, oldest first. An entry's `settlement.payoutId` joins to a row here. This is NOT a bank statement. Money moves in two hops and only the first is ours: Cobuntu to their Stripe balance (these rows), then their Stripe to their bank on their own payout schedule, which batches however many of our transfers have accumulated and which we do not hold. One bank credit routinely covers several rows here. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Finance x-required-scope: READ_FINANCE x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: limit schema: type: integer minimum: 1 maximum: 500 default: 100 description: Clamped to 500 rather than refused. - in: query required: false name: cursor schema: type: string description: The previous page's nextCursor. Malformed is a 400, never a silent restart. - in: query required: false name: from schema: type: string format: date-time description: Inclusive. - in: query required: false name: to schema: type: string format: date-time description: Inclusive. responses: '200': description: Success. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/FinancePayout' nextCursor: type: - string - 'null' hasMore: type: boolean asOf: type: string format: date-time '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_CURSOR: summary: 'INVALID_CURSOR: Malformed cursor' value: error: Malformed cursor code: INVALID_CURSOR INVALID_INPUT: summary: 'INVALID_INPUT: from and to must be ISO-8601 dates' value: error: from and to must be ISO-8601 dates code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This route needs a secret server key' value: error: This route needs a secret server key code: SECRET_KEY_REQUIRED WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY API_key_missing_required_scope_READ_FINANCE: summary: 'API key missing required scope: READ_FINANCE' value: error: 'API key missing required scope: READ_FINANCE' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/finance/deposits/{depositId}/statement: get: operationId: getFinanceDepositsDepositIdStatement summary: What one bank credit covered description: >- **Required scope:** `READ_FINANCE` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). A remittance statement: the payouts, and their invoice numbers, behind a single line on the bank statement. The depositId comes from the payout.deposited webhook. Add ?format=pdf for a document to forward to an accountant; the PDF renders exactly this payload, so the two cannot disagree. totals.unaccounted is deposit minus covered. Normally 0; non-zero is not an error, it means the deposit also carried money that did not come through Cobuntu. This is a STATEMENT, not an invoice. Every payout in it was already invoiced separately, so nothing here is additional income. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Finance x-required-scope: READ_FINANCE x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - name: depositId in: path required: true description: depositId schema: type: string - in: query required: false name: format schema: type: string enum: - json - pdf default: json description: pdf streams application/pdf instead of JSON. responses: '200': description: Success. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/RemittanceStatement' asOf: type: string format: date-time '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This route needs a secret server key' value: error: This route needs a secret server key code: SECRET_KEY_REQUIRED WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY API_key_missing_required_scope_READ_FINANCE: summary: 'API key missing required scope: READ_FINANCE' value: error: 'API key missing required scope: READ_FINANCE' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NOT_FOUND: summary: 'NOT_FOUND: Deposit not found' value: error: Deposit not found code: NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable /api/v1/communities/{communityTag}/finance/summary: get: operationId: getFinanceSummary summary: Totals for a window description: >- **Required scope:** `READ_FINANCE` (`ADMIN` also satisfies it). **Key:** Secret key only (server-side). Aggregates by stream and by entry type, grouped by currency. Never summed across currencies. Computed from exactly the same entries /finance/entries serves, so the two cannot disagree. **Rate limit:** 600 requests/min per API key (whole v1 surface). tags: - Finance x-required-scope: READ_FINANCE x-key-type: secret x-rate-limit: 600 requests/min per API key (whole v1 surface). security: - ApiKey: [] parameters: - name: communityTag in: path required: true description: Your community's tag, for example `your-community`. schema: type: string example: your-community - in: query required: false name: from schema: type: string format: date-time description: Inclusive. - in: query required: false name: to schema: type: string format: date-time description: Inclusive. responses: '200': description: Success. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/FinanceSummaryBucket' window: type: object properties: from: type: - string - 'null' to: type: - string - 'null' asOf: type: string format: date-time '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: INVALID_INPUT: summary: 'INVALID_INPUT: from and to must be ISO-8601 dates' value: error: from and to must be ISO-8601 dates code: INVALID_INPUT '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' examples: API_key_required_Pass_it_via_X_API_Key_header: summary: API key required. Pass it via X-API-Key header. value: error: API key required. Pass it via X-API-Key header. Invalid_API_key: summary: Invalid API key. value: error: Invalid API key. '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' examples: SECRET_KEY_REQUIRED: summary: 'SECRET_KEY_REQUIRED: This route needs a secret server key' value: error: This route needs a secret server key code: SECRET_KEY_REQUIRED WRONG_COMMUNITY: summary: 'WRONG_COMMUNITY: API key does not belong to this community' value: error: API key does not belong to this community code: WRONG_COMMUNITY API_key_missing_required_scope_READ_FINANCE: summary: 'API key missing required scope: READ_FINANCE' value: error: 'API key missing required scope: READ_FINANCE' grantedScopes: - READ_PUBLIC '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: COMMUNITY_NOT_FOUND: summary: 'COMMUNITY_NOT_FOUND: Community not found' value: error: Community not found code: COMMUNITY_NOT_FOUND '429': description: Rate limited. content: application/json: schema: $ref: '#/components/schemas/Error' examples: RATE_LIMITED: summary: 'RATE_LIMITED: Too many requests' value: error: Too many requests code: RATE_LIMITED '503': description: Temporarily unavailable; retry after the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Service_temporarily_unavailable: summary: Service temporarily unavailable value: error: Service temporarily unavailable components: securitySchemes: ApiKey: type: apiKey in: header name: X-API-Key description: 'Community API key (`ck_...`), publishable or secret. `Authorization: Bearer ` is also accepted.' UserApiKey: type: apiKey in: header name: X-API-Key description: Personal user key (`uk_...`) with scope `READ_OWN`. MemberSession: type: apiKey in: header name: X-Cobuntu-Auth-Token description: Member session token returned by the Auth endpoints. Forward it from your server. MemberToken: type: apiKey in: header name: X-Cobuntu-Member-Token description: Signed member token issued for this community (alternative member identity on event endpoints). CobuntuSession: type: http scheme: bearer description: The member's own Cobuntu session (used only by the app handoff mint, called from the community app). parameters: EndUserIp: name: X-End-User-IP in: header required: false schema: type: string description: The end user's IP when calling from your server, so per-visitor rate limits apply to the visitor. CartToken: name: X-Cobuntu-Cart-Token in: header required: false schema: type: string description: Guest cart token returned by `POST /cart`. IdempotencyKey: name: X-Idempotency-Key in: header required: false schema: type: string description: 'Makes retries safe: the same key returns the same checkout.' schemas: Error: type: object required: - error description: >- Every error response. `code` is present where the endpoint documents one; some errors carry extra detail fields (for example `missingFields`, `remaining`, `hint`). properties: error: type: string description: Human-readable message. Do not branch on it; use `code`. code: type: string description: Machine-readable error code, when documented. hint: type: string additionalProperties: true Pagination: type: object properties: total: type: integer limit: type: integer offset: type: integer hasMore: type: boolean User: type: object properties: id: type: string name: type: string email: type: string format: email avatar: type: - string - 'null' Session: type: object properties: token: type: string description: Member session token. Forward it as `X-Cobuntu-Auth-Token`. user: $ref: '#/components/schemas/User' newMember: type: boolean description: True when this call just joined an open community. Location: type: object properties: id: type: string kind: type: string enum: - PHYSICAL - ONLINE label: type: - string - 'null' isPrimary: type: boolean sortOrder: type: integer address: type: - string - 'null' latitude: type: - number - 'null' longitude: type: - number - 'null' url: type: - string - 'null' hidden: type: boolean MemberOffer: type: object properties: segmentName: type: string price: type: integer description: In the smallest currency unit (cents). mode: type: string enum: - FREE - PERCENT_OFF - FLAT_OFF - FIXED_PRICE Tier: type: object properties: id: type: string name: type: string description: type: - string - 'null' price: type: integer description: List price. In the smallest currency unit (cents). currency: type: string capacity: type: - integer - 'null' remaining: type: - integer - 'null' soldCount: type: - integer - 'null' soldOut: type: - boolean - 'null' priceMode: type: string description: FIXED or pay-what-you-want. pwywMinAmount: type: - integer - 'null' description: Minimum for pay-what-you-want tiers. In the smallest currency unit (cents). installmentTotalPrice: type: - integer - 'null' installmentCount: type: - integer - 'null' installmentIntervalMonths: type: - integer - 'null' hasForm: type: boolean description: True when the tier has a registration form (see GET /tiers/{tierId}/form). publishedAt: type: - string - 'null' format: date-time salesStartAt: type: - string - 'null' format: date-time salesEndAt: type: - string - 'null' format: date-time isOnSale: type: boolean state: type: string memberPrice: type: - integer - 'null' description: Price for the identified member, if they qualify. In the smallest currency unit (cents). memberPriceMode: type: - string - 'null' publicMemberOffers: type: array items: $ref: '#/components/schemas/MemberOffer' Event: type: object properties: id: type: string slug: type: string createdAt: type: string format: date-time name: type: string description: type: - string - 'null' bannerUrl: type: - string - 'null' cardImageUrl: type: - string - 'null' startDate: type: string format: date-time endDate: type: string format: date-time timezone: type: string physicalLocation: type: - string - 'null' physicalLatitude: type: - number - 'null' physicalLongitude: type: - number - 'null' onlineUrl: type: - string - 'null' description: Only for attendees. locationVisibility: type: string locations: type: array items: $ref: '#/components/schemas/Location' locationFormat: type: string enum: - HYBRID - PHYSICAL - ONLINE - TBA accessibility: type: string viewability: type: string requiresApproval: type: boolean donationConfig: type: - object - 'null' featured: type: boolean detailSource: type: string externalDetailUrl: type: - string - 'null' externalListings: type: array items: type: object properties: platform: type: string url: type: string tiers: type: array items: $ref: '#/components/schemas/Tier' tags: type: array items: type: object properties: id: type: string name: type: string agenda: type: array items: type: object properties: title: type: string description: type: - string - 'null' startTime: type: string format: date-time endTime: type: string format: date-time order: type: integer hosts: type: array items: type: object properties: id: type: string role: type: string user: type: object properties: id: type: string name: type: string usertag: type: string profileImage: type: - string - 'null' attendeeCount: type: - integer - 'null' isAttending: type: boolean categoryId: type: - string - 'null' subCategoryId: type: - string - 'null' category: type: - object - 'null' properties: id: type: string name: type: string subcategory: type: - object - 'null' properties: id: type: string name: type: string EventFacetCount: type: object properties: id: type: string name: type: string count: type: integer EventFacets: type: object properties: total: type: integer categories: type: array items: allOf: - $ref: '#/components/schemas/EventFacetCount' - type: object properties: subcategories: type: array items: $ref: '#/components/schemas/EventFacetCount' uncategorized: type: integer price: type: object properties: free: type: integer paid: type: integer format: type: object properties: in_person: type: integer online: type: integer hybrid: type: integer tba: type: integer Ticket: type: object properties: eventSlug: type: string eventName: type: string startDate: type: string format: date-time endDate: type: string format: date-time bannerUrl: type: - string - 'null' tierId: type: string tierName: type: string status: type: string enum: - CONFIRMED - PENDING quantity: type: integer saleId: type: - string - 'null' refundable: type: boolean Membership: type: - object - 'null' properties: segmentId: type: string segmentName: type: - string - 'null' status: type: string enum: - PENDING - ACTIVE - PAST_DUE - TRIALING - CANCELLED - EXPIRED billingCycle: type: string currentPeriodEnd: type: - string - 'null' format: date-time cancelAtPeriodEnd: type: boolean Onboarding: type: object additionalProperties: true description: What the member still owes the community, with everything needed to render each step. properties: complete: type: boolean nextStep: type: - string - 'null' steps: type: object additionalProperties: type: object properties: required: type: boolean done: type: boolean dataSegmentId: type: - string - 'null' rules: type: array items: type: object properties: id: type: string title: type: string description: type: - string - 'null' linkUrl: type: - string - 'null' linkLabel: type: - string - 'null' order: type: integer tiers: type: array items: type: object properties: id: type: string name: type: string description: type: - string - 'null' color: type: - string - 'null' isDefault: type: boolean paid: type: boolean form: type: object properties: segmentId: type: string title: type: - string - 'null' description: type: - string - 'null' formSource: type: string embedFormUrl: type: - string - 'null' stepLabels: type: array items: type: string fields: type: array items: $ref: '#/components/schemas/FormField' FormField: type: object properties: id: type: string type: type: string label: type: string required: type: boolean options: type: array items: type: object properties: id: type: string label: type: string Profile: type: object properties: id: type: string name: type: string email: type: string bio: type: - string - 'null' avatarUrl: type: - string - 'null' phone: type: - string - 'null' location: type: - string - 'null' locationVisibility: type: string enum: - PUBLIC - CIRCLE - 'OFF' description: 'Who sees `location`: PUBLIC anyone, CIRCLE fellow members, OFF nobody.' languages: type: array items: type: string hideFromDirectory: type: boolean description: Leave the members directory. The profile still opens by handle. usertag: type: - string - 'null' pronouns: type: - string - 'null' gender: type: - string - 'null' signature: type: - string - 'null' socials: type: array items: type: object properties: url: type: string label: type: string birthday: type: - object - 'null' properties: month: type: integer day: type: integer emailVisibility: type: string enum: - PUBLIC - CIRCLE - 'OFF' phoneVisibility: type: string enum: - PUBLIC - CIRCLE - 'OFF' description: 'PUBLIC is stored as CIRCLE: a phone is never public.' isPremium: type: boolean bioMaxLength: type: integer friendsCount: type: integer Preferences: type: object properties: locale: type: - string - 'null' timeFormat: type: - string - 'null' enum: - H12 - H24 - null receivePromotionalContent: type: boolean notifications: type: object properties: eventsEmail: type: boolean postsEmail: type: boolean announcementsEmail: type: boolean Note: type: object properties: id: type: string content: type: string category: type: string enum: - LOOKING_FOR - OFFERING - OPEN_TO - WORKING_ON - CUSTOM sortOrder: type: integer freshSince: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time MemberTier: type: object properties: id: type: string name: type: string color: type: - string - 'null' DirectoryMember: type: object properties: userId: type: string usertag: type: - string - 'null' name: type: string profileImage: type: - string - 'null' bio: type: - string - 'null' pronouns: type: - string - 'null' socials: type: - array - 'null' description: 'Raw: plain URLs or labelled links.' items: {} location: type: - string - 'null' description: null when hidden by the member's location visibility. languages: type: array items: type: string tiers: type: array items: $ref: '#/components/schemas/MemberTier' role: type: string description: '`founder`, else the first role group name in lowercase, else `member`.' isFounder: type: boolean verified: type: boolean joinedAt: type: - string - 'null' format: date-time FacetCount: type: object properties: value: type: string count: type: integer Application: type: object properties: requestId: type: string segmentId: type: string segmentName: type: - string - 'null' status: type: string enum: - PENDING - PAYMENT_PENDING - RESERVED - APPROVED - REJECTED submittedAt: type: string format: date-time CheckoutRedirect: type: object properties: checkoutUrl: type: string format: uri description: Send the buyer here. sessionId: type: - string - 'null' Segment: type: object properties: id: type: string name: type: string description: type: - string - 'null' color: type: - string - 'null' hasForm: type: boolean formKey: type: - string - 'null' priceMonthly: type: - integer - 'null' description: In the smallest currency unit (cents). priceYearly: type: - integer - 'null' description: In the smallest currency unit (cents). priceOneTime: type: - integer - 'null' description: In the smallest currency unit (cents). foundingMemberCap: type: - integer - 'null' foundingMemberCount: type: - integer - 'null' installmentTotalPrice: type: - integer - 'null' installmentCount: type: - integer - 'null' installmentIntervalMonths: type: - integer - 'null' accessDurationMonths: type: - integer - 'null' currency: type: string prices: type: array items: type: object Article: type: object properties: id: type: string title: type: string slug: type: string excerpt: type: - string - 'null' content: type: - string - 'null' metaTitle: type: - string - 'null' keywords: type: array items: type: string references: type: array items: type: object properties: label: type: string url: type: - string - 'null' bannerUrl: type: - string - 'null' category: type: - string - 'null' status: type: string enum: - DRAFT - PUBLISHED publishedAt: type: - string - 'null' format: date-time readTimeMinutes: type: - integer - 'null' createdAt: type: string format: date-time updatedAt: type: string format: date-time ProductCategoryRef: type: - object - 'null' properties: id: type: string name: type: string iconId: type: - string - 'null' iconColor: type: - string - 'null' ProductSeller: type: object properties: type: type: string enum: - community - member name: type: string usertag: type: - string - 'null' description: null for the community. imageUrl: type: - string - 'null' ProductVariant: type: object properties: id: type: string description: The variant (tier) id. Send it as `tierId` at checkout. name: type: string description: type: - string - 'null' licenseTerms: type: - string - 'null' maxDownloads: type: - integer - 'null' attributes: type: - array - 'null' items: type: object properties: key: type: string value: type: string description: Structured attributes (Colour, Size, Material, ...). productType: type: - string - 'null' condition: type: - string - 'null' parcelClass: type: - string - 'null' shippingPrice: type: - integer - 'null' description: null = postage included. In the smallest currency unit (cents). sortOrder: type: integer priceMode: type: - string - 'null' pwywMinAmount: type: - integer - 'null' publishedAt: type: - string - 'null' format: date-time salesStartAt: type: - string - 'null' format: date-time salesEndAt: type: - string - 'null' format: date-time isOnSale: type: boolean state: type: string attachmentCount: type: integer hasForm: type: boolean description: 'Collects answers at checkout: fetch `GET /tiers/{tierId}/form` and send `formAnswers`.' capacity: type: - integer - 'null' description: null = uncapped. remaining: type: - integer - 'null' description: null when uncapped. Floored at 0. soldOut: type: - boolean - 'null' installmentTotalPrice: type: - integer - 'null' installmentCount: type: - integer - 'null' installmentIntervalMonths: type: - integer - 'null' memberPrice: type: - integer - 'null' description: >- The signed-in member's own price, only with a member session that qualifies. In the smallest currency unit (cents). memberPriceMode: type: - string - 'null' enum: - FREE - PERCENT_OFF - FLAT_OFF - FIXED_PRICE - null publicMemberOffers: type: array items: $ref: '#/components/schemas/MemberOffer' product: type: - object - 'null' description: The variant's own price row. properties: id: type: string sku: type: - string - 'null' price: type: integer description: In the smallest currency unit (cents). currency: type: string isRecurring: type: boolean recurringInterval: type: - string - 'null' Product: type: object properties: id: type: string name: type: string sku: type: - string - 'null' description: type: - string - 'null' bannerImageUrl: type: - string - 'null' cardImageUrl: type: - string - 'null' price: type: integer description: In the smallest currency unit (cents). currency: type: string productType: type: string isRecurring: type: boolean recurringInterval: type: - string - 'null' ctaText: type: - string - 'null' condition: type: - string - 'null' parcelClass: type: - string - 'null' shippingPrice: type: - integer - 'null' description: null = postage included in the price. In the smallest currency unit (cents). avgRating: type: number reviewCount: type: integer category: $ref: '#/components/schemas/ProductCategoryRef' subcategory: $ref: '#/components/schemas/ProductCategoryRef' attachmentCount: type: integer description: How many deliverables a buyer gets. The files are reached after purchase. media: type: array items: type: object properties: url: type: string mimeType: type: - string - 'null' creator: type: object description: Kept for older callers; prefer `seller`. properties: name: type: string iconUrl: type: - string - 'null' seller: $ref: '#/components/schemas/ProductSeller' installmentTotalPrice: type: - integer - 'null' installmentCount: type: - integer - 'null' installmentIntervalMonths: type: - integer - 'null' tags: type: array items: type: object properties: id: type: string name: type: string variants: type: array items: $ref: '#/components/schemas/ProductVariant' pageUrl: type: string ProductFacets: type: object properties: total: type: integer categories: type: array items: allOf: - $ref: '#/components/schemas/EventFacetCount' - type: object properties: subcategories: type: array items: $ref: '#/components/schemas/EventFacetCount' uncategorized: type: integer type: type: object properties: DIGITAL: type: integer PHYSICAL: type: integer price: type: object properties: free: type: integer paid: type: integer seller: type: object properties: community: type: integer member: type: integer BasketItem: type: object properties: productId: type: string sku: type: string tierId: type: string description: Required when the product has more than one variant. quantity: type: integer minimum: 1 maximum: 10 default: 1 customAmount: type: integer description: Pay-what-you-want amount. In the smallest currency unit (cents). formAnswers: type: object additionalProperties: true description: Only on a one-item product order. Never on a ticket line. attendees: type: array items: $ref: '#/components/schemas/BasketAttendee' description: >- Ticket lines only. Entry i is place i of the line; missing entries default to the buyer. At most `quantity` entries. BasketAttendee: type: object properties: name: type: string email: type: string format: email formAnswers: type: object additionalProperties: true description: Answers to the tier form for this place, keyed by field id. BasketGroup: type: object properties: lines: type: array items: type: integer description: Indexes into `items[]`. mode: type: string enum: - payment - subscription reason: type: string enum: - MAIN - PHYSICAL - INSTALMENTS - RECURRING requiresAccount: type: boolean QuoteGroup: allOf: - $ref: '#/components/schemas/BasketGroup' - type: object properties: subtotal: type: integer description: In the smallest currency unit (cents). shipping: type: integer description: In the smallest currency unit (cents). total: type: integer description: In the smallest currency unit (cents). currency: type: string Quote: type: object properties: lines: type: array items: type: object properties: productId: type: string sku: type: - string - 'null' tierId: type: - string - 'null' name: type: string tierName: type: - string - 'null' unitPrice: type: integer description: In the smallest currency unit (cents). quantity: type: integer lineTotal: type: integer description: In the smallest currency unit (cents). currency: type: string appliedMemberPricingId: type: - string - 'null' listPrice: type: integer description: In the smallest currency unit (cents). isCustomAmount: type: boolean offersDonation: type: boolean productType: type: string maxQuantity: type: - integer - 'null' index: type: integer description: Index into `items[]`. kind: type: string enum: - PRODUCT - TICKET eventId: type: - string - 'null' requiresApproval: type: boolean description: 'Ticket lines: charged now and held until the host decides.' subtotal: type: integer description: Summed over groups. In the smallest currency unit (cents). shipping: type: integer description: In the smallest currency unit (cents). total: type: integer description: Excludes tax (computed at payment). In the smallest currency unit (cents). currency: type: string memberSavings: type: integer description: In the smallest currency unit (cents). offersDonation: type: boolean requiresShipping: type: boolean parcelClass: type: - string - 'null' allowedShippingCountries: type: - array - 'null' items: type: string groups: type: array items: $ref: '#/components/schemas/QuoteGroup' description: The checkouts this basket is paid in. One for most baskets. PurchaseProduct: type: object properties: id: type: - string - 'null' sku: type: - string - 'null' name: type: - string - 'null' imageUrl: type: - string - 'null' productType: type: - string - 'null' PurchaseDownload: type: object properties: attachmentId: type: string name: type: string kind: type: string enum: - FILE - LINK mimeType: type: - string - 'null' fileSize: type: - integer - 'null' maxDownloads: type: - integer - 'null' downloadsUsed: type: - integer - 'null' remainingDownloads: type: - integer - 'null' url: type: - string - 'null' description: 'LINK: open directly.' downloadUrl: type: - string - 'null' description: 'FILE: the download route.' Purchase: type: object properties: saleId: type: string transactionId: type: - string - 'null' purchasedAt: type: string format: date-time product: $ref: '#/components/schemas/PurchaseProduct' variant: type: - object - 'null' properties: tierId: type: string name: type: - string - 'null' quantity: type: integer amount: type: integer description: In the smallest currency unit (cents). shippingAmount: type: integer description: In the smallest currency unit (cents). currency: type: string refundStatus: type: string approvalStatus: type: - string - 'null' shippedAt: type: - string - 'null' format: date-time deliveredAt: type: - string - 'null' format: date-time refundable: type: boolean refundReason: type: - string - 'null' refundWindowEndsAt: type: - string - 'null' format: date-time invoiceUrl: type: string receiptUrl: type: string downloads: type: array items: $ref: '#/components/schemas/PurchaseDownload' description: Empty while the purchase grants no access (refunded, or awaiting approval). GuestSale: type: object properties: saleId: type: string email: type: string purchasedAt: type: string format: date-time product: $ref: '#/components/schemas/PurchaseProduct' variant: type: - object - 'null' properties: tierId: type: string name: type: - string - 'null' quantity: type: integer amount: type: integer description: In the smallest currency unit (cents). shippingAmount: type: integer description: In the smallest currency unit (cents). currency: type: string refundStatus: type: string refundable: type: boolean refundReason: type: - string - 'null' refundWindowEndsAt: type: - string - 'null' format: date-time invoiceUrl: type: - string - 'null' description: The hosted invoice page, or null until issued. hasReceipt: type: boolean Category: type: object properties: id: type: string name: type: string description: type: - string - 'null' iconId: type: - string - 'null' iconColor: type: - string - 'null' imageUrl: type: - string - 'null' sortOrder: type: integer subcategories: type: array items: type: object properties: id: type: string name: type: string description: type: - string - 'null' iconId: type: - string - 'null' iconColor: type: - string - 'null' imageUrl: type: - string - 'null' sortOrder: type: integer Member: type: object properties: userId: type: string name: type: string usertag: type: string profileImage: type: - string - 'null' bio: type: - string - 'null' pronouns: type: - string - 'null' socials: type: - object - 'null' roleGroups: type: array items: type: object properties: name: type: string color: type: - string - 'null' joinedAt: type: string format: date-time friendsCount: type: integer communitiesCount: type: integer profileUrl: type: string MemberMembership: type: object properties: userId: type: string usertag: type: string status: type: string joinedAt: type: string format: date-time roleGroups: type: array items: type: object properties: name: type: string color: type: - string - 'null' isSystem: type: boolean permissions: type: array items: type: string segments: type: array items: type: object properties: segmentId: type: string name: type: string isDefault: type: boolean currentPeriodEnd: type: - string - 'null' format: date-time required: - userId - status - roleGroups CartLine: type: object properties: id: type: string description: Cart item id (for PATCH / DELETE /cart/items/{itemId}). productId: type: string description: The product the buyer browsed. checkoutProductId: type: string description: >- The id checkout and quote key on. For a variant line this is the variant's own backing product, not `productId`. tierId: type: - string - 'null' quantity: type: integer name: type: string tierName: type: - string - 'null' sku: type: - string - 'null' unitPrice: type: - integer - 'null' description: Resolved live; null while unavailable. In the smallest currency unit (cents). lineTotal: type: - integer - 'null' description: In the smallest currency unit (cents). currency: type: string imageUrl: type: - string - 'null' productType: type: - string - 'null' unavailableReason: type: - string - 'null' description: >- Set when the line can no longer be bought (listing pulled, sales window closed). Kept in the cart, left out of `subtotal`. Cart: type: object properties: id: type: string communityId: type: string items: type: array items: $ref: '#/components/schemas/CartLine' description: Oldest first. At most 50 lines. subtotal: type: integer description: Buyable lines only. In the smallest currency unit (cents). currency: type: string totalItems: type: integer description: Sum of quantities. AppDataEntry: type: object properties: key: type: string value: description: Any JSON value. updatedAt: type: string format: date-time RefundResult: type: object additionalProperties: true description: The created refund request (id, status, amount in cents). ProfileEvent: type: object additionalProperties: true description: An event on a member profile Events tab, in the community app's own event shape plus the fields below. properties: id: type: string slug: type: - string - 'null' name: type: string description: type: - string - 'null' startDate: type: - string - 'null' format: date-time endDate: type: - string - 'null' format: date-time timezone: type: - string - 'null' bannerUrl: type: - string - 'null' cardImageUrl: type: - string - 'null' physicalLocation: type: - string - 'null' isOnline: type: boolean status: type: - string - 'null' description: 'Virtual: PUBLISHED when a listing is live, else DRAFT. Read `isDraft`, not this.' catalogStatus: type: string enum: - LIVE - PENDING - HIDDEN - REJECTED - DRAFT description: Owner view only. catalogRejectionReason: type: string description: Present when a community declined the listing with a reason. isDraft: type: boolean description: True for an unfinished wizard draft. draftStep: type: - string - 'null' description: The wizard step a draft was left on. MemberEvent: type: object properties: id: type: string slug: type: - string - 'null' name: type: string startDate: type: - string - 'null' format: date-time endDate: type: - string - 'null' format: date-time bannerUrl: type: - string - 'null' status: type: - string - 'null' description: Event status, for example PUBLISHED or CANCELLED. attendanceStatus: type: - string - 'null' enum: - APPROVED - PENDING - null description: null when the member only hosts the event. transactionId: type: - string - 'null' description: The latest purchase for this event, if any. isHosting: type: boolean LedgerEntry: type: object properties: id: type: string description: '`purchase:`, `refund:` or `sale:`.' type: type: string enum: - PURCHASE - REFUND - SALE direction: type: string enum: - in - out description: PURCHASE is out; REFUND and SALE are in. amount: type: integer description: >- PURCHASE: gross paid. REFUND: amount refunded. SALE: the member's net earning. In the smallest currency unit (cents). currency: type: string date: type: string format: date-time saleId: type: string transactionId: type: - string - 'null' item: type: object properties: kind: type: string enum: - product - event - membership - unknown name: type: string counterpart: type: - object - 'null' description: The buyer on a SALE. null on the member's own purchases. properties: name: type: string usertag: type: - string - 'null' status: type: string description: Refund status of the sale (NONE, PARTIAL, FULL, ...); COMPLETED on a REFUND entry. fees: type: - object - 'null' description: SALE only. properties: gross: type: integer platformFee: type: integer stripeFees: type: integer stripeTaxFee: type: integer payout: type: - object - 'null' description: SALE only. properties: status: type: string description: ESCROW, PAID, ... eligibleAt: type: string format: date-time paidOutAt: type: - string - 'null' format: date-time refund: type: - object - 'null' properties: amount: type: integer date: type: string format: date-time reason: type: - string - 'null' invoiceUrl: type: - string - 'null' description: Path of `me/sales/{saleId}/invoice`. Own purchases only. receiptUrl: type: - string - 'null' description: Path of `me/sales/{saleId}/receipt`. invoiceAvailable: type: boolean LedgerSummary: type: object properties: totals: type: array items: type: object properties: currency: type: string spent: type: integer refunded: type: integer earned: type: integer fees: type: integer description: >- Over the filtered entries, one row per currency. Never summed across currencies. `earned` and `fees` count non-refunded sales only. pendingPayouts: type: integer description: Payout state for this community, unfiltered. In the smallest currency unit (cents). readyForPayout: type: integer description: In the smallest currency unit (cents). inEscrowPeriod: type: integer description: In the smallest currency unit (cents). LibraryItem: type: object properties: saleId: type: string purchasedAt: type: string format: date-time awaitingApproval: type: boolean description: An approval-gated purchase not yet approved. `downloads` is empty until it is. product: type: object properties: id: type: - string - 'null' sku: type: - string - 'null' name: type: string description: type: - string - 'null' imageUrl: type: - string - 'null' productType: type: string enum: - DIGITAL - COURSE - PHYSICAL creator: type: object properties: name: type: - string - 'null' usertag: type: - string - 'null' avatar: type: - string - 'null' downloads: type: array items: type: object properties: attachmentId: type: string name: type: string kind: type: string enum: - FILE - LINK mimeType: type: - string - 'null' fileSize: type: - integer - 'null' url: type: - string - 'null' description: LINK only. downloadUrl: type: - string - 'null' description: 'FILE only: the `me/purchases/.../download` path (counted, signed).' EventDraftSummary: type: object properties: id: type: string kind: type: string enum: - event name: type: - string - 'null' draftStep: type: - string - 'null' updatedAt: type: string format: date-time communityId: type: - string - 'null' description: Set for a community-owned draft; null for a personal one. productType: type: 'null' MemberPackage: type: object properties: id: type: string name: type: string description: type: - string - 'null' rate: type: number description: The community's cut, as a percentage (20 = 20%). sortOrder: type: integer segmentId: type: - string - 'null' EventWrite: type: object properties: name: type: string minLength: 1 description: type: - string - 'null' bannerUrl: type: - string - 'null' cardImageUrl: type: - string - 'null' startDate: type: string format: date-time endDate: type: string format: date-time timezone: type: string description: IANA time zone, for example Europe/Lisbon. locations: type: array items: type: object properties: kind: type: string enum: - PHYSICAL - ONLINE label: type: string address: type: string url: type: string isPrimary: type: boolean required: - kind physicalLocation: type: string FinanceFees: type: object properties: platform: type: integer description: Cobuntu platform fee, negative. In the smallest currency unit (cents). stripe: type: integer description: Stripe processing, negative. In the smallest currency unit (cents). stripeTax: type: integer description: Stripe tax fee, negative. In the smallest currency unit (cents). memberSeller: type: integer description: Member seller fee, negative. Zero on a community-owned sale. In the smallest currency unit (cents). FinanceEntry: type: object properties: id: type: string cursor: type: string description: Opaque resume token for THIS entry. Pass it as ?cursor=. Do not build one from `id`. type: type: string enum: - SALE - COMMISSION description: A refund is reported on the sale it refunded (see `refund`), not as its own entry. stream: type: string enum: - EVENT - DIGITAL - COURSE - PHYSICAL - MEMBERSHIP - DONATION - OTHER role: type: string enum: - SELLER - COMMISSION_RECIPIENT description: >- Whose money `net` is. SELLER = the community sold its own thing. COMMISSION_RECIPIENT = a MEMBER sold and the community keeps only its commission; `gross` on such a row is the member's sale value, not community revenue. occurredAt: type: string format: date-time currency: type: string gross: type: integer description: In the smallest currency unit (cents). shipping: type: integer description: In the smallest currency unit (cents). tip: type: integer description: Buyer tip, paid to the seller. In the smallest currency unit (cents). vat: type: integer description: In the smallest currency unit (cents). fees: $ref: '#/components/schemas/FinanceFees' net: type: integer description: What the community earned. Read `role` first. In the smallest currency unit (cents). settlement: type: object properties: status: type: - string - 'null' enum: - ESCROW - HOLD - ELIGIBLE - PAID - FAILED - BLOCKED - null description: >- Where the money is. ESCROW = inside the refund window. HOLD = releasable but below the transfer threshold. ELIGIBLE = waiting for the next transfer run. PAID = transferred. FAILED = a transfer was attempted and did not succeed. BLOCKED is NOT a sanction: it means the sale will never pay out, and here that always means a FULL refund, so the entry also carries `refund` and reports `net: 0` — render it as refunded. payoutId: type: - string - 'null' paidAt: type: - string - 'null' format: date-time item: type: object properties: name: type: - string - 'null' productType: type: - string - 'null' id: type: - string - 'null' buyerRef: type: - string - 'null' description: Opaque, stable per buyer. Null for a guest, and null after the buyer exercises erasure. buyer: type: object properties: email: type: - string - 'null' name: type: - string - 'null' refund: type: object properties: refundedAt: type: - string - 'null' format: date-time amount: type: integer description: Amount refunded to the buyer. In the smallest currency unit (cents). status: type: - string - 'null' description: >- Present only when this sale was refunded. A fully refunded sale already reports net 0 — do not subtract this again. reference: type: object properties: saleId: type: - string - 'null' transactionId: type: - string - 'null' FinancePayout: type: object properties: id: type: string cursor: type: string type: type: - string - 'null' status: type: string currency: type: string amount: type: integer description: In the smallest currency unit (cents). salesCount: type: integer createdAt: type: string format: date-time paidAt: type: - string - 'null' format: date-time stripeTransferId: type: - string - 'null' RemittanceLine: type: object properties: payoutId: type: string type: type: - string - 'null' amount: type: integer description: In the smallest currency unit (cents). salesCount: type: integer paidAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time invoiceNumber: type: - string - 'null' description: The invoice already issued for this payout. RemittanceStatement: type: object properties: deposit: type: object properties: id: type: string stripePayoutId: type: string amount: type: integer description: The bank credit. In the smallest currency unit (cents). currency: type: string status: type: string arrivalDate: type: - string - 'null' format: date-time paidAt: type: - string - 'null' format: date-time community: type: object properties: id: type: string name: type: string tag: type: string lines: type: array items: $ref: '#/components/schemas/RemittanceLine' totals: type: object properties: covered: type: integer description: Sum of the Cobuntu payouts in this deposit. In the smallest currency unit (cents). deposit: type: integer description: The bank credit itself. In the smallest currency unit (cents). unaccounted: type: integer description: >- deposit - covered. Normally 0. Non-zero means the deposit also carried money that did not come through Cobuntu, which is legitimate when the same Stripe account takes payments directly. In the smallest currency unit (cents). FinanceSummaryBucket: type: object properties: currency: type: string byStream: type: object additionalProperties: type: object properties: count: type: integer net: type: integer description: In the smallest currency unit (cents). byType: type: object additionalProperties: type: object properties: count: type: integer net: type: integer description: In the smallest currency unit (cents). net: type: integer description: In the smallest currency unit (cents). count: type: integer