Skip to main content
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: 
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: 
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.