ElastOS v1 (PC2)ReferenceAPI Reference

API Reference

This page documents ElastOS v1 (PC2), the proof of concept. ElastOS v2 is the current system. To install it, see Install ElastOS. To see how the stages fit together, see ElastOS in stages.

Complete REST API documentation for PC2 nodes.

Base URL

http://localhost:4200
https://yourname.ela.city

Authentication

Most endpoints require authentication via session token.

Headers

Authorization: Bearer <session_token>
Cookie: session=<session_token>

Session tokens are obtained after wallet authentication.


Auth Endpoints

Get Current User

GET /whoami

Response (Authenticated)

{
  "user": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "username": "alice",
    "wallet": "0x1234567890abcdef...",
    "authenticated": true
  }
}

Response (Not Authenticated)

{
  "user": {
    "authenticated": false
  }
}

Particle Auth Callback

POST /auth/particle
Content-Type: application/json
 
{
  "uuid": "particle-user-id",
  "address": "0x1234567890abcdef...",
  "token": "particle-jwt-token"
}

Response

{
  "success": true,
  "user": { ... },
  "sessionToken": "abc123..."
}

File Endpoints

Read File

GET /read?path=/Documents/hello.txt

Response

Hello, World!

Write File

POST /write
Content-Type: multipart/form-data
 
path: /Documents/hello.txt
file: <file data>

Response

{
  "success": true,
  "path": "/Documents/hello.txt"
}

List Directory

GET /readdir?path=/Documents

Response

[
  {
    "name": "hello.txt",
    "type": "file",
    "size": 13,
    "modified": "2024-01-15T10:30:00Z"
  },
  {
    "name": "subfolder",
    "type": "directory",
    "modified": "2024-01-14T08:00:00Z"
  }
]

File Metadata

GET /stat?path=/Documents/hello.txt

Response

{
  "name": "hello.txt",
  "path": "/Documents/hello.txt",
  "type": "file",
  "size": 13,
  "modified": "2024-01-15T10:30:00Z",
  "created": "2024-01-15T10:30:00Z"
}

Create Directory

POST /mkdir
Content-Type: application/json
 
{
  "path": "/Documents/newfolder"
}

Response

{
  "success": true,
  "path": "/Documents/newfolder"
}

Delete File/Folder

POST /delete
Content-Type: application/json
 
{
  "path": "/Documents/hello.txt"
}

Response

{
  "success": true
}

Move/Rename

POST /move
Content-Type: application/json
 
{
  "source": "/Documents/hello.txt",
  "destination": "/Documents/renamed.txt"
}

Response

{
  "success": true,
  "path": "/Documents/renamed.txt"
}

WASM Endpoints

Execute WASM File

POST /api/wasm/execute-file
Content-Type: application/json
 
{
  "filepath": "/apps/calculator.wasm",
  "function": "add",
  "args": [5, 3]
}

Response

{
  "success": true,
  "result": 8
}

Execute WASM Bytes

POST /api/wasm/execute
Content-Type: application/json
 
{
  "wasmBytes": "<base64-encoded-wasm>",
  "function": "calculate",
  "args": [10, 20]
}

AI Endpoints

Chat (Streaming)

POST /api/ai/chat
Content-Type: application/json
 
{
  "provider": "openai",
  "model": "gpt-4o",
  "messages": [
    {"role": "user", "content": "Hello!"}
  ],
  "stream": true
}

Response (Server-Sent Events)

data: {"chunk": "Hello"}
data: {"chunk": "! How"}
data: {"chunk": " can I help?"}
data: [DONE]

List Models

GET /api/ai/models

Response

{
  "providers": {
    "ollama": ["deepseek-r1:7b", "llama3"],
    "openai": ["gpt-4o", "gpt-4o-mini"],
    "anthropic": ["claude-3-opus", "claude-3-sonnet"]
  }
}

Update Endpoints

Get Version

GET /api/update/version

Response

{
  "version": "1.0.0",
  "commit": "abc123",
  "buildDate": "2024-01-15T10:00:00Z"
}

Check Status

GET /api/update/status

Response

{
  "currentVersion": "1.0.0",
  "latestVersion": "1.1.0",
  "updateAvailable": true,
  "releaseNotes": "Bug fixes and performance improvements"
}

Trigger Check

POST /api/update/check

Response

{
  "updateAvailable": true,
  "latestVersion": "1.1.0"
}

Install Update

POST /api/update/install

Response

{
  "success": true,
  "message": "Update started"
}

Get Progress

GET /api/update/progress

Response

{
  "isUpdating": true,
  "progress": "Installing dependencies..."
}

Backup Endpoints

Create Backup

POST /api/backup/create

Response

{
  "success": true,
  "filename": "backup-2024-01-15-103000.tar.gz",
  "size": 15728640
}

List Backups

GET /api/backup/list

Response

{
  "backups": [
    {
      "filename": "backup-2024-01-15-103000.tar.gz",
      "size": 15728640,
      "created": "2024-01-15T10:30:00Z"
    }
  ]
}

Download Backup

GET /api/backup/download/:filename

Response: Binary file download


System Endpoints

Health Check

GET /health

Response

{
  "status": "ok",
  "database": "connected",
  "ipfs": "available",
  "uptime": 86400
}

Boson Status

GET /api/boson/status

Response

{
  "nodeId": "2abc...",
  "did": "did:boson:2abc...",
  "connected": true,
  "proxyEnabled": true,
  "allocatedPort": 25001
}

Error Responses

All errors return:

{
  "error": true,
  "message": "Description of error",
  "code": "ERROR_CODE"
}

Common Error Codes

CodeHTTP StatusDescription
UNAUTHORIZED401Not authenticated
FORBIDDEN403Access denied
NOT_FOUND404Resource not found
VALIDATION_ERROR400Invalid input
INTERNAL_ERROR500Server error

→ See Configuration for node settings

© 2026 Elacity Labs. ELASTOS® is a registered trademark of Elastos DAO. ElastOS is open source under the MIT licence.