> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mudstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin API Reference

> Complete reference for the Plugin API: logging, events, database, config, dependencies, inter-plugin requests, and script execution.

Your plugin receives a single **api** object (e.g. **this.api**) when the runtime instantiates your class. This page documents that API. The types are defined in **@mudstack/plugins** for IntelliSense.

## Logging

### api.log(level, message, payload?)

Log to Mudstack’s console and plugin log file.

* **level**: `'info'` | `'warn'` | `'error'` | `'debug'`
* **message**: String message.
* **payload**: Optional data (object, string, etc.) attached to the log entry.

Example:

```js theme={null}
this.api.log("info", "Processing asset", { assetId, versionId });
```

***

## Events

### api.events

Event manager for subscribing and (via sendEvent) emitting.

### api.events.on(eventType, handler) → unsubscribe

Subscribe to an event type. Supports wildcards (e.g. `file.*`).

* **eventType**: String (e.g. `'file.created'`, `'plugin.activated'`).
* **handler**: `(event: Event<T>) => void | Promise<void>`. **event** has **type**, **payload**, **metadata**.
* **Returns**: A function; call it to unsubscribe. You only need to unsubscribe for subscriptions you add in code (not for manifest **subscriptions**).

Example:

```js theme={null}
const unsub = this.api.events.on("file.newVersion", (ev) => {
  this.api.log("info", "New version", ev.payload);
});
// In deactivate(): unsub();
```

### api.events.off(eventType, handler)

Remove a handler previously registered with **on()**. Use the same **eventType** and **handler** reference.

### api.sendEvent(eventType, payload)

Emit an event to the app and other plugins. **eventType** is a string; **payload** is any serializable value. Other plugins can subscribe via **api.events.on()** or manifest **subscriptions**.

***

## Database (api.db)

The **api.db** object exposes workspace and asset data. All methods are async and communicate with the main process. IDs are UUID-like strings (e.g. **account\_id**, **workspace\_id**, **asset\_id**, **version\_id**, **library\_id**, **tag\_id**).

### api.db.accountAPI

* `getAccount({ account_id })` – Fetch an account by ID.

### api.db.workspaceAPI

* `getWorkspace({ account_id, workspace_id })` – Fetch one workspace.
* `getWorkspaces({ account_id })` – List workspaces for an account.

### api.db.libraryAPI (alias: api.db.library)

* `createLibrary({ workspace_id, name, description })`
* `getLibrary({ workspace_id, library_id })`
* `getLibraries({ workspace_id })`
* `updateLibrary({ workspace_id, library_id, name, description })`
* `updateThumbnail({ workspace_id, library_id, thumbnail_path })`
* **enableSync** / **disableSync** / **deleteLibrary** – With **workspace\_id**, **library\_id**.

### api.db.tagAPI (alias: api.db.tag)

* `createTag({ workspace_id, name, color })`
* `getTag({ workspace_id, tag_id })`
* `getTags({ workspace_id })`
* `updateTag({ workspace_id, tag_id, name, color })`
* `deleteTag({ workspace_id, tag_id })`

### api.db.assetAPI (alias: api.db.asset)

* `getAsset({ workspace_id, asset_id })`
* `getFolderAssets({ workspace_id, folder? })` – List assets in a folder (omit `folder` for root).
* `setCurrentVersion({ workspace_id, asset_id, version_id })`
* `moveAsset({ workspace_id, asset_id, from, to })`
* **disableSync**, **addTags**, **removeTags**, **addToLibrary**, **removeFromLibrary**
* **trashAsset**, **restoreAsset**, **deleteAsset**

### api.db.assetVersionAPI (alias: api.db.assetVersion)

* `getVersionLocalPath({ workspace_id, asset_id, version_id })` – Get local filesystem path for the version's file(s). Use for thumbnailers or processors that need to read the file.
* `getAssetVersion({ workspace_id, asset_id, version_id })`
* `getAssetVersions({ workspace_id, asset_id })`
* `updateThumbnail({ workspace_id, asset_id, version_id, thumbnail_path })` – Set thumbnail image path for a version.
* **trashAssetVersion**, **restoreAssetVersion**, **deleteAssetVersion**

