> ## Documentation Index
> Fetch the complete documentation index at: https://empty-ad9a3406.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# api.registry

> Low-level plugin registry access

## Overview

`api.registry` provides low-level access to the plugin registry. Primarily used by the Plugin Manager.

## Registry Methods

### `registry.getAll()`

Returns a deep copy of the registry array.

```javascript theme={null}
const plugins = api.registry.getAll();
// → [{ id: 'hello', name: 'Hello Box', enabled: true, ... }, ...]
```

**Returns:** `Array<PluginDefinition>`

```typescript theme={null}
interface PluginDefinition {
  id: string;
  name: string;
  url: string;
  enabled: boolean;
  source?: 'system' | 'registry' | 'manual';  // How the plugin was installed
  icon?: string;                                // Emoji icon
  author?: string;                              // Plugin author
}
```

### `registry.get(id)`

Returns a single plugin definition by ID (shallow copy), or `null` if not found.

```javascript theme={null}
const plugin = api.registry.get('my-plugin');
// → { id: 'my-plugin', name: 'My Plugin', enabled: true, ... }
```

| Parameter | Type     | Description |
| --------- | -------- | ----------- |
| `id`      | `string` | Plugin ID   |

**Returns:** `PluginDefinition | null`

### `registry.save(newRegistry)`

Overwrites the entire registry and persists to localStorage.

```javascript theme={null}
const plugins = api.registry.getAll();
plugins.push({ id: 'new', name: 'New', url: './new.js', enabled: true });
api.registry.save(plugins);
```

## Management Methods

These are attached directly to `api` (not `api.registry`):

### `api.installPlugin(id, url, name)`

Install a plugin from URL. Validates the URL format and checks for duplicate IDs.

```javascript theme={null}
await api.installPlugin(
  'my-plugin',
  'https://raw.githubusercontent.com/user/repo/main/plugin.js',
  'My Plugin'
);
```

| Parameter | Type     | Description                                                       |
| --------- | -------- | ----------------------------------------------------------------- |
| `id`      | `string` | Unique plugin ID                                                  |
| `url`     | `string` | URL to the `.js` file (must end with `.js`, must be `http(s)://`) |
| `name`    | `string` | Display name (defaults to `id`)                                   |

**Returns:** `Promise<boolean>` — `true` if installed, `false` if ID already exists

<Info>
  Plugins installed via `installPlugin` get `source: 'manual'`. The core will show a warning notification when loading manual plugins.
</Info>

### `api.togglePlugin(id)`

Enable or disable a plugin. Loads the plugin if disabled, unloads if enabled.

```javascript theme={null}
await api.togglePlugin('my-plugin');
```

| Parameter | Type     | Description |
| --------- | -------- | ----------- |
| `id`      | `string` | Plugin ID   |

**Returns:** `Promise<boolean>` — `true` if successful, `false` if not found

### `api.deletePlugin(id)`

Permanently remove a plugin. Unloads it first, then removes from registry.

```javascript theme={null}
api.deletePlugin('my-plugin');
```

| Parameter | Type     | Description |
| --------- | -------- | ----------- |
| `id`      | `string` | Plugin ID   |

**Returns:** `boolean` — `true` if successful, `false` if not found

### `api.reloadPlugin(id)`

Unload and reload a single plugin without restarting the whole board.

```javascript theme={null}
await api.reloadPlugin('my-plugin');
```

| Parameter | Type     | Description |
| --------- | -------- | ----------- |
| `id`      | `string` | Plugin ID   |

**Returns:** `Promise<boolean>` — `true` if successful, `false` if not found

<Tip>
  Use `reloadPlugin` during plugin development to test changes without restarting the entire board.
</Tip>

### `api.restart()`

Unload all plugins, then reload all enabled plugins from the registry.

```javascript theme={null}
await api.restart();
// All plugins are torn down and re-initialized
```

**Emits:** `board:restarted` event after completion.

<Info>
  `restart()` is useful after bulk registry changes or when you need a clean slate.
</Info>

## Plugin ID

### `api.getPluginId()`

Returns the ID of the **currently loading** plugin. Only has a value while a plugin's `setup()` is executing.

```javascript theme={null}
export function setup(api) {
  console.log(api.getPluginId());  // → 'my-plugin'
}
```

**Returns:** `string | null`