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/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
  • 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
  • DELETE /api/actions/:actionId - Delete action
  • POST /api/actions/:actionId/accept - Accept action
  • POST /api/actions/:actionId/reject - Reject action
  • 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
  • PATCH /api/files/:fileId - Update file
  • DELETE /api/files/:fileId - Delete file
  • PUT /api/files/:fileId/tag/:tag - Add tag
  • DELETE /api/files/:fileId/tag/:tag - Remove tag
  • GET /api/files/variant/:variantId - Get variant

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

Collections

Favorites, bookmarks, and pins.

  • GET /api/collections/:collType - List collection items
  • POST /api/collections/:collType/:itemId - Add to collection
  • DELETE /api/collections/:collType/:itemId - Remove from collection

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

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

Batch Operations

Some endpoints support batch operations:

POST /actions/batch
Content-Type: application/json

{
  "operations": [
    { "method": "POST", "data": {...} },
    { "method": "PATCH", "id": "act_123", "data": {...} }
  ]
}

WebSocket Endpoints

For real-time features, use WebSocket connections:

  • WSS /ws/crdt - Collaborative documents
  • WSS /ws/rtdb/:fileId - 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: