Chuyển tới nội dung chính
Phiên bản: v1

Tham chiếu API Endpoints

Tài liệu tham chiếu chi tiết các API REST do tiến trình nền ActonOS (actond) cung cấp. Base URL: http://localhost:8080/api

1. Hệ thống & Sức khỏe (Health & System)​

GET /api/health​

Trả về trạng thái sức khỏe, phiên bản, thời gian hoạt động (uptime), chế độ runtime và tài nguyên tải. Không yêu cầu xác thực.

Phản hồi:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime_seconds": 3600,
  "runtime_mode": "baremetal",
  "agents_active": 3,
  "memory_usage_mb": 42.5,
  "cpu_percent": 1.8,
  "disk_usage_percent": 12.4,
  "tailscale_connected": true
}

GET /api/models​

Lấy danh mục catalog chuẩn của tất cả các mô hình LLM được hỗ trợ, thông số nhà cung cấp, nhãn badge và hạn mức. Đây là nguồn dữ liệu chuẩn duy nhất của toàn hệ thống.

Phản hồi:

{
  "models": [
    {
      "id": "anthropic/claude-sonnet-4-6",
      "name": "Claude Sonnet 4.6",
      "provider_id": "anthropic",
      "provider_name": "Anthropic Claude",
      "context_window": 200000,
      "badge": "Recommended"
    }
  ]
}

GET /api/system/audit/verify​

Xác thực chuỗi băm mật mã SHA-256 của tệp /data/logs/audit.jsonl để phát hiện can thiệp dữ liệu trái phép.

GET /api/system/backup​

Tải bản sao lưu SQLite nhất quán theo giao dịch được tạo qua VACUUM INTO.

2. Xác thực & Danh tính Quản trị​

GET /api/auth/status​

Trả về trạng thái khởi tạo và phiên đăng nhập hiện tại.

POST /api/auth/setup​

Khởi tạo danh tính Quản trị viên và đặt mật khẩu chính trong quá trình thiết lập ban đầu.

POST /api/auth/login​

Xác thực bằng mật khẩu chính và nhận mã phiên Bearer JWT.

POST /api/auth/logout​

Thu hồi và hủy phiên đăng nhập hiện tại.

PUT /api/auth/password​

Thay đổi mật khẩu quản trị viên.

3. Quản trị Agents​

GET /api/agents​

Liệt kê tất cả các Agent đã đăng ký.

POST /api/agents​

Tạo mới một cấu hình Agent.

Body Yêu cầu:

{
  "agent_id": "researcher",
  "name": "Research Agent",
  "description": "Thực hiện nghiên cứu web chuyên sâu và viết báo cáo markdown",
  "system_instructions": "Bạn là chuyên gia nghiên cứu dữ liệu...",
  "model_config": {
    "primary_model": "anthropic/claude-sonnet-4-6",
    "fallback_model": "google/gemini-2.0-flash"
  },
  "authorized_tools": ["native_web_search", "native_browser_navigate", "native_workspace_write"],
  "delegation_scope": {
    "allowed_workspace_paths": ["*"]
  }
}

PUT /api/agents/{id}​

Cập nhật cấu hình của một Agent có sẵn.

DELETE /api/agents/{id}​

Xóa Agent khỏi hệ thống.

4. Trò chuyện & Luồng Thực thi (Chat Streams)​

POST /api/agents/{id}/chat​

Gửi tin nhắn đồng bộ đến một Agent.

POST /api/agents/{id}/chat/stream​

Khởi tạo luồng Server-Sent Events (SSE) để truyền dữ liệu sinh token theo thời gian thực và thẻ thực thi công cụ trực tiếp.

5. Sổ cái Phê duyệt (Approvals Ledger)​

GET /api/approvals?status=pending​

Liệt kê danh sách các yêu cầu đột biến chờ phê duyệt (pending, approved, rejected, all).

POST /api/approvals/{id}/approve​

Chấp thuận hành động chính xác và tiếp tục luồng thực thi của Agent.

POST /api/approvals/{id}/reject​

Từ chối hành động mà không thực thi lệnh đột biến.

6. Phân hệ Plugin (WASMLoader)​

GET /api/plugins​

Liệt kê tất cả các Plugin WASM đã cài đặt kèm manifest, khả năng (tool, channel, connector), phân quyền và trạng thái runtime.

Phản hồi:

{
  "plugins": [
    {
      "id": "channel-discord",
      "name": "Discord Bot Channel",
      "version": "2.0.0",
      "author": "ActonOS Core Team",
      "capabilities": ["channel"],
      "enabled": true,
      "status": "running",
      "permissions": {
        "net_outbound": ["discord.com", "gateway.discord.gg"],
        "secrets": ["discord_bot_tokens.*"],
        "storage": true
      }
    }
  ]
}

POST /api/plugins/upload​

Tải lên gói .actonpkg hoặc tệp nhị phân .wasm qua multipart/form-data (file). Xác thực manifest và hot-load vào môi trường sandbox Wazero.

