Plugins & Registry API

The plugins API manages the agent's plugin system. It covers three areas: plugin management (listing, configuring, enabling/disabling installed plugins), plugin installation (install, uninstall, eject, sync from npm), and the plugin registry (browsing the elizaOS community catalog).

When ELIZA_API_TOKEN is set, include it as a Bearer token in the Authorization header.

Endpoints

Plugin Management

Plugin Installation

Core Plugin Management

Plugin Registry

Plugin Management

GET /api/plugins

List all known plugins — bundled, installed, and discovered from config. Each entry includes enabled/active state, configuration parameters with current values (sensitive values masked), and validation results.

Response

{
  "plugins": [
    {
      "id": "twitter",
      "name": "Twitter",
      "description": "Twitter/X integration",
      "category": "social",
      "enabled": true,
      "isActive": true,
      "configured": true,
      "loadError": null,
      "parameters": [
        {
          "key": "TWITTER_API_KEY",
          "required": true,
          "sensitive": true,
          "isSet": true,
          "currentValue": "sk-****...xxxx"
        }
      ],
      "validationErrors": [],
      "validationWarnings": []
    }
  ]
}

PUT /api/plugins/:id

Update a plugin's enabled state and/or configuration. Enabling/disabling a plugin schedules a runtime restart.

Request Body

{
  "enabled": true,
  "config": {
    "TWITTER_API_KEY": "sk-new-key"
  }
}

Response

{
  "ok": true,
  "plugin": { "id": "twitter", "enabled": true, "..." : "..." }
}

Errors

POST /api/plugins/:id/test

Test a plugin's connectivity or configuration. If the plugin exposes a health probe, it is invoked. Otherwise, a basic "plugin is loaded" status is returned.

Response

{
  "success": true,
  "pluginId": "openai",
  "message": "Connection successful",
  "durationMs": 142
}

Errors

GET /api/plugins/installed

List all installed plugin packages with version information.

Response

{
  "count": 3,
  "plugins": [
    {
      "name": "@elizaos/plugin-x",
      "version": "1.2.0",
      "installedAt": "2025-06-01T12:00:00.000Z"
    }
  ]
}

GET /api/plugins/ejected

List all ejected plugins (plugins that have been copied to a local directory for development).

Response

{
  "plugins": [
    {
      "name": "@elizaos/plugin-x",
      "localPath": "/path/to/local/plugin-twitter"
    }
  ]
}

Plugin Installation

POST /api/plugins/install

Install a plugin package from npm. Plugin installation may take significant time depending on the package size and dependency tree. The client SDK uses a 120-second timeout for this endpoint (compared to the default timeout used for other API calls).

Request Body

Response

{
  "ok": true,
  "requiresRestart": true
}

POST /api/plugins/update

Update an installed plugin to a newer version. Uses the same install mechanism but targets an existing plugin for upgrade.

Request Body

Response

{
  "ok": true,
  "requiresRestart": true
}

POST /api/plugins/uninstall

Uninstall a plugin package.

Request Body

Response

{
  "ok": true,
  "requiresRestart": true
}

POST /api/plugins/:id/eject

Eject a plugin to a local directory for development. Creates a local copy of the plugin source that can be modified independently. If the result indicates a restart is required, the runtime schedules an automatic restart.

Response

{
  "ok": true,
  "pluginName": "@elizaos/plugin-x",
  "requiresRestart": true,
  "message": "@elizaos/plugin-x ejected to local source."
}

Errors

POST /api/plugins/:id/sync

Sync an ejected plugin back — re-build from the local copy.

Response

{
  "ok": true,
  "pluginName": "@elizaos/plugin-x",
  "requiresRestart": true,
  "message": "@elizaos/plugin-x synced with upstream."
}

Errors

POST /api/plugins/:id/reinject

Restore a previously ejected plugin back to its registry version, removing the local copy.

Response

{
  "ok": true,
  "pluginName": "@elizaos/plugin-x",
  "requiresRestart": true,
  "message": "@elizaos/plugin-x restored to registry version."
}

Errors

Core Plugin Management

GET /api/core/status

