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.cityAuthentication
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 /whoamiResponse (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.txtResponse
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=/DocumentsResponse
[
{
"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.txtResponse
{
"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/modelsResponse
{
"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/versionResponse
{
"version": "1.0.0",
"commit": "abc123",
"buildDate": "2024-01-15T10:00:00Z"
}Check Status
GET /api/update/statusResponse
{
"currentVersion": "1.0.0",
"latestVersion": "1.1.0",
"updateAvailable": true,
"releaseNotes": "Bug fixes and performance improvements"
}Trigger Check
POST /api/update/checkResponse
{
"updateAvailable": true,
"latestVersion": "1.1.0"
}Install Update
POST /api/update/installResponse
{
"success": true,
"message": "Update started"
}Get Progress
GET /api/update/progressResponse
{
"isUpdating": true,
"progress": "Installing dependencies..."
}Backup Endpoints
Create Backup
POST /api/backup/createResponse
{
"success": true,
"filename": "backup-2024-01-15-103000.tar.gz",
"size": 15728640
}List Backups
GET /api/backup/listResponse
{
"backups": [
{
"filename": "backup-2024-01-15-103000.tar.gz",
"size": 15728640,
"created": "2024-01-15T10:30:00Z"
}
]
}Download Backup
GET /api/backup/download/:filenameResponse: Binary file download
System Endpoints
Health Check
GET /healthResponse
{
"status": "ok",
"database": "connected",
"ipfs": "available",
"uptime": 86400
}Boson Status
GET /api/boson/statusResponse
{
"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
| Code | HTTP Status | Description |
|---|---|---|
UNAUTHORIZED | 401 | Not authenticated |
FORBIDDEN | 403 | Access denied |
NOT_FOUND | 404 | Resource not found |
VALIDATION_ERROR | 400 | Invalid input |
INTERNAL_ERROR | 500 | Server error |
→ See Configuration for node settings