Communities API

The Communities API enables creation and management of community profiles.

Concepts

Communities are special profile types that can have multiple members with different roles. They provide:

Shared content feeds
Member management with role hierarchy
Community-specific settings

Community Roles

Roles form a hierarchy from least to most privileged:

Role	Level	Description
`public`	0	Anyone (non-member)
`follower`	1	Following the community
`supporter`	2	Supporter/subscriber
`contributor`	3	Can create content
`moderator`	4	Can moderate content
`leader`	5	Full administrative access

Endpoints

Create Community

PUT /api/profiles/{idTag}

Create a new community profile.

Path Parameters:

idTag - Identity tag for the new community (e.g., mygroup.cloudillo.net)

Request Body:

{
  "type": "community",
  "name": "My Community",
  "bio": "A community for enthusiasts",
  "ownerIdTag": "alice.cloudillo.net"
}

Response:

{
  "data": {
    "idTag": "mygroup.cloudillo.net",
    "name": "My Community",
    "type": "community",
    "bio": "A community for enthusiasts",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "time": 1705315800,
  "req_id": "req_xyz"
}

Example:

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"community","name":"My Community","ownerIdTag":"alice.cloudillo.net"}' \
  "https://cl-o.alice.cloudillo.net/api/profiles/mygroup.cloudillo.net"

Verify Community Availability

POST /api/profiles/verify

Check if a community identity is available.

Request Body:

{
  "type": "community",
  "idTag": "mygroup.cloudillo.net"
}

Response:

{
  "data": {
    "available": true,
    "errors": [],
    "serverAddresses": ["192.168.1.100"]
  },
  "time": 1705315800,
  "req_id": "req_xyz"
}

If not available:

{
  "data": {
    "available": false,
    "errors": ["E-PROFILE-EXISTS"],
    "serverAddresses": []
  }
}

Client SDK Usage

import { createApiClient } from '@cloudillo/core'

const api = createApiClient({ idTag: 'alice.cloudillo.net', authToken: token })

// Verify community name is available
const verification = await api.profile.verify({
  type: 'community',
  idTag: 'mygroup.cloudillo.net'
})

if (verification.available) {
  // Create the community
  const community = await api.communities.create('mygroup.cloudillo.net', {
    type: 'community',
    name: 'My Community',
    ownerIdTag: 'alice.cloudillo.net'
  })
}

Member Management

Member roles are managed through the Profiles API.

Update Member Role

// As community leader/moderator
await api.profiles.adminUpdate('member.cloudillo.net', {
  roles: ['contributor']
})

List Community Members

const members = await api.profiles.list({
  community: 'mygroup.cloudillo.net',
  role: 'contributor'
})

Role-Based Permissions

Use the ROLE_LEVELS constant from @cloudillo/types for permission checks:

import { ROLE_LEVELS, CommunityRole } from '@cloudillo/types'

function hasPermission(userRole: CommunityRole, requiredRole: CommunityRole): boolean {
  return ROLE_LEVELS[userRole] >= ROLE_LEVELS[requiredRole]
}

// Check if user can moderate
if (hasPermission(userRole, 'moderator')) {
  // Allow moderation actions
}