API Documentation

Cloudillo API Documentation

Welcome to the Cloudillo API documentation for application developers. This guide will help you build applications on top of the Cloudillo decentralized collaboration platform.

What is Cloudillo?

Cloudillo is an open-source, decentralized collaboration platform that enables users to maintain control over their data while seamlessly collaborating with others. Built on DNS-based identity and cryptographically signed action tokens, Cloudillo allows users to self-host, use community servers, or choose third-party providers without vendor lock-in.

For Application Developers

Cloudillo provides a comprehensive set of APIs and client libraries for building:

  • Collaborative applications with real-time synchronization
  • Social features using action tokens (posts, comments, reactions)
  • Rich content editors with CRDT-based conflict-free editing
  • File management with automatic image variants
  • Real-time databases with Firebase-like APIs
  • Microfrontend applications that integrate with the Cloudillo shell

API Overview

Client Libraries (TypeScript/JavaScript)

REST API

The Cloudillo server provides a comprehensive REST API for:

  • Authentication - Login, registration, token management
  • Profiles - User and community profiles
  • Actions - Social interactions (posts, comments, reactions)
  • Files - File upload, download, and management
  • Settings - User preferences and configuration
  • References - Bookmarks and shortcuts

WebSocket API

Real-time features are provided via WebSocket connections:

  • Message Bus - Pub/sub notifications and presence
  • RTDB - Real-time database synchronization
  • CRDT - Collaborative document editing

Getting Started

New to Cloudillo development? Start here:

  1. Getting Started Guide - Create your first Cloudillo app
  2. Authentication Guide - Understand token-based auth
  3. Microfrontend Integration - Build apps for the Cloudillo shell

Developer Guides

Comprehensive guides to help you build better Cloudillo applications:

Key Concepts

DNS-Based Identity

Every user in Cloudillo has an identity tag (idTag) based on a domain name (e.g., alice@example.com). This decouples identity from storage location, allowing users to migrate their data between providers while maintaining their identity.

Action Tokens

Actions are cryptographically signed events that represent user activities:

  • POST - Creating posts and content
  • CMNT - Adding comments
  • REACT - Reactions (e.g., LOVE)
  • FLLW - Following users
  • CONN - User connections
  • FSHR - File sharing

See Actions API for details.

Multi-Tenancy

Cloudillo is designed for multi-tenant deployments. Every request includes a tenant ID (tnId) that isolates data between tenants. Application developers typically don’t need to manage this directly - it’s handled by the client libraries.

Real-Time Collaboration

Cloudillo provides three levels of real-time collaboration:

  1. CRDT - Conflict-free collaborative editing using Yjs
  2. RTDB - Real-time database with structured queries
  3. Message Bus - Pub/sub for notifications and presence

Architecture

┌─────────────────────────────────────────┐
│         Your Application                │
│  (React, Vue, vanilla JS, etc.)         │
├─────────────────────────────────────────┤
│     Cloudillo Client Libraries          │
│  @cloudillo/base, @cloudillo/react      │
├─────────────────────────────────────────┤
│         REST + WebSocket APIs            │
├─────────────────────────────────────────┤
│       Cloudillo Server (Rust)            │
├─────────────────────────────────────────┤
│    Pluggable Storage Adapters            │
│  (Database, Blob, Auth, CRDT, etc.)     │
└─────────────────────────────────────────┘

Example: Your First App

import * as cloudillo from '@cloudillo/base'
import * as Y from 'yjs'

// Initialize your app
const token = await cloudillo.init('my-app')

// Access global state
console.log('User:', cloudillo.idTag)
console.log('Tenant:', cloudillo.tnId)
console.log('Roles:', cloudillo.roles)

// Create an API client
const api = cloudillo.createApiClient()

// Fetch the user's profile
const profile = await api.me.get()

// Open a collaborative document
const yDoc = new Y.Doc()
const { provider } = await cloudillo.openYDoc(yDoc, 'my-document-id')

// Use the CRDT
const yText = yDoc.getText('content')
yText.insert(0, 'Hello, Cloudillo!')

Client Libraries

REST API

Developer Guides

Advanced Topics

Support

License

Cloudillo is open source software licensed under the MIT License.