POST /api/plugins/{id}/config​

Cập nhật giá trị cấu hình động và lưu trữ khóa bí mật vào Hardware Vault. Tự động kích hoạt cơ chế Hot-reload của plugin.

POST /api/plugins/{id}/enable | POST /api/plugins/{id}/disable​

Bật hoặc Tắt plugin tại thời điểm chạy mà không cần khởi động lại actond.

DELETE /api/plugins/{id}​

Gỡ cài đặt plugin và xóa thư mục lưu trữ khỏi /data/plugins/{id}.

GET /api/plugins/{id}/logs​

Lấy nhật ký thực thi và đo kiểm phát ra từ sandbox của plugin WASM.

7. Tài khoản Kênh & Ghép đôi Thiết bị (Pairing)​

GET /api/integrations/channels | POST /api/integrations/channels​

Lấy hoặc cấu hình thông tin xác thực kênh chat đa tài khoản và quy tắc định tuyến Agent.

GET /api/integrations/channels/accounts​

Liệt kê tất cả tài khoản kênh đang hoạt động kèm huy hiệu trạng thái kết nối trực tiếp.

POST /api/integrations/pairing/code​

Tạo mã ghép đôi 6 chữ số để xác thực người vận hành kênh chat.

POST /api/integrations/pairing/verify​

Xác thực mã PIN ghép đôi từ tin nhắn đến để cấp quyền điều hành cho User ID.

GET /api/integrations/authorizations | DELETE /api/integrations/authorizations​

Xem danh sách hoặc thu hồi quyền của các người gửi chat bên ngoài.

8. Khóa bí mật Hardware Vault​

GET /api/vault/secrets​

Liệt kê siêu dữ liệu của toàn bộ khóa bí mật được mã hóa trong Hardware Vault.

POST /api/vault/secrets​

Lưu trữ khóa bí mật được mã hóa gắn liền với UUID và CPU serial phần cứng.

DELETE /api/vault/secrets/{name}​

Xóa một bản ghi khóa bí mật khỏi Vault.

9. Công cụ, MCP và catalog Skills​

GET /api/tools​

Liệt kê công cụ đã đăng ký (native, MCP, plugin WASM, skill thư mục). Trang Native Tools ẩn nhóm skill; những skill đó hiện trên Skills.

POST /api/tools/mcp | DELETE /api/tools/mcp/{serverID}​

Đăng ký hoặc ngắt kết nối máy chủ MCP (stdio, Streamable HTTP, hoặc sse). Thao tác rủi ro cao trả về 202 Accepted chờ duyệt.

GET /api/tools/hub/catalog​

Lấy catalog skill cộng đồng hiện trên Extensions → Skills → Community Hub.

POST /api/tools/hub/install | POST /api/tools/hub/uninstall​

Cài hoặc gỡ một gói skill cộng đồng.

10. Quản lý Tệp Workspace​

Trang Workspace hiện tên gốc (report.pdf). API định danh tệp bằng id / parent_id. path và dir vẫn được nhận như lối tương thích cũ.

GET /api/workspace/files?parent_id=​

Liệt kê con của một thư mục. Bỏ parent_id để lấy gốc. Mỗi mục có name, virtual_path và trạng thái lập chỉ mục.

GET /api/workspace/file?id=​

Trả về siêu dữ liệu. Tệp chữ kèm content UTF-8; tệp nhị phân kèm raw_url (không nhét base64).

GET /api/workspace/raw?id=​

Truyền nguyên byte tệp (hỗ trợ HTTP Range) cho PDF, ảnh, audio, video.

POST /api/workspace/file​

Tạo hoặc cập nhật (parent_id, name, cộng content hoặc content_base64) và đưa vào hàng đợi lập chỉ mục.

DELETE /api/workspace/file?id=​

Xóa tệp hoặc thư mục.

POST /api/workspace/mkdir | POST /api/workspace/upload | POST /api/workspace/rename | POST /api/workspace/duplicate​

Tạo thư mục, tải lên multipart, đổi tên/di chuyển, nhân bản.

GET /api/workspace/stats | GET /api/workspace/zip?id= | POST /api/workspace/reindex | GET /api/workspace/chunks?id=​

Thống kê dung lượng, tải zip, lập chỉ mục lại, và các đoạn ngữ nghĩa của một tệp.

11. Trung tâm Thông báo (Notifications)​

GET /api/notifications​

Lấy danh sách thông báo hệ thống và nhiệm vụ có phân trang.

POST /api/notifications/mark-read​

Đánh dấu thông báo đã đọc ({ "id": "notif_..." } hoặc { "all": true }).

GET /api/notifications/push/vapid-key​

Lấy khóa công khai VAPID cho thông báo đẩy trình duyệt.

POST /api/notifications/push/subscribe​

Đăng ký Service Worker nhận thông báo đẩy cấp hệ điều hành.