Admin API

The Admin API provides programmatic control over plugins, memory, scheduler, and configuration. It uses JSON-RPC over the existing authenticated WebSocket channel between the mobile app and the Secrets Agent.

Transport

Protocol — JSON-RPC over WebSocket (same channel used for secret approvals)
Authentication — requires an established, Ed25519-authenticated session
Security — destructive operations (delete memory, update config) require biometric confirmation on the mobile device

Envelope Format

Request

Admin Request Envelope json

{
  "type": "admin",
  "request_id": "a1b2c3d4",
  "payload": {
    "action": "list_plugins"
  }
}

Response

Admin Response Envelope json

{
  "type": "admin_response",
  "request_id": "a1b2c3d4",
  "payload": {
    "result": "plugins",
    "plugins": [...]
  }
}

The request_id field correlates responses with their originating request, enabling concurrent requests over a single WebSocket connection.

Request Types

Dashboard

Action	Parameters	Description
`get_dashboard`	None	System overview with counts and recent activity

Returns: connected, memory_count, plugin_count, skill_count, scheduled_task_count, recent_executions.

Plugins

Action	Parameters	Description
`list_plugins`	None	List all installed plugins with type, version, capabilities, enabled state
`toggle_plugin`	`name` (string), `enabled` (bool)	Enable or disable a plugin
`list_skills`	None	List all available skills

Memory

Action	Parameters	Description
`list_memories`	`page` (u32), `per_page` (u32)	Paginated list of memory entries
`search_memories`	`query` (string), `limit` (usize)	Semantic search over memory entries
`delete_memory`	`id` (string)	Delete a memory entry (requires biometric)

Scheduler

Action	Parameters	Description
`list_scheduled_tasks`	None	List all scheduled tasks with cron, next run, enabled state
`toggle_task`	`name` (string), `enabled` (bool)	Enable or disable a scheduled task
`trigger_task`	`name` (string)	Execute a task immediately, regardless of schedule
`list_task_executions`	`task_name` (string), `limit` (usize)	Get execution history for a specific task

Configuration

Action	Parameters	Description
`get_config`	None	Get sanitized system configuration
`update_config`	`section` (string), `value` (JSON)	Update a config section (requires biometric)

Response Types

All responses include a result discriminator field:

Result	Fields	Returned By
`dashboard`	`connected`, `memory_count`, `plugin_count`, `skill_count`, `scheduled_task_count`, `recent_executions`	`get_dashboard`
`plugins`	`plugins`: array of {name, version, plugin_type, capabilities, enabled}	`list_plugins`
`skills`	`skills`: array of skill info objects	`list_skills`
`memories`	Paginated list with `entries`, `page`, `per_page`, `total`	`list_memories`
`memory_search`	`results`: array of {entry, similarity}	`search_memories`
`scheduled_tasks`	`tasks`: array of {id, name, cron_expression, handler_type, enabled, last_run, next_run}	`list_scheduled_tasks`
`task_executions`	`executions`: array of {task_id, started_at, completed_at, success, error}	`list_task_executions`
`config`	`llm_provider`, `llm_model`, `scheduler_enabled`, `scheduler_check_interval_secs`, `audit_dir`	`get_config`
`success`	`message` (string)	`toggle_plugin`, `toggle_task`, `trigger_task`, `delete_memory`, `update_config`
`error`	`code` (string), `message` (string)	Any request on failure

Example: Toggle a Plugin

Request json

{
  "type": "admin",
  "request_id": "req-001",
  "payload": {
    "action": "toggle_plugin",
    "name": "hello-plugin",
    "enabled": false
  }
}

Response json

{
  "type": "admin_response",
  "request_id": "req-001",
  "payload": {
    "result": "success",
    "message": "Plugin 'hello-plugin' disabled"
  }
}

Example: Semantic Memory Search

Request json

{
  "type": "admin",
  "request_id": "req-002",
  "payload": {
    "action": "search_memories",
    "query": "API authentication patterns",
    "limit": 3
  }
}

Response json

{
  "type": "admin_response",
  "request_id": "req-002",
  "payload": {
    "result": "memory_search",
    "results": [
      {
        "entry": {
          "id": "mem-abc",
          "content": "OAuth2 with PKCE is preferred for public clients",
          "category": "decision",
          "tags": ["auth", "oauth"],
          "confidence": "high"
        },
        "similarity": 0.82
      }
    ]
  }
}