Skip to main content

Admin API

Administrative endpoints for runtime management of ClawDesk components. All admin endpoints are prefixed with /api/v1/admin/.

warning

Admin endpoints should be protected in production environments. Configure access control via the security settings in config.toml.

Base URL​

http://localhost:1420/api/v1/admin

Plugins​

GET /api/v1/admin/plugins​

List all loaded plugins and their status.

Response 200 OK:

{
  "plugins": [
    {
      "name": "weather-tool",
      "version": "1.0.0",
      "status": "active",
      "loaded_at": "2026-02-17T09:00:00Z",
      "sandbox": "wasm",
      "capabilities": ["tool_call"]
    },
    {
      "name": "custom-formatter",
      "version": "0.2.1",
      "status": "active",
      "loaded_at": "2026-02-17T09:00:00Z",
      "sandbox": "native",
      "capabilities": ["message_transform"]
    }
  ]
}

POST /api/v1/admin/plugins/:name/reload​

Hot-reload a specific plugin.

Response 200 OK:

{
  "name": "weather-tool",
  "status": "reloaded",
  "version": "1.0.1",
  "reload_time_ms": 45
}

Error 404 Not Found:

{
  "error": "not_found",
  "message": "Plugin 'unknown-plugin' is not registered"
}

Cron Tasks​

GET /api/v1/admin/cron/tasks​

List all scheduled cron tasks.

Response 200 OK:

{
  "tasks": [
    {
      "id": "cron_001",
      "name": "session-cleanup",
      "schedule": "0 */6 * * *",
      "status": "scheduled",
      "last_run": "2026-02-17T06:00:00Z",
      "next_run": "2026-02-17T12:00:00Z",
      "run_count": 42
    },
    {
      "id": "cron_002",
      "name": "metrics-export",
      "schedule": "*/5 * * * *",
      "status": "scheduled",
      "last_run": "2026-02-17T10:25:00Z",
      "next_run": "2026-02-17T10:30:00Z",
      "run_count": 1200
    }
  ]
}

POST /api/v1/admin/cron/tasks​

Create a new cron task.

Request Body:

{
  "name": "daily-report",
  "schedule": "0 9 * * *",
  "action": {
    "type": "webhook",
    "url": "https://example.com/report",
    "method": "POST"
  },
  "enabled": true
}

Response 201 Created:

{
  "id": "cron_003",
  "name": "daily-report",
  "schedule": "0 9 * * *",
  "status": "scheduled",
  "next_run": "2026-02-18T09:00:00Z"
}

POST /api/v1/admin/cron/tasks/:id/trigger​

Manually trigger a cron task immediately.

Response 200 OK:

{
  "id": "cron_001",
  "name": "session-cleanup",
  "triggered_at": "2026-02-17T10:30:00Z",
  "status": "running"
}

Skills​

GET /api/v1/admin/skills​

List all registered skills.

Response 200 OK:

{
  "skills": [
    {
      "id": "web-search",
      "name": "Web Search",
      "version": "1.0.0",
      "status": "active",
      "description": "Search the web using multiple providers",
      "trigger_patterns": ["search for", "look up", "find"]
    },
    {
      "id": "code-execution",
      "name": "Code Execution",
      "version": "0.3.0",
      "status": "active",
      "description": "Execute code snippets in a sandboxed environment",
      "trigger_patterns": ["run this code", "execute"]
    }
  ]
}

POST /api/v1/admin/skills/reload​

Hot-reload all skills from the skills directory.

Response 200 OK:

{
  "reloaded": 5,
  "failed": 0,
  "skills": ["web-search", "code-execution", "file-manager", "calculator", "translator"]
}

POST /api/v1/admin/skills/:id/activate​

Activate a specific skill.

Response 200 OK:

{
  "id": "web-search",
  "status": "active",
  "activated_at": "2026-02-17T10:30:00Z"
}

POST /api/v1/admin/skills/:id/deactivate​

Deactivate a specific skill.

Response 200 OK:

{
  "id": "web-search",
  "status": "inactive",
  "deactivated_at": "2026-02-17T10:30:00Z"
}

Channels​

POST /api/v1/admin/channels/reload​

Hot-reload channel configurations and rebuild the channel registry.

Response 200 OK:

{
  "reloaded": 3,
  "channels": [
    { "id": "telegram", "status": "reconnected" },
    { "id": "discord", "status": "reconnected" },
    { "id": "slack", "status": "reconnected" }
  ]
}

Metrics​

GET /api/v1/admin/metrics​

Get runtime metrics in Prometheus-compatible format or JSON.

Headers:

Accept HeaderResponse Format
application/jsonJSON metrics
text/plainPrometheus text format

Response 200 OK (JSON):

{
  "uptime_secs": 86400,
  "requests": {
    "total": 15420,
    "success": 15100,
    "errors": 320
  },
  "sessions": {
    "active": 42,
    "total_created": 256
  },
  "providers": {
    "anthropic": {
      "requests": 12000,
      "errors": 150,
      "avg_latency_ms": 820,
      "tokens_used": 2450000
    },
    "openai": {
      "requests": 3000,
      "errors": 45,
      "avg_latency_ms": 650,
      "tokens_used": 890000
    }
  },
  "channels": {
    "telegram": { "messages_sent": 8000, "messages_received": 7500 },
    "discord": { "messages_sent": 5000, "messages_received": 4800 }
  },
  "memory": {
    "heap_bytes": 52428800,
    "rss_bytes": 104857600
  }
}

Response 200 OK (Prometheus):

# HELP clawdesk_requests_total Total number of requests
# TYPE clawdesk_requests_total counter
clawdesk_requests_total{status="success"} 15100
clawdesk_requests_total{status="error"} 320

# HELP clawdesk_active_sessions Number of active sessions
# TYPE clawdesk_active_sessions gauge
clawdesk_active_sessions 42

# HELP clawdesk_provider_latency_ms Provider response latency
# TYPE clawdesk_provider_latency_ms histogram
clawdesk_provider_latency_ms_bucket{provider="anthropic",le="500"} 4200
clawdesk_provider_latency_ms_bucket{provider="anthropic",le="1000"} 9800