***

## Config (api.config)

Plugin-specific settings. Schema can be defined in manifest **config.schema**; values are validated and merged with defaults.

* **getConfig()** – Current config (merged with schema defaults). Returns `Promise<Record<string, unknown>>`.
* **setConfig(config)** – Persist config. Validates against schema if present.
* **getSchema()** – Config schema from the manifest.
* **validateConfig(config)** – Returns `Promise<{ valid: boolean; errors: string[] }>`.
* **getDefaultConfig()** – Default values from the schema.

Optional (child process): **api.loadedConfig** may be set when config is inherited from another plugin (manifest **config.source** / **config.key**). **api.getConfig(key?)** may be provided to read inherited config by key.

***

## Dependencies

### api.hasDependency(pluginId, version?) → Promise\<boolean>

Returns whether a dependency (e.g. another plugin) is available. **version** is an optional semver range (e.g. `'^1.0.0'`).

### api.getDependency(dependencyId) → Promise\<string>

Resolve the filesystem path of a dependency declared in your manifest **dependencies**. **dependencyId** is the dependency’s **id** in that array.

***

## Inter-plugin requests

### api.requestFromPlugin(targetPluginId, methodName, payload?) → Promise\<T>

Call a method on another plugin. The target plugin must handle the request (e.g. via a subscription or handler) and call **api.respond(requestId, result)** or **api.respondWithError(requestId, error)**. The promise resolves with the response payload or rejects on error/timeout.

### api.respond(requestId, payload?)

Send a successful response for a request you received (e.g. in a subscription handler). **requestId** comes from the incoming message.

### api.respondWithError(requestId, error)

Send an error response. **error** is an **Error** instance; message and stack are sent.

***

## Script and command execution

All execute methods return `Promise<{ exitCode: number; stdout: string; stderr: string }>`. Common options: **timeout**, **cwd**, **env**.

* **executeNodeScript(scriptPath, args?, options?)**
* **executeCommand(command, args?, options?)**
* **executePythonScript(scriptPath, args?, options?)** – options may include **pythonPath**
* **executePowerShellScript(scriptPath, args?, options?)**
* **executeBashScript(scriptPath, args?, options?)**
* **executeCSharpScript(scriptPath, args?, options?)**
* **executeRustScript(scriptPath, args?, options?)**
* **executeGoScript(scriptPath, args?, options?)**
* **executePHPScript(scriptPath, args?, options?)** – options may include **phpPath**
* **executeRubyScript(scriptPath, args?, options?)** – options may include **rubyPath**
* **executePerlScript(scriptPath, args?, options?)** – options may include **perlPath**
* **executeJava(classOrJarPath, args?, options?)** – options may include **javaPath**, **classpath**
* **executeDotNet(executablePath, args?, options?)** – options may include **dotnetPath**
* **executeNative(executablePath, args?, options?)**
* **executeWithInterpreter(interpreterPath, scriptPath, args?, options?)**

***

## Temp directory (child process)

**api.getTempDirectory(purpose?)** – (Available in the plugin child process.) Returns a path to a temporary directory for this plugin. **purpose** is an optional subfolder name (default `'default'`). Use for scratch files or generated assets (e.g. thumbnails) before writing to the path returned for **updateThumbnail**.

***

## Manifest types (reference)

Your **manifest.json** can include:

* **id**, **name**, **version**, **description**, **author**, **main**, **enabled**
* **dependencies**: `[{ id, version?, optional?, type? }]`
* **subscriptions**: `[{ event, handler }]` – event type and method name on your class.
* **registrations**: `[{ event, payload }]` – emitted on activation (e.g. thumbnailer registration).
* **contextMenuCommands**: `[{ id, title, description?, eventType, filter?, ... }]`
* **config**: `{ schema?, source?, key? }` – schema for settings; **source**/**key** for inheriting from another plugin’s config.

For full TypeScript types and interfaces (Event, ConfigSchema, ContextMenuCommand, PluginManifest, etc.), install **@mudstack/plugins** and use the exported types in your IDE.