Skip to main content
Version: v0.2 (Next)

API Endpoints Reference

A complete reference of all core REST endpoints exposed by the ActonOS daemon (actond). Base URL: http://localhost:8080/api

1. System & Health​

GET /api/health​

Returns system status, active version, uptime, runtime mode, and resource load. No auth required.

Response:

{
  "status": "healthy",
  "version": "0.1.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​

Retrieve the canonical catalog of all supported LLM models, provider specs, badges, and pricing tiers. Single source of truth for the entire system.

Response:

{
  "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​

Validates the cryptographic SHA-256 hash chain of /data/logs/audit.jsonl to detect tampering.

GET /api/system/backup​

Streams a transactionally consistent SQLite database backup created using VACUUM INTO.

2. Authentication & Admin Identity​

GET /api/auth/status​

Returns initialization status and current session state.

POST /api/auth/setup​

Initialize system admin identity and set the master password during onboarding.

POST /api/auth/login​

Authenticate using the master password and obtain a Bearer JWT session token.

POST /api/auth/logout​

Revoke the current session token.

PUT /api/auth/password​

Update admin master password.

3. Agents Management​

GET /api/agents​

Lists all registered agent manifests.

POST /api/agents​

Creates a new agent definition.

Request Body:

{
  "id": "researcher",
  "name": "Research Agent",
  "description": "Performs deep web research and generates markdown reports",
  "system_prompt": "You are a professional research agent...",
  "primary_model": "anthropic:claude-3-7-sonnet",
  "fallback_model": "google:gemini-2.0-flash",
  "temperature": 0.2,
  "tools": ["native_web_search", "native_browser_headless", "native_workspace_write"],
  "allowed_paths": ["docs/*", "research/*"]
}

PUT /api/agents/{id}​

Updates an existing agent manifest.

DELETE /api/agents/{id}​

Removes an agent from the registry.

4. Chat & Execution Streams​

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

Synchronously sends a message to an agent.

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

Initiates a Server-Sent Events (SSE) stream for real-time token streaming and live tool execution cards.

5. Approvals Ledger​

GET /api/approvals?status=pending​

Lists pending mutation approval requests (pending, approved, rejected, all).

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

Approves the exact action recorded in the approval entry and resumes the agent run.

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

Safely rejects the pending mutation without executing the action.

6. Plugins Subsystem (WASMLoader)​

GET /api/plugins​

Lists all installed WASM plugins with manifests, capabilities (tool, channel, connector), permissions, and runtime statuses.

Response:

{
  "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​

Upload an .actonpkg bundle or .wasm binary via multipart/form-data (file). Validates the manifest and hot-loads into the Wazero runtime sandbox.

GET /api/plugins/{id}​

Returns complete manifest details and configuration schema for a specific plugin.

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

Updates dynamic configuration values and persists declared secrets into Hardware Vault. Automatically triggers hot-reloading of the plugin instance.

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

Enables or disables an installed plugin at runtime without restarting actond.

DELETE /api/plugins/{id}​

Uninstalls the plugin and purges its directory from /data/plugins/{id}.

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

Fetches execution and telemetry logs emitted by the sandboxed WASM plugin.

7. Channel Accounts & Device Pairing​

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

Fetch or configure multi-account chat channel credentials and agent binding rules.

GET /api/integrations/channels/accounts​

List all active channel accounts with live connectivity health badges.

POST /api/integrations/pairing/code​

Generates a 6-digit numeric pairing code for channel operator verification.

POST /api/integrations/pairing/verify​

Validates pairing code from an incoming chat message to authorize a user ID.

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

List or revoke authorized external chat senders.

8. Hardware Vault Secrets​

GET /api/vault/secrets​

Lists metadata for all encrypted secrets currently stored in the Hardware Vault.

POST /api/vault/secrets​

Stores an encrypted secret value bound to hardware UUID and CPU serial.

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

Deletes a secret record from the Vault.

9. Tools & Marketplace Hub​

GET /api/tools​

Lists all active tools across Native, MCP, WASM Plugins, and Skill-as-a-Folder categories.

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

Register or disconnect an MCP server (stdio or sse). High-risk operations return a 202 Accepted pending approval request.

GET /api/tools/hub/catalog​

Fetches the live Community Tool Hub catalog.

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

Installs or uninstalls a verified community skill package.

10. Workspace File Management​

GET /api/workspace/files?dir=docs​

Lists files and directories under the specified relative workspace path with semantic vector status.

GET /api/workspace/file?path=docs/notes.md​

Returns the content and metadata of a specific text file.

GET /api/workspace/raw?path=docs/diagram.png​

Streams raw binary bytes (with HTTP Range support) for media and image previews.

POST /api/workspace/file​

Creates or updates a file and enqueues it for semantic vector indexing.

DELETE /api/workspace/file?path=reports/old.md​

Deletes a file or directory from the workspace.

11. Notifications Center​

GET /api/notifications​

Returns paginated system and mission notifications (page, limit, type, unread_only).

POST /api/notifications/mark-read​

Marks notifications as read ({ "id": "notif_..." } or { "all": true }).

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

Returns the server's VAPID public key for browser push subscriptions.

POST /api/notifications/push/subscribe​

Registers a browser Service Worker push subscription for OS-level alerts.