Skip to main content

PluginDto

A plugin (credentials are never exposed)

argsstring[]required

Command arguments

Example: ["/opt/codex/plugins/mangabaka/dist/index.js"]
autoMatchConditions

Auto-match conditions (JSON object with mode and rules)

commandstringrequired

Command to spawn the plugin

Example: node
configrequired

Plugin-specific configuration

createdAtstring<date-time>required

When the plugin was created

credentialDeliverystringrequired

How credentials are delivered to the plugin

Example: env
defaultLogLevelstring | nullnullable

Read-only: the default log level a plugin gets when it has no override, i.e. the server's own logging.level (with trace shown as debug). Surfaced so the UI can label what "use the server default" resolves to.

Example: info
descriptionstring | nullnullable

Description of the plugin

Example: Fetch manga metadata from MangaBaka (MangaUpdates)
disabledReasonstring | nullnullable

Reason the plugin was disabled

displayNamestringrequired

Human-readable display name

Example: MangaBaka
enabledbooleanrequired

Whether the plugin is enabled

Example: true
envrequired

Additional environment variables (non-sensitive only)

failureCountinteger<int32>required

Number of consecutive failures

Example: 0
hasCredentialsbooleanrequired

Whether credentials have been set (actual credentials are never returned)

Example: true
healthStatusstringrequired

Health status: unknown, healthy, degraded, unhealthy, disabled

Example: healthy
idstring<uuid>required

Plugin ID

Example: 550e8400-e29b-41d4-a716-446655440000
internalConfig object
oneOf
null
lastFailureAtstring,null<date-time>nullable

When the last failure occurred

lastSuccessAtstring,null<date-time>nullable

When the last successful operation occurred

libraryIdsstring<uuid>[]required

Library IDs this plugin applies to (empty = all libraries)

Example: []
logLevelstring | nullnullable

Per-plugin override for the log level sent to the plugin at startup (error/warn/info/debug). None means "use the server default".

Example: debug
manifest object
oneOf
null
metadataTargetsstring[]nullable

Metadata targets: which resource types this plugin auto-matches against null = auto-detect from plugin capabilities

Example: ["series","book"]
namestringrequired

Unique identifier (e.g., "mangabaka")

Example: mangabaka
permissionsstring[]required

RBAC permissions for metadata writes

Example: ["metadata:write:summary","metadata:write:genres"]
pluginTypestringrequired

Plugin type: "system" (admin-configured) or "user" (per-user instances)

Example: system
rateLimitRequestsPerMinuteinteger,null<int32>nullable

Rate limit in requests per minute (None = no limit)

Example: 60
requestTimeoutSecondsinteger,null<int32>nullable

Per-plugin override for the host → plugin RPC deadline, in seconds. None means "use the server default" (typically 30s).

Example: 300
scopesstring[]required

Scopes where plugin can be invoked

Example: ["series:detail","series:bulk"]
searchPreprocessingRules

Preprocessing rules for search queries (JSON array of regex rules)

searchQueryTemplatestring | nullnullable

Handlebars template for customizing search queries

syncCronSchedulestring | nullnullable

Admin-managed cron schedule for automatic user-plugin syncs (null = no scheduled sync)

Example: 0 0 */6 * * *
updatedAtstring<date-time>required

When the plugin was last updated

useExistingExternalIdbooleanrequired

Whether to skip search when external ID exists for this plugin

Example: true
userCountinteger,null<int64>nullable

Number of users who have enabled this plugin (only for user-type plugins)

Possible values: >= 0

Example: 3
workingDirectorystring | nullnullable

Working directory for the plugin process

PluginDto
{
  "args": [
    "/opt/codex/plugins/mangabaka/dist/index.js"
  ],
  "command": "node",
  "createdAt": "2024-07-29T15:51:28.071Z",
  "credentialDelivery": "env",
  "defaultLogLevel": "info",
  "description": "Fetch manga metadata from MangaBaka (MangaUpdates)",
  "disabledReason": "string",
  "displayName": "MangaBaka",
  "enabled": true,
  "failureCount": 0,
  "hasCredentials": true,
  "healthStatus": "healthy",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "internalConfig": "null",
  "lastFailureAt": "2024-07-29T15:51:28.071Z",
  "lastSuccessAt": "2024-07-29T15:51:28.071Z",
  "libraryIds": [],
  "logLevel": "debug",
  "manifest": "null",
  "metadataTargets": [
    "series",
    "book"
  ],
  "name": "mangabaka",
  "permissions": [
    "metadata:write:summary",
    "metadata:write:genres"
  ],
  "pluginType": "system",
  "rateLimitRequestsPerMinute": 60,
  "requestTimeoutSeconds": 300,
  "scopes": [
    "series:detail",
    "series:bulk"
  ],
  "searchQueryTemplate": "string",
  "syncCronSchedule": "0 0 */6 * * *",
  "updatedAt": "2024-07-29T15:51:28.071Z",
  "useExistingExternalId": true,
  "userCount": 3,
  "workingDirectory": "string"
}