Get the core manager status and available core plugins.

Response

{
  "available": true,
  "corePlugins": ["knowledge", "sql"],
  "optionalCorePlugins": ["plugin-manager"]
}

• knowledge -- RAG knowledge retrieval
• sql -- Database layer

GET /api/plugins/core

List core and optional-core plugins with their enabled/loaded status.

Response

{
  "core": [
    { "npmName": "@elizaos/plugin-sql", "id": "sql", "name": "Sql", "isCore": true, "loaded": true }
  ],
  "optional": [
    { "npmName": "@elizaos/plugin-browser", "id": "browser", "name": "Browser", "isCore": false, "loaded": true, "enabled": true }
  ]
}

POST /api/plugins/core/toggle

Toggle an optional core plugin on or off. Only plugins in the OPTIONAL_CORE_PLUGINS list can be toggled; core plugins cannot be disabled.

Request Body

Response

{
  "ok": true,
  "requiresRestart": true
}

Plugin Registry

GET /api/registry/plugins

List all plugins from the elizaOS registry with installation and load status.

Response

{
  "count": 87,
  "plugins": [
    {
      "name": "@elizaos/plugin-x",
      "displayName": "Twitter",
      "description": "Twitter/X integration for posting and monitoring",
      "npm": {
        "package": "@elizaos/plugin-x",
        "version": "1.2.0"
      },
      "installed": false,
      "installedVersion": null,
      "loaded": false,
      "bundled": false
    }
  ]
}

GET /api/registry/plugins/:name

Get details for a specific registry plugin. The name parameter should be URL-encoded if it contains slashes (e.g., %40elizaos%2Fplugin-twitter).

Path Parameters

Response

{
  "plugin": {
    "name": "@elizaos/plugin-x",
    "displayName": "Twitter",
    "description": "Twitter/X integration for posting and monitoring",
    "npm": {
      "package": "@elizaos/plugin-x",
      "version": "1.2.0"
    },
    "author": "elizaOS Team",
    "repository": "https://github.com/elizaos/eliza",
    "tags": ["social", "twitter"],
    "installed": false,
    "loaded": false,
    "bundled": false
  }
}

GET /api/registry/search

Search the plugin registry by keyword.

Query Parameters

Response

{
  "query": "twitter",
  "count": 2,
  "results": [
    {
      "name": "@elizaos/plugin-x",
      "displayName": "Twitter",
      "description": "Twitter/X integration",
      "npmPackage": "@elizaos/plugin-x",
      "version": "1.2.0"
    }
  ]
}

POST /api/registry/refresh

Force refresh the local registry cache from the upstream elizaOS registry.

Response

{
  "ok": true,
  "count": 87
}

GET /api/registry/status

Get the agent's registry connection status.

Response

When the registry service is configured:

{
  "registered": true,
  "configured": true,
  "tokenId": 1,
  "agentName": "Eliza",
  "agentEndpoint": "https://...",
  "capabilitiesHash": "...",
  "isActive": true,
  "tokenURI": "https://...",
  "walletAddress": "0x...",
  "totalAgents": 42
}

When the registry service is not configured:

{
  "registered": false,
  "configured": false,
  "tokenId": 0,
  "agentName": "",
  "agentEndpoint": "",
  "capabilitiesHash": "",
  "isActive": false,
  "tokenURI": "",
  "walletAddress": "",
  "totalAgents": 0
}

POST /api/registry/register

Register the agent with the elizaOS registry.

Request Body

Response

Returns the registration result from the registry service (schema depends on registry implementation).

POST /api/registry/update-uri

Update the agent's token URI in the registry.

Request Body

Response

{
  "ok": true
}

POST /api/registry/sync

Sync the agent's state with the registry (heartbeat, status update).

Request Body

Response

{
  "ok": true,
  "txHash": "0x..."
}

GET /api/registry/config

Get the current registry configuration. Returns the contents of config.registry along with chain metadata.

Response

{
  "chainId": 1,
  "explorerUrl": "https://etherscan.io",
  "...": "additional fields from config.registry"
}

The exact response shape depends on what is configured in eliza.json under the registry key.