REST API

REST API Reference

Cloudillo provides a comprehensive REST API for building applications. All endpoints return JSON and use standard HTTP methods.

Base URL

https://your-cloudillo-server.com

For local development:

http://localhost:3000

Authentication

Most endpoints require authentication via JWT tokens in the Authorization header:

Authorization: Bearer eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9...

See Authentication for details on obtaining and managing tokens.

Response Format

All successful responses follow this format:

{
  "data": <payload>,
  "time": "2025-01-01T12:00:00Z",
  "reqId": "req_abc123"
}

For list endpoints, cursor-based pagination is recommended:

{
  "data": [...],
  "cursorPagination": {
    "nextCursor": "eyJzIjoiY3JlYXRlZCIsInYiOjE3MzUwMDAwMDAsImlkIjoiYTF-YWJjMTIzIn0",
    "hasMore": true
  },
  "time": "2025-01-01T12:00:00Z"
}

Legacy offset-based pagination (deprecated):

{
  "data": [...],
  "pagination": {
    "total": 150,
    "offset": 0,
    "limit": 20
  },
  "time": "2025-01-01T12:00:00Z"
}

Error Format

Errors return this structure:

{
  "error": {
    "code": "E-AUTH-UNAUTH",
    "message": "Unauthorized access",
    "details": {...}
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

See Error Handling for all error codes.

Common Query Parameters

Many list endpoints support these parameters:

  • limit - Maximum number of results (default: 20)
  • cursor - Opaque cursor for pagination (from previous response)
  • sort - Sort field (e.g., created, modified, name)
  • sortDir - Sort direction (asc or desc)

Endpoint Categories

Authentication

User authentication and token management.

  • POST /api/auth/login - Login and get token
  • POST /api/auth/login-init - Combined login init (token + QR + WebAuthn)
  • POST /api/auth/logout - Logout
  • POST /api/auth/password - Change password
  • GET /api/auth/login-token - Refresh token
  • GET /api/auth/access-token - Get scoped token
  • GET /api/auth/proxy-token - Get federation token
  • POST /api/auth/qr-login/init - QR login init
  • GET /api/auth/qr-login/{session_id}/status - QR login status
  • GET /api/me - Get tenant profile (public)
  • GET /.well-known/cloudillo/id-tag - Resolve identity

Profiles

User and community profiles.

  • POST /api/profiles/register - Register new user
  • POST /api/profiles/verify - Verify identity availability
  • GET /api/me - Get own profile
  • PATCH /api/me - Update own profile
  • PUT /api/me/image - Upload profile image
  • PUT /api/me/cover - Upload cover image
  • GET /api/profiles - List profiles
  • GET /api/profiles/:idTag - Get specific profile
  • PATCH /api/profiles/:idTag - Update relationship
  • PATCH /api/admin/profiles/:idTag - Admin update profile

Actions

Social features: posts, comments, reactions, connections.

  • GET /api/actions - List actions
  • POST /api/actions - Create action
  • GET /api/actions/{actionId} - Get action
  • PATCH /api/actions/{actionId} - Update draft action
  • DELETE /api/actions/{actionId} - Delete action
  • POST /api/actions/{actionId}/accept - Accept action
  • POST /api/actions/{actionId}/reject - Reject action
  • POST /api/actions/{actionId}/dismiss - Dismiss notification
  • POST /api/actions/{actionId}/publish - Publish draft
  • POST /api/actions/{actionId}/cancel - Cancel scheduled
  • POST /api/actions/{actionId}/stat - Update statistics
  • POST /api/actions/{actionId}/reaction - Add reaction
  • POST /api/inbox - Federation inbox (async)
  • POST /api/inbox/sync - Federation inbox (sync)

Files

File upload, download, and management.

  • GET /api/files - List files
  • POST /api/files - Create file metadata (CRDT/RTDB)
  • POST /api/files/{preset}/{file_name} - Upload file (BLOB)
  • GET /api/files/{fileId} - Download file
  • GET /api/files/{fileId}/descriptor - Get file info
  • GET /api/files/{fileId}/metadata - Get file metadata
  • PATCH /api/files/{fileId} - Update file
  • DELETE /api/files/{fileId} - Delete file
  • POST /api/files/{fileId}/duplicate - Duplicate CRDT/RTDB file
  • POST /api/files/{fileId}/restore - Restore from trash
  • PUT /api/files/{fileId}/tag/{tag} - Add tag
  • DELETE /api/files/{fileId}/tag/{tag} - Remove tag
  • GET /api/files/variant/{variantId} - Get variant

Apps

App package management.

  • GET /api/apps - List available apps
  • POST /api/apps/install - Install app
  • GET /api/apps/installed - List installed apps
  • DELETE /api/apps/@{publisher}/{name} - Uninstall app

Shares

File sharing and access grants.

  • GET /api/shares - List shares by subject
  • GET /api/files/{fileId}/shares - List file shares
  • POST /api/files/{fileId}/shares - Create share
  • DELETE /api/files/{fileId}/shares/{shareId} - Delete share

Settings

User preferences and configuration.

  • GET /api/settings - List all settings
  • GET /api/settings/:name - Get setting
  • PUT /api/settings/:name - Update setting

References

Bookmarks and shortcuts.

  • GET /api/refs - List references
  • POST /api/refs - Create reference
  • GET /api/refs/:refId - Get reference
  • DELETE /api/refs/:refId - Delete reference

Tags

File and content tagging.

  • GET /api/tags - List tags
  • PUT /api/files/:fileId/tag/:tag - Add tag
  • DELETE /api/files/:fileId/tag/:tag - Remove tag

Trash

Trash management.

  • GET /api/files?parentId=__trash__ - List trashed files
  • POST /api/files/:fileId/restore - Restore from trash
  • DELETE /api/files/:fileId?permanent=true - Permanently delete
  • DELETE /api/trash - Empty trash

Communities

Community creation and management.

  • PUT /api/profiles/:idTag - Create community
  • POST /api/profiles/verify - Verify availability

Admin

System administration (requires admin role).

  • GET /api/admin/tenants - List tenants
  • POST /api/admin/tenants/{idTag}/password-reset - Send password reset
  • POST /api/admin/email/test - Test SMTP
  • PATCH /api/admin/profiles/{idTag} - Admin profile update
  • GET /api/admin/proxy-sites - List proxy sites
  • POST /api/admin/proxy-sites - Create proxy site
  • PATCH /api/admin/proxy-sites/{siteId} - Update proxy site
  • DELETE /api/admin/proxy-sites/{siteId} - Delete proxy site
  • POST /api/admin/proxy-sites/{siteId}/renew-cert - Renew certificate
  • POST /api/admin/invite-community - Invite community

IDP Management

Identity provider administration.

  • GET /api/idp/identities - List managed identities
  • POST /api/idp/identities - Create identity
  • GET /api/idp/identities/:idTag - Get identity
  • PATCH /api/idp/identities/:idTag - Update identity
  • PUT /api/idp/identities/:idTag/address - Update identity address (DNS)
  • DELETE /api/idp/identities/:idTag - Delete identity
  • GET /api/idp/api-keys - List API keys
  • POST /api/idp/api-keys - Create API key
  • DELETE /api/idp/api-keys/:keyId - Delete API key

Rate Limiting

API requests are rate-limited per tenant:

  • Default: 1000 requests per minute
  • Authenticated: 5000 requests per minute
  • Admin: Unlimited

Rate limit headers:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4950
X-RateLimit-Reset: 1735000000

CORS

CORS is enabled for all origins in development mode. In production, configure allowed origins in the server settings.

Timestamps

All response timestamps are in ISO 8601 format:

{
  "createdAt": "2025-01-01T12:00:00Z"
}

Query parameter timestamps accept both ISO 8601 strings and Unix seconds:

GET /api/actions?createdAfter=2025-01-01T00:00:00Z
GET /api/actions?createdAfter=1735689600

Content Types

Request Content-Type

Most endpoints accept:

Content-Type: application/json

File uploads use:

Content-Type: multipart/form-data

Response Content-Type

All responses return:

Content-Type: application/json; charset=utf-8

Except file downloads which return the appropriate MIME type.

HTTP Methods

  • GET - Retrieve resources
  • POST - Create resources
  • PATCH - Partially update resources
  • PUT - Replace resources
  • DELETE - Delete resources

Idempotency

PUT, PATCH, and DELETE operations are idempotent. POST operations are not idempotent unless you provide an idempotencyKey:

{
  "idempotencyKey": "unique-key-123",
  "type": "POST",
  "content": {...}
}

Pagination

List endpoints use cursor-based pagination for stable results:

GET /api/actions?limit=20

Response includes pagination info:

{
  "data": [...],
  "cursorPagination": {
    "nextCursor": "eyJzIjoiY3JlYXRlZCIsInYiOjE3MzUwMDAwMDAsImlkIjoiYTF-YWJjMTIzIn0",
    "hasMore": true
  },
  "time": "2025-01-01T12:00:00Z"
}

To fetch the next page, use the cursor:

GET /api/actions?limit=20&cursor=eyJzIjoiY3JlYXRlZCIsInYiOjE3MzUwMDAwMDAsImlkIjoiYTF-YWJjMTIzIn0

Filtering

Many endpoints support filtering via query parameters. Each endpoint documents its available filters.

GET /api/actions?type=POST&status=A&createdAfter=2025-01-01T00:00:00Z

WebSocket Endpoints

For real-time features, use WebSocket connections:

  • WSS /ws/crdt/{doc_id} - Collaborative documents
  • WSS /ws/rtdb/{file_id} - Real-time database
  • WSS /ws/bus - Message bus

See WebSocket API for details.

Quick Start

Using @cloudillo/core

import * as cloudillo from '@cloudillo/core'

await cloudillo.init('my-app')
const api = cloudillo.createApiClient()

// Make requests
const profile = await api.profiles.getOwn()
const posts = await api.actions.list({ type: 'POST' })

Using fetch directly

const response = await fetch('/api/me', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
})

const data = await response.json()
console.log(data.data) // Profile object
console.log(data.time) // Timestamp
console.log(data.reqId) // Request ID

Cursor Pagination Details

Cursors are opaque base64-encoded strings containing:

  • Sort field (s)
  • Sort value (v)
  • Last item ID (id)
{
  "s": "created",
  "v": 1735000000,
  "id": "a1~abc123"
}

Benefits:

  • Stable: Results don’t shift when new items are added
  • Efficient: No offset scanning in database
  • Reliable: Works with large datasets

Use the SDK for easier pagination:

let cursor = undefined
while (true) {
  const result = await api.actions.list({ type: 'POST', limit: 20, cursor })
  // Process result.data
  if (!result.cursorPagination?.hasMore) break
  cursor = result.cursorPagination.nextCursor
}

Next Steps

Explore specific endpoint categories: