PC2 API Reference
All endpoints are served from the PC2 node's HTTP server (default http://localhost:4200). Authenticated endpoints require a valid session cookie obtained through the authentication flow.
Authentication
Get Current User
Returns the currently authenticated user's information.
GET /whoami
Response (authenticated):
{
"is_logged_in": true,
"user": {
"address": "0x1234...abcd",
"role": "owner",
"username": "alice"
}
}
Response (not authenticated):
{
"is_logged_in": false
}
Authenticate via Particle
Authenticates a user using a Particle Network session.
POST /auth/particle
Request body:
{
"token": "<particle-auth-token>",
"address": "0x1234...abcd"
}
Response:
{
"success": true,
"user": {
"address": "0x1234...abcd",
"role": "owner"
}
}
Sets an HTTP-only session cookie on success.
File Operations
All file paths are relative to the authenticated user's storage root. Paths are automatically scoped to the user's wallet address.
Read File
GET /read?path=<file-path>
Query parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | Path to the file relative to user root |
Response: File contents with appropriate Content-Type header.
Write File
POST /write
Request body: multipart/form-data
| Field | Type | Required | Description |
|---|---|---|---|
path | string | Yes | Destination path relative to user root |
file | file | Yes | File contents |
Response:
{
"success": true,
"path": "/documents/report.pdf",
"cid": "bafybeig..."
}
Read Directory
GET /readdir?path=<directory-path>
Query parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | Path to the directory relative to user root |
Response:
[
{
"name": "report.pdf",
"type": "file",
"size": 102400,
"modified": "2025-01-15T10:30:00Z"
},
{
"name": "images",
"type": "directory",
"modified": "2025-01-14T08:00:00Z"
}
]
Get File/Directory Info
GET /stat?path=<path>
Query parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | Path to the file or directory |
Response:
{
"name": "report.pdf",
"type": "file",
"size": 102400,
"modified": "2025-01-15T10:30:00Z",
"created": "2025-01-10T09:00:00Z",
"cid": "bafybeig..."
}
Create Directory
POST /mkdir
Request body:
{
"path": "/documents/projects"
}
Response:
{
"success": true,
"path": "/documents/projects"
}
Delete File or Directory
POST /delete
Request body:
{
"path": "/documents/old-report.pdf"
}
Response:
{
"success": true
}
Move/Rename File or Directory
POST /move
Request body:
{
"source": "/documents/draft.pdf",
"destination": "/documents/final.pdf"
}
Response:
{
"success": true,
"path": "/documents/final.pdf"
}
WASM Execution
Execute WASM File
Execute a WASM binary that has been uploaded to the user's storage.
POST /api/wasm/execute-file
Request body:
{
"path": "/wasm/calculator.wasm",
"args": ["add", "2", "3"],
"env": {}
}
Response:
{
"success": true,
"stdout": "5\n",
"stderr": "",
"exitCode": 0
}
Execute Inline WASM
Execute a WASM binary provided directly in the request.
POST /api/wasm/execute
Request body: multipart/form-data
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes | The WASM binary |
args | string | No | JSON-encoded array of arguments |
Response:
{
"success": true,
"stdout": "Hello from WASM\n",
"stderr": "",
"exitCode": 0
}
AI
Chat
Send a message to an AI model and receive a streamed response.
POST /api/ai/chat
Request body:
{
"model": "llama3",
"provider": "ollama",
"messages": [
{
"role": "user",
"content": "Explain quantum computing in simple terms."
}
],
"stream": true
}
Response (stream: true): Server-Sent Events (SSE) stream.
data: {"content": "Quantum", "done": false}
data: {"content": " computing", "done": false}
data: {"content": " uses...", "done": false}
data: {"content": "", "done": true}
Response (stream: false):
{
"content": "Quantum computing uses quantum mechanical phenomena...",
"model": "llama3",
"provider": "ollama"
}
List Available Models
GET /api/ai/models
Response:
{
"models": [
{
"name": "llama3",
"provider": "ollama",
"type": "local"
},
{
"name": "gpt-4",
"provider": "openai",
"type": "cloud"
}
]
}
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
}
No authentication required.
Boson Status
GET /api/boson/status
Response:
{
"nodeId": "2abc...",
"did": "did:boson:2abc...",
"connected": true,
"proxyEnabled": true,
"allocatedPort": 25001
}
Access Control
GET /api/access/status
GET /api/access/wallets
POST /api/access/wallets
DELETE /api/access/wallets/:id
See Access Control for details.
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 |