UserPluginsListResponse

User plugins list response

available object[]required

Plugins available for the user to enable

Array [

capabilities objectrequired

Plugin capabilities

readSyncbooleanrequired

Can sync reading progress

userRecommendationProviderbooleanrequired

Can provide recommendations

wantsDetailedProgressbooleanrequired

Consumes the per-book reading-progress breakdown (readBooks); when set, the host attaches per-book volume/chapter/page detail to sync entries.

wantsFullMetadatabooleanrequired

Consumes enriched series data; gates whether the _codex.send* metadata toggles are shown on the connection.

descriptionstring | nullnullable

Plugin description

displayNamestringrequired

Plugin display name

namestringrequired

Plugin name

oauthConfiguredbooleanrequired

Whether the admin has configured OAuth credentials (client_id set)

pluginIdstring<uuid>required

Plugin definition ID

requiresOauthbooleanrequired

Whether this plugin requires OAuth authentication

userSetupInstructionsstring | nullnullable

User-facing setup instructions for the plugin

]

enabled object[]required

Plugins the user has enabled

Array [

autoSyncbooleanrequired

Whether this connection is opted into automatic scheduled syncs (host-side preference, derived from config._codex.autoSync). When false (the default), syncs run only when manually triggered.

capabilities objectrequired

Plugin capabilities (derived from manifest)

readSyncbooleanrequired

Can sync reading progress

userRecommendationProviderbooleanrequired

Can provide recommendations

wantsDetailedProgressbooleanrequired

Consumes the per-book reading-progress breakdown (readBooks); when set, the host attaches per-book volume/chapter/page detail to sync entries.

wantsFullMetadatabooleanrequired

Consumes enriched series data; gates whether the _codex.send* metadata toggles are shown on the connection.

configrequired

Per-user configuration

connectedbooleanrequired

Whether the plugin is connected and ready to operate. True when the plugin has valid credentials/OAuth, or when it requires no per-user authentication (credential-less or shared-key plugins).

createdAtstring<date-time>required

Created timestamp

descriptionstring | nullnullable

User-facing description of the plugin

enabledbooleanrequired

Whether the user has enabled this plugin

externalAvatarUrlstring | nullnullable

External service avatar URL

externalUsernamestring | nullnullable

External service username (if connected via OAuth)

healthStatusstringrequired

Health status of this user's plugin instance

idstring<uuid>required

User plugin instance ID

lastSuccessAtstring,null<date-time>nullable

Last successful operation timestamp

lastSyncAtstring,null<date-time>nullable

Last sync timestamp

lastSyncResult

Last sync result summary (stored in user_plugin_data)

oauthConfiguredbooleanrequired

Whether the admin has configured OAuth credentials (client_id set)

pluginDisplayNamestringrequired

Plugin display name for UI

pluginIdstring<uuid>required

Plugin definition ID

pluginNamestringrequired

Plugin display name

pluginTypestringrequired

Plugin type: "system" or "user"

requiresAuthbooleanrequired

Whether this plugin requires per-user authentication (OAuth or required credentials). When false, the connect/disconnect flow is not applicable; the plugin is usable as soon as it is enabled.

requiresOauthbooleanrequired

Whether this plugin requires OAuth authentication

sendCustomMetadatabooleanrequired

User privacy opt-out for sending user-defined custom metadata (host-side, from config._codex.sendCustomMetadata). Default false. tags/genres/the bibliographic block are admin policy on the plugin, not user-controlled.

syncCronSchedulestring | nullnullable

The admin-configured cron schedule that drives automatic syncs for this plugin (the normalized 6-field form), or None when the admin has not set one. Surfaced read-only so the UI can show the cadence to users and indicate when auto sync isn't set up yet. The cadence is plugin-wide, not per-user.

userConfigSchema object

oneOf

• null
• ConfigSchemaDto

null

userSetupInstructionsstring | nullnullable

User-facing setup instructions for the plugin

]

UserPluginsListResponse

{
  "available": [
    {
      "capabilities": {
        "readSync": true,
        "userRecommendationProvider": true,
        "wantsDetailedProgress": true,
        "wantsFullMetadata": true
      },
      "description": "string",
      "displayName": "string",
      "name": "string",
      "oauthConfigured": true,
      "pluginId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "requiresOauth": true,
      "userSetupInstructions": "string"
    }
  ],
  "enabled": [
    {
      "autoSync": true,
      "capabilities": {
        "readSync": true,
        "userRecommendationProvider": true,
        "wantsDetailedProgress": true,
        "wantsFullMetadata": true
      },
      "connected": true,
      "createdAt": "2024-07-29T15:51:28.071Z",
      "description": "string",
      "enabled": true,
      "externalAvatarUrl": "string",
      "externalUsername": "string",
      "healthStatus": "string",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "lastSuccessAt": "2024-07-29T15:51:28.071Z",
      "lastSyncAt": "2024-07-29T15:51:28.071Z",
      "oauthConfigured": true,
      "pluginDisplayName": "string",
      "pluginId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "pluginName": "string",
      "pluginType": "string",
      "requiresAuth": true,
      "requiresOauth": true,
      "sendCustomMetadata": true,
      "syncCronSchedule": "string",
      "userConfigSchema": "null",
      "userSetupInstructions": "string"
    }
  ]
}