Profiles API

Overview

Manage user and community profiles, including registration and community creation.

Registration

Verify Profile

POST /api/profiles/verify

Verify identity availability before registration or community creation. This endpoint checks if an identity tag is available and can be used.

Authentication: Not required

Request:

{
  "idTag": "alice@example.com",
  "type": "idp"
}
Field Type Required Description
idTag string Yes The identity tag to verify
type string Yes Identity type: idp (hosted) or domain (self-hosted)
appDomain string No Application domain (for domain type)
token string No Verification token (for unauthenticated requests)

Response:

{
  "data": {
    "available": true,
    "idTag": "alice@example.com"
  },
  "time": "2025-01-01T12:00:00Z"
}

Example:

const result = await api.profile.verify({
  idTag: 'alice@example.com',
  type: 'idp'
})
if (result.data.available) {
  // Proceed with registration
}

Register User

POST /api/profiles/register

Register a new user account. This initiates the registration process and sends a verification email.

Authentication: Not required

Request:

{
  "type": "idp",
  "idTag": "alice@example.com",
  "email": "alice@gmail.com",
  "token": "verification-token",
  "lang": "en"
}
Field Type Required Description
type string Yes Identity type: idp or domain
idTag string Yes Desired identity tag
email string Yes Email address for verification
token string Yes Registration token
appDomain string No Application domain (for domain type)
lang string No Preferred language code

Response:

{
  "data": {
    "tnId": 12345,
    "idTag": "alice@example.com",
    "name": "Alice",
    "token": "eyJhbGc..."
  },
  "time": "2025-01-01T12:00:00Z"
}

Example:

const result = await api.profile.register({
  type: 'idp',
  idTag: 'alice@example.com',
  email: 'alice@gmail.com',
  token: 'registration-token'
})
// User is now registered and logged in
console.log('Registered:', result.data.idTag)

Create Community

PUT /api/profiles/{id_tag}

Create a new community profile. The authenticated user becomes the community owner.

Authentication: Required

Path Parameters:

  • id_tag - The identity tag for the new community

Request:

{
  "type": "idp",
  "name": "Developer Community",
  "profilePic": "b1~abc123",
  "appDomain": "devs.example.com"
}
Field Type Required Description
type string Yes Identity type: idp or domain
name string No Community display name
profilePic string No Profile picture file ID
appDomain string No Application domain (for domain type)

Response:

{
  "data": {
    "idTag": "devs@example.com",
    "name": "Developer Community",
    "type": "community",
    "createdAt": "2025-01-01T12:00:00Z"
  },
  "time": "2025-01-01T12:00:00Z"
}

Example:

// First verify the community name is available
const check = await api.profile.verify({
  idTag: 'devs@example.com',
  type: 'idp'
})

if (check.data.available) {
  const response = await fetch('/api/profiles/devs@example.com', {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'idp',
      name: 'Developer Community'
    })
  })
  const community = await response.json()
  console.log('Created community:', community.data.idTag)
}
Community Ownership

The authenticated user who creates the community becomes the owner. Only the owner can manage community settings and membership.

Profile Management

Get Own Profile

GET /api/me

Get the authenticated user’s profile (requires authentication). For the public server identity endpoint, see GET /api/me in the Authentication API.

Authentication: Required

Example:

const api = cloudillo.createApiClient()
const profile = await api.profiles.getOwn()

Response:

{
  "data": {
    "tnId": 12345,
    "idTag": "alice@example.com",
    "name": "Alice Johnson",
    "profilePic": "/file/b1~abc123",
    "x": {
      "bio": "Software developer",
      "location": "San Francisco"
    }
  }
}

Update Own Profile

PATCH /api/me

Update the authenticated user’s profile.

Authentication: Required

Request:

await api.profiles.updateOwn({
  name: 'Alice Smith',
  x: {
    bio: 'Senior developer',
    website: 'https://alice.example.com'
  }
})

Upload Profile Image

PUT /api/me/image

Upload or update your profile picture.

Authentication: Required

Content-Type: Image type (e.g., image/jpeg, image/png)

Request Body: Raw image binary data

Example:

const imageFile = document.querySelector('input[type="file"]').files[0]

const response = await fetch('/api/me/image', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': imageFile.type
  },
  body: imageFile
})

const result = await response.json()
console.log('Profile image updated:', result.data.profilePic)

Response:

{
  "data": {
    "profilePic": "/api/file/b1~abc123",
    "fileId": "b1~abc123"
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Upload Cover Image

PUT /api/me/cover

Upload or update your cover photo.

Authentication: Required

Content-Type: Image type (e.g., image/jpeg, image/png)

Request Body: Raw image binary data

Example:

const coverFile = document.querySelector('input[type="file"]').files[0]

const response = await fetch('/api/me/cover', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': coverFile.type
  },
  body: coverFile
})

const result = await response.json()
console.log('Cover image updated:', result.data.coverPic)

Response:

{
  "data": {
    "coverPic": "/api/file/b1~xyz789",
    "fileId": "b1~xyz789"
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Get Profile

GET /api/profiles/:idTag

Get a specific user or community profile.

Example:

const profile = await api.profiles.get('bob@example.com')

List Profiles

GET /api/profiles

List all accessible profiles.

Authentication: Required

Query Parameters:

  • type - Filter by type (person, community)
  • status - Filter by status (comma-separated)
  • connected - Filter by connection status (disconnected, pending, connected)
  • following - Filter by follow status (true/false)
  • q - Search query for name
  • idTag - Filter by specific identity tag

Example:

// List all communities
const communities = await api.profiles.list({
  type: 'community'
})

// List connected profiles
const friends = await api.profiles.list({
  connected: 'connected'
})

// Search for profiles
const results = await api.profiles.list({
  q: 'alice'
})

Update Relationship

PATCH /api/profiles/:idTag

Update your relationship with another profile (follow, block, etc.).

Authentication: Required

Request:

{
  "relationship": "follow"
}

Response:

{
  "data": {
    "idTag": "bob@example.com",
    "relationship": "follow",
    "updatedAt": 1735000000
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Admin: Update Profile

PATCH /api/admin/profiles/:idTag

Admin endpoint to update any user’s profile.

Authentication: Required (admin role)

Request:

{
  "name": "Updated Name",
  "status": "active",
  "roles": ["user", "moderator"]
}

Response:

{
  "data": {
    "tnId": 12345,
    "idTag": "bob@example.com",
    "name": "Updated Name",
    "status": "active",
    "roles": ["user", "moderator"]
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

See Also