Communities and Spaces

Cativa organizes content in a four-level hierarchy. Understanding this hierarchy is essential to know which endpoint to call and what can be created via API versus what’s configured by the admin in the dashboard.

The hierarchy

Community (the entire tenant platform)
└── Space (thematic area, e.g. "Trading", "Mentoring")
    └── Group (sub-community inside the space)
        ├── Post (feed publication)
        ├── Comment (comment on a post)
        └── Course (sequence of lessons, optional)

Every tenant has exactly one Community (the customer’s whole site). Inside it, the admin creates multiple Spaces, each with its own Groups. Groups contain Posts, Comments and, optionally, Courses.

The difference between Space and Group is easy to remember: Space is the thematic division shown in the main navigation; Group is where conversation happens and where badge-based permissions are applied.

Who creates what

The general rule: structure is the admin’s job, content is the partner’s job.

Resource	Via API (partner)	In admin dashboard
Community	No	Yes (created on tenant provisioning)
Space	Typically no (admin scope only)	Yes
Group	Typically no (admin scope only)	Yes
Post	Yes	Yes
Comment	Yes	Yes
Course	Typically no (admin scope only)	Yes

Endpoints to create Space, Group and Course exist but require admin scope. Partner keys with default scope (recommended) cannot reach them. Ask the tenant admin to set up the structure in the dashboard: that’s the natural flow. The write sections below assume a key with admin scope.

Access control: badge gates the group

Each Group can require one or more badges for a user to enter. This is configured in the dashboard, on each group’s access screen:

Group "VIP Members"  --requires-->   Badge "Premium"
Group "Mentors"      --requires-->   Badge "Mentor"
Group "Open"         --no badge-->   any user can enter

The partner does not configure this rule (it lives in the admin) but triggers the transition: by assigning a badge to the user, they gain automatic access to every group that accepts that badge. See Badges as Permissions.

Read endpoints

Even without creating structure, you almost always need to read groups: to show them to the user in your app or to discover IDs before creating posts.

List groups

GET /community/groups returns a paginated list. It accepts a space filter and pagination.

curl "https://apis.cativalab.digital/tenant/api/v2/community/groups?spaceId=01HQ0...&pageNumber=1" \
  -H "Authorization: Bearer cativa_live_..."

const res = await fetch(
  'https://apis.cativalab.digital/tenant/api/v2/community/groups?pageNumber=1',
  { headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` } }
);
const page = await res.json();

Illustrative response (paginated):

{
  "items": [
    {
      "id": "01HQ5ABCDEF1234567890XYZ",
      "ownerId": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
      "name": "VIP Members",
      "coverUrl": "https://cdn.cativalab.digital/groups/vip.png",
      "description": "Exclusive group for Premium subscribers.",
      "icon": "crown",
      "isPrivate": true,
      "spaceId": "01HQ0ABCDEF1234567890XYZ",
      "courseId": null,
      "onlyModeratorsCanPost": false,
      "hasFeed": true,
      "hasChat": true,
      "membersCount": 128,
      "isInGroup": false,
      "isModerator": false
    }
  ],
  "total": 12,
  "pageNumber": 1,
  "hasNextPage": true
}

The JSON on this page is illustrative. The authoritative field-by-field schema lives in the API Reference tab (Group tag).

Group detail

GET /community/groups/{groupId} returns the full group, including allowedBadges (the badges that unlock entry) and the caller’s own flags (isInGroup, isModerator).

curl https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5... \
  -H "Authorization: Bearer cativa_live_..."

{
  "id": "01HQ5ABCDEF1234567890XYZ",
  "name": "VIP Members",
  "description": "Exclusive group for Premium subscribers.",
  "isPrivate": true,
  "spaceId": "01HQ0ABCDEF1234567890XYZ",
  "allowedBadges": ["01HQ4ABCDEF1234567890XYZ"],
  "hasFeed": true,
  "hasChat": true,
  "membersCount": 128,
  "isInGroup": false,
  "isModerator": false
}

List members

GET /community/groups/{groupId}/members returns paginated members, with role, moderator flag, and access expiration date (when present).

curl "https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../members?pageNumber=1" \
  -H "Authorization: Bearer cativa_live_..."

{
  "items": [
    {
      "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
      "displayName": "Mary Smith",
      "pictureUrl": "https://cdn.cativalab.digital/avatars/mary.png",
      "role": 0,
      "isModerator": false,
      "expirationDate": "2026-12-31T23:59:59Z",
      "createdAt": "2026-07-10T12:00:00Z"
    }
  ],
  "total": 128,
  "pageNumber": 1,
  "hasNextPage": true
}

Group CRUD (admin scope)

Operation	Method and route
Create group	`POST /community/groups`
Update group	`PUT /community/groups/{groupId}`
Delete group	`DELETE /community/groups/{groupId}`

Create a group

curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/groups \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Members",
    "description": "Exclusive group for Premium subscribers.",
    "isPrivate": true,
    "icon": "crown",
    "addNewUsers": false,
    "spaceId": "01HQ0ABCDEF1234567890XYZ",
    "onlyModeratorsCanPost": false,
    "hasFeed": true,
    "hasChat": true,
    "allowedBadges": ["01HQ4ABCDEF1234567890XYZ"]
  }'

const res = await fetch('https://apis.cativalab.digital/tenant/api/v2/community/groups', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CATIVA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'VIP Members',
    description: 'Exclusive group for Premium subscribers.',
    isPrivate: true,
    icon: 'crown',
    addNewUsers: false,
    spaceId: '01HQ0ABCDEF1234567890XYZ',
    onlyModeratorsCanPost: false,
    hasFeed: true,
    hasChat: true,
    allowedBadges: ['01HQ4ABCDEF1234567890XYZ']
  })
});
const group = await res.json();

Illustrative response (201 Created):

{
  "id": "01HQ5ABCDEF1234567890XYZ",
  "name": "VIP Members",
  "coverUrl": null,
  "description": "Exclusive group for Premium subscribers.",
  "icon": "crown",
  "isPrivate": true
}

allowedBadges on create already binds the group to the badges that unlock entry, without touching the dashboard. Combine it with badge assignment to automate access end to end.

Members: join, leave, invite, and remove

Operation	Method and route
Join	`POST /community/groups/{groupId}/join`
Leave	`POST /community/groups/{groupId}/leave`
Invite by `userId`	`POST /community/groups/{groupId}/invite/{invitedUserId}`
Invite by email	`POST /community/groups/{groupId}/invite/email/{email}`
Remove by `userId` (kick)	`POST /community/groups/{groupId}/kick/{kickedUserId}`
Remove by email (kick)	`POST /community/groups/{groupId}/kick/email/{email}`
Add all users	`POST /community/groups/{groupId}/add/all`
Add by allowed badges	`POST /community/groups/{groupId}/add/by-allowed-badges`
Set a member’s expiration	`PUT /community/groups/{groupId}/members/{userId}/expiration`

Join and leave

join respects access control: if the group requires a badge the user doesn’t have, it returns 403.

curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../join \
  -H "Authorization: Bearer cativa_live_..."

curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../leave \
  -H "Authorization: Bearer cativa_live_..."

Invite and remove

Invite by email when you only have the email; use userId when you’ve already resolved the user.

curl -X POST \
  "https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../invite/email/mary@example.com" \
  -H "Authorization: Bearer cativa_live_..."

curl -X POST \
  "https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../invite/01HQ7..." \
  -H "Authorization: Bearer cativa_live_..."

curl -X POST \
  "https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../kick/01HQ7..." \
  -H "Authorization: Bearer cativa_live_..."

Bulk fill

To populate a group at once, without inviting one by one:

curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../add/all \
  -H "Authorization: Bearer cativa_live_..."

curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../add/by-allowed-badges \
  -H "Authorization: Bearer cativa_live_..."

add/by-allowed-badges adds every user who already holds one of the group’s allowedBadges. It’s how you “reconcile” the group after configuring badges.

Per-member expiration

Set a date when that member’s access automatically expires:

curl -X PUT \
  "https://apis.cativalab.digital/tenant/api/v2/community/groups/01HQ5.../members/01HQ7.../expiration" \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "expirationDate": "2026-12-31T23:59:59Z" }'

Create posts and comments

Posts live inside a Group. You need the groupId first: fetch it via the listing or store it at onboarding.

The post author is always the user associated with the authenticated credential. You do not (and cannot) send authorId in the body.

curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/posts \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "01HQ5ABCDEF1234567890XYZ",
    "content": "Welcome to the group!"
  }'

const res = await fetch('https://apis.cativalab.digital/tenant/api/v2/community/posts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CATIVA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    groupId: '01HQ5ABCDEF1234567890XYZ',
    content: 'Welcome to the group!'
  })
});
const post = await res.json();

The user tied to the credential must have access to the group (at least one matching badge, or membership in the open group). Without access, the call returns 403 forbidden. To comment, post to POST /community/posts/{postId}/comments:

curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/posts/01HQ8.../comments \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "content": "Loved this post!" }'

Same access rule: the user must be able to see the post.

Common errors

403 Forbidden on join or post

The user lacks a badge that unlocks the group. Assign the right badge first (see Badges as Permissions) or confirm the group is open.

404 Not Found on groupId

The group doesn’t exist in that tenant, or it’s secret and hidden from discovery. Confirm the groupId from the listing.

403 on group write routes

Creating/editing/deleting a group and bulk-adding require admin scope. Ask the tenant admin for the right credential.

Anti-pattern: one group per customer via API

Don’t model “one group per customer”. Groups are static entities defined by the admin: they represent discussion communities, not ephemeral containers. To customize access per customer, use badges: create a single “VIP Members” group and assign the Premium badge to the right customers.

Get Started

Concepts

Guides

Webhooks

Changelog

The hierarchy

Who creates what

Access control: badge gates the group

Read endpoints

List groups

Group detail

List members

Group CRUD (admin scope)

Create a group

Members: join, leave, invite, and remove

Join and leave

Invite and remove

Bulk fill

Per-member expiration

Create posts and comments

Common errors

Anti-pattern: one group per customer via API

Next steps

Badges as Permissions

Webhooks

​The hierarchy

​Who creates what

​Access control: badge gates the group

​Read endpoints

​List groups

​Group detail

​List members

​Group CRUD (admin scope)

​Create a group

​Members: join, leave, invite, and remove

​Join and leave

​Invite and remove

​Bulk fill

​Per-member expiration

​Create posts and comments

​Common errors

​Anti-pattern: one group per customer via API

​Next steps

Badges as Permissions

Webhooks

The hierarchy

Who creates what

Access control: badge gates the group

Read endpoints

List groups

Group detail

List members

Group CRUD (admin scope)

Create a group

Members: join, leave, invite, and remove

Join and leave

Invite and remove

Bulk fill

Per-member expiration

Create posts and comments

Common errors

Anti-pattern: one group per customer via API

Next steps