PluginStatusResponse

Response after enabling or disabling a plugin

healthCheckErrorstring | nullnullable

Health check error message (None if passed or not performed)

healthCheckLatencyMsinteger,null<int64>nullable

Health check latency in milliseconds (None if not performed)

Possible values: >= 0

Example: 150

healthCheckPassedboolean | nullnullable

Health check passed (None if not performed)

Example: true

healthCheckPerformedboolean

Whether a health check was performed

Example: true

messagestringrequired

Status change message

Example: Plugin enabled successfully

plugin objectrequired

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

Internal server-side configuration (not sent to plugin)

searchResultsLimitinteger,null<int32>nullable

Maximum results returned by metadata search (None = plugin default)

Possible values: >= 0

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

Cached manifest from plugin (if available)

adminSetupInstructionsstring | nullnullable

Admin-facing setup instructions (e.g., how to create OAuth app, set client ID)

authorstring | nullnullable

Author

capabilities objectrequired

Plugin capabilities

externalIdSourcestring | nullnullable

External ID source for matching sync entries to series (e.g., "api:anilist")

metadataProviderstring[]

Content types this plugin can provide metadata for (e.g., ["series", "book"])

releaseSourceboolean

Whether the plugin declares the release_source capability (announces new chapter / volume releases for tracked series).

userReadSyncboolean

Can sync user reading progress

userRecommendationProviderboolean

Can provide personalized recommendations

wantsDetailedProgressboolean

Whether the plugin consumes the per-book reading-progress breakdown on the sync entries it receives. Only meaningful when user_read_sync is true.

wantsFullMetadataboolean

Whether the plugin consumes enriched series data (bibliographic metadata, custom metadata) on the sync/recommendation entries it receives.

configSchema object

Configuration schema documenting available config options

descriptionstring | nullnullable

Human-readable description of the configuration

fields object[]required

List of configuration fields

Array [

default

Default value if not provided

descriptionstring | nullnullable

Description of what this field does

example

Example value for documentation

keystringrequired

Field name (key in JSON config)

labelstringrequired

Human-readable label

requiredboolean

Whether this field is required

typestringrequired

Field type — free-form documentation hint. Common values: "number", "string", "boolean", "string-array", "object". The host never validates stored config against this; it forwards the raw JSON to the plugin.

]

contentTypesstring[]required

Supported content types

descriptionstring | nullnullable

Description

displayNamestringrequired

Display name for UI

homepagestring | nullnullable

Homepage URL

namestringrequired

Unique identifier

oauth object

OAuth 2.0 configuration (if plugin supports OAuth)

authorizationUrlstringrequired

OAuth 2.0 authorization endpoint URL

pkcebooleanrequired

Whether to use PKCE (Proof Key for Code Exchange)

scopesstring[]

Required OAuth scopes

tokenUrlstringrequired

OAuth 2.0 token endpoint URL

userInfoUrlstring | nullnullable

Optional user info endpoint URL

protocolVersionstringrequired

Protocol version

requiredCredentials object[]

Required credentials

Array [

credentialTypestringrequired

Input type for UI

descriptionstring | nullnullable

Description for the user

keystringrequired

Credential key (e.g., "api_key")

labelstringrequired

Display label (e.g., "API Key")

requiredboolean

Whether this credential is required

sensitiveboolean

Whether to mask the value in UI

]

scopesstring[]

Supported scopes

searchUriTemplatestring | nullnullable

URI template for searching on the plugin's website

userSetupInstructionsstring | nullnullable

User-facing setup instructions (e.g., how to connect or get a personal token)

versionstringrequired

Semantic version

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

PluginStatusResponse

{
  "healthCheckError": "string",
  "healthCheckLatencyMs": 150,
  "healthCheckPassed": true,
  "healthCheckPerformed": true,
  "message": "Plugin enabled successfully",
  "plugin": {
    "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": {
      "searchResultsLimit": 0
    },
    "lastFailureAt": "2024-07-29T15:51:28.071Z",
    "lastSuccessAt": "2024-07-29T15:51:28.071Z",
    "libraryIds": [],
    "logLevel": "debug",
    "manifest": {
      "adminSetupInstructions": "string",
      "author": "string",
      "capabilities": {
        "externalIdSource": "string",
        "metadataProvider": [
          "string"
        ],
        "releaseSource": true,
        "userReadSync": true,
        "userRecommendationProvider": true,
        "wantsDetailedProgress": true,
        "wantsFullMetadata": true
      },
      "configSchema": {
        "description": "string",
        "fields": [
          {
            "description": "string",
            "key": "string",
            "label": "string",
            "required": true,
            "type": "string"
          }
        ]
      },
      "contentTypes": [
        "string"
      ],
      "description": "string",
      "displayName": "string",
      "homepage": "string",
      "name": "string",
      "oauth": {
        "authorizationUrl": "string",
        "pkce": true,
        "scopes": [
          "string"
        ],
        "tokenUrl": "string",
        "userInfoUrl": "string"
      },
      "protocolVersion": "string",
      "requiredCredentials": [
        {
          "credentialType": "string",
          "description": "string",
          "key": "string",
          "label": "string",
          "required": true,
          "sensitive": true
        }
      ],
      "scopes": [
        "string"
      ],
      "searchUriTemplate": "string",
      "userSetupInstructions": "string",
      "version": "string"
    },
    "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"
  }
}