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": 1735000000,
  "reqId": "req_abc123"
}

For list endpoints, pagination metadata is included:

{
  "data": [...],
  "pagination": {
    "total": 150,
    "offset": 0,
    "limit": 20,
    "hasMore": true
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

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: 50, max: 200)
  • _offset - Skip N results (for pagination)
  • _sort - Sort field (e.g., createdAt)
  • _order - Sort order (asc or desc)

Endpoint Categories

Authentication

User authentication and token management.

  • POST /api/auth/register - Register new user
  • POST /api/auth/register-verify - Complete email verification
  • 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.

  • 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 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

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 (see Files API).

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

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 timestamps are in Unix seconds (not milliseconds):

{
  "createdAt": 1735000000
}

Convert in JavaScript:

const date = new Date(timestamp * 1000)

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 return paginated results:

GET /actions?_limit=20&_offset=40

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "total": 150,
    "offset": 40,
    "limit": 20,
    "hasMore": true
  }
}

Filtering

Many endpoints support filtering via query parameters:

GET /actions?type=POST&status=A&createdAfter=1735000000

Field Selection

Request specific fields only (reduces response size):

GET /actions?_fields=actionId,type,content,createdAt

Expansion

Expand related resources in a single request:

GET /actions?_expand=issuer,audience

This resolves references instead of returning just IDs.

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/base

import * as cloudillo from '@cloudillo/base'

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

// Make requests
const profile = await api.me.get()
const posts = await api.actions.get({ 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

Next Steps

Explore specific endpoint categories: