Docker Plugin API

openapi: 3.2.0
info:
  title: Docker Engine Config Plugin API
  version: '1.54'
  x-logo:
    url: https://docs.docker.com/assets/images/logo-docker-main.png
  description: "The Engine API is an HTTP API served by Docker Engine. It is the API the\nDocker client uses to communicate with the Engine, so everything the Docker\nclient can do can be done with the API.\n\nMost of the client's commands map directly to API endpoints (e.g. `docker ps`\nis `GET /containers/json`). The notable exception is running containers,\nwhich consists of several API calls.\n\n# Errors\n\nThe API uses standard HTTP status codes to indicate the success or failure\nof the API call. The body of the response will be JSON in the following\nformat:\n\n```\n{\n  \"message\": \"page not found\"\n}\n```\n\n# Versioning\n\nThe API is usually changed in each release, so API calls are versioned to\nensure that clients don't break. To lock to a specific version of the API,\nyou prefix the URL with its version, for example, call `/v1.30/info` to use\nthe v1.30 version of the `/info` endpoint. If the API version specified in\nthe URL is not supported by the daemon, a HTTP `400 Bad Request` error message\nis returned.\n\nIf you omit the version-prefix, the current version of the API (v1.50) is used.\nFor example, calling `/info` is the same as calling `/v1.52/info`. Using the\nAPI without a version-prefix is deprecated and will be removed in a future release.\n\nEngine releases in the near future should support this version of the API,\nso your client will continue to work even if it is talking to a newer Engine.\n\nThe API uses an open schema model, which means the server may add extra properties\nto responses. Likewise, the server will ignore any extra query parameters and\nrequest body properties. When you write clients, you need to ignore additional\nproperties in responses to ensure they do not break when talking to newer\ndaemons.\n\n\n# Authentication\n\nAuthentication for registries is handled client side. The client has to send\nauthentication details to various endpoints that need to communicate with\nregistries, such as `POST /images/(name)/push`. These are sent as\n`X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5)\n(JSON) string with the following structure:\n\n```\n{\n  \"username\": \"string\",\n  \"password\": \"string\",\n  \"serveraddress\": \"string\"\n}\n```\n\nThe `serveraddress` is a domain/IP without a protocol. Throughout this\nstructure, double quotes are required.\n\nIf you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth),\nyou can just pass this instead of credentials:\n\n```\n{\n  \"identitytoken\": \"9cbaf023786cd7...\"\n}\n```\n"
servers:
- url: /v1.54
tags:
- name: Plugin
  x-displayName: Plugins
paths:
  /plugins:
    get:
      summary: List plugins
      operationId: PluginList
      description: Returns information about installed plugins.
      responses:
        200:
          description: No error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Plugin'
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: filters
        in: query
        description: 'A JSON encoded value of the filters (a `map[string][]string`) to

          process on the plugin list.


          Available filters:


          - `capability=<capability name>`

          - `enable=<true>|<false>`

          '
        schema:
          type: string
      tags:
      - Plugin
  /plugins/privileges:
    get:
      summary: Get plugin privileges
      operationId: GetPluginPrivileges
      responses:
        200:
          description: no error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PluginPrivilege'
                example:
                - Name: network
                  Description: ''
                  Value:
                  - host
                - Name: mount
                  Description: ''
                  Value:
                  - /data
                - Name: device
                  Description: ''
                  Value:
                  - /dev/cpu_dma_latency
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PluginPrivilege'
                example:
                - Name: network
                  Description: ''
                  Value:
                  - host
                - Name: mount
                  Description: ''
                  Value:
                  - /data
                - Name: device
                  Description: ''
                  Value:
                  - /dev/cpu_dma_latency
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: remote
        in: query
        description: 'The name of the plugin. The `:latest` tag is optional, and is the

          default if omitted.

          '
        required: true
        schema:
          type: string
      tags:
      - Plugin
  /plugins/pull:
    post:
      summary: Install a plugin
      operationId: PluginPull
      description: 'Pulls and installs a plugin. After the plugin is installed, it can be

        enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

        '
      responses:
        204:
          description: no error
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: remote
        in: query
        description: 'Remote reference for plugin to install.


          The `:latest` tag is optional, and is used as the default if omitted.

          '
        required: true
        schema:
          type: string
      - name: name
        in: query
        description: 'Local name for the pulled plugin.


          The `:latest` tag is optional, and is used as the default if omitted.

          '
        required: false
        schema:
          type: string
      - name: X-Registry-Auth
        in: header
        description: 'A base64url-encoded auth configuration to use when pulling a plugin

          from a registry.


          Refer to the [authentication section](#section/Authentication) for

          details.

          '
        schema:
          type: string
      tags:
      - Plugin
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PluginPrivilege'
              example:
              - Name: network
                Description: ''
                Value:
                - host
              - Name: mount
                Description: ''
                Value:
                - /data
              - Name: device
                Description: ''
                Value:
                - /dev/cpu_dma_latency
          text/plain:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PluginPrivilege'
              example:
              - Name: network
                Description: ''
                Value:
                - host
              - Name: mount
                Description: ''
                Value:
                - /data
              - Name: device
                Description: ''
                Value:
                - /dev/cpu_dma_latency
  /plugins/{name}/json:
    get:
      summary: Inspect a plugin
      operationId: PluginInspect
      responses:
        200:
          description: no error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plugin'
            text/plain:
              schema:
                $ref: '#/components/schemas/Plugin'
        404:
          description: plugin is not installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: name
        in: path
        description: 'The name of the plugin. The `:latest` tag is optional, and is the

          default if omitted.

          '
        required: true
        schema:
          type: string
      tags:
      - Plugin
  /plugins/{name}:
    delete:
      summary: Remove a plugin
      operationId: PluginDelete
      responses:
        200:
          description: no error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plugin'
            text/plain:
              schema:
                $ref: '#/components/schemas/Plugin'
        404:
          description: plugin is not installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: name
        in: path
        description: 'The name of the plugin. The `:latest` tag is optional, and is the

          default if omitted.

          '
        required: true
        schema:
          type: string
      - name: force
        in: query
        description: 'Disable the plugin before removing. This may result in issues if the

          plugin is in use by a container.

          '
        schema:
          type: boolean
          default: false
      tags:
      - Plugin
  /plugins/{name}/enable:
    post:
      summary: Enable a plugin
      operationId: PluginEnable
      responses:
        200:
          description: no error
        404:
          description: plugin is not installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: name
        in: path
        description: 'The name of the plugin. The `:latest` tag is optional, and is the

          default if omitted.

          '
        required: true
        schema:
          type: string
      - name: timeout
        in: query
        description: Set the HTTP client timeout (in seconds)
        schema:
          type: integer
          default: 0
      tags:
      - Plugin
  /plugins/{name}/disable:
    post:
      summary: Disable a plugin
      operationId: PluginDisable
      responses:
        200:
          description: no error
        404:
          description: plugin is not installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: name
        in: path
        description: 'The name of the plugin. The `:latest` tag is optional, and is the

          default if omitted.

          '
        required: true
        schema:
          type: string
      - name: force
        in: query
        description: 'Force disable a plugin even if still in use.

          '
        required: false
        schema:
          type: boolean
      tags:
      - Plugin
  /plugins/{name}/upgrade:
    post:
      summary: Upgrade a plugin
      operationId: PluginUpgrade
      responses:
        204:
          description: no error
        404:
          description: plugin not installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: name
        in: path
        description: 'The name of the plugin. The `:latest` tag is optional, and is the

          default if omitted.

          '
        required: true
        schema:
          type: string
      - name: remote
        in: query
        description: 'Remote reference to upgrade to.


          The `:latest` tag is optional, and is used as the default if omitted.

          '
        required: true
        schema:
          type: string
      - name: X-Registry-Auth
        in: header
        description: 'A base64url-encoded auth configuration to use when pulling a plugin

          from a registry.


          Refer to the [authentication section](#section/Authentication) for

          details.

          '
        schema:
          type: string
      tags:
      - Plugin
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PluginPrivilege'
              example:
              - Name: network
                Description: ''
                Value:
                - host
              - Name: mount
                Description: ''
                Value:
                - /data
              - Name: device
                Description: ''
                Value:
                - /dev/cpu_dma_latency
          text/plain:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PluginPrivilege'
              example:
              - Name: network
                Description: ''
                Value:
                - host
              - Name: mount
                Description: ''
                Value:
                - /data
              - Name: device
                Description: ''
                Value:
                - /dev/cpu_dma_latency
  /plugins/create:
    post:
      summary: Create a plugin
      operationId: PluginCreate
      responses:
        204:
          description: no error
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: name
        in: query
        description: 'The name of the plugin. The `:latest` tag is optional, and is the

          default if omitted.

          '
        required: true
        schema:
          type: string
      tags:
      - Plugin
      requestBody:
        content:
          application/x-tar:
            schema:
              type: string
              format: binary
        description: Path to tar containing plugin rootfs and manifest
  /plugins/{name}/push:
    post:
      summary: Push a plugin
      operationId: PluginPush
      description: 'Push a plugin to the registry.

        '
      parameters:
      - name: name
        in: path
        description: 'The name of the plugin. The `:latest` tag is optional, and is the

          default if omitted.

          '
        required: true
        schema:
          type: string
      responses:
        200:
          description: no error
        404:
          description: plugin not installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Plugin
  /plugins/{name}/set:
    post:
      summary: Configure a plugin
      operationId: PluginSet
      parameters:
      - name: name
        in: path
        description: 'The name of the plugin. The `:latest` tag is optional, and is the

          default if omitted.

          '
        required: true
        schema:
          type: string
      responses:
        204:
          description: No error
        404:
          description: Plugin not installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Plugin
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
              example:
              - DEBUG=1
components:
  schemas:
    PluginEnv:
      type: object
      x-go-name: Env
      required:
      - Name
      - Description
      - Settable
      - Value
      properties:
        Name:
          type: string
        Description:
          type: string
        Settable:
          type: array
          items:
            type: string
        Value:
          type: string
    ErrorResponse:
      description: Represents an error.
      type: object
      required:
      - message
      properties:
        message:
          description: The error message.
          type: string
      example:
        message: Something went wrong.
    PluginMount:
      type: object
      x-go-name: Mount
      required:
      - Name
      - Description
      - Settable
      - Source
      - Destination
      - Type
      - Options
      properties:
        Name:
          type: string
          example: some-mount
        Description:
          type: string
          example: This is a mount that's used by the plugin.
        Settable:
          type: array
          items:
            type: string
        Source:
          type: string
          example: /var/lib/docker/plugins/
        Destination:
          type: string
          example: /mnt/state
        Type:
          type: string
          example: bind
        Options:
          type: array
          items:
            type: string
          example:
          - rbind
          - rw
    PluginPrivilege:
      description: 'Describes a permission the user has to accept upon installing

        the plugin.

        '
      type: object
      x-go-name: Privilege
      properties:
        Name:
          type: string
          example: network
        Description:
          type: string
        Value:
          type: array
          items:
            type: string
          example:
          - host
    Plugin:
      description: A plugin for the Engine API
      type: object
      x-go-name: Plugin
      required:
      - Settings
      - Enabled
      - Config
      - Name
      properties:
        Id:
          type: string
          example: 5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078
        Name:
          type: string
          example: tiborvass/sample-volume-plugin
        Enabled:
          description: True if the plugin is running. False if the plugin is not running, only installed.
          type: boolean
          example: true
        Settings:
          description: user-configurable settings for the plugin.
          type: object
          x-go-name: Settings
          required:
          - Args
          - Devices
          - Env
          - Mounts
          properties:
            Mounts:
              type: array
              items:
                $ref: '#/components/schemas/PluginMount'
            Env:
              type: array
              items:
                type: string
              example:
              - DEBUG=0
            Args:
              type: array
              items:
                type: string
            Devices:
              type: array
              items:
                $ref: '#/components/schemas/PluginDevice'
        PluginReference:
          description: plugin remote reference used to push/pull the plugin
          type: string
          x-go-name: PluginReference
          example: localhost:5000/tiborvass/sample-volume-plugin:latest
        Config:
          description: The config of a plugin.
          type: object
          x-go-name: Config
          required:
          - Description
          - Documentation
          - Interface
          - Entrypoint
          - WorkDir
          - Network
          - Linux
          - PidHost
          - PropagatedMount
          - IpcHost
          - Mounts
          - Env
          - Args
          properties:
            Description:
              type: string
              example: A sample volume plugin for Docker
            Documentation:
              type: string
              example: https://docs.docker.com/engine/extend/plugins/
            Interface:
              description: The interface between Docker and the plugin
              type: object
              x-go-name: Interface
              required:
              - Types
              - Socket
              properties:
                Types:
                  type: array
                  items:
                    type: string
                    x-go-type:
                      type: CapabilityID
                  example:
                  - docker.volumedriver/1.0
                Socket:
                  type: string
                  example: plugins.sock
                ProtocolScheme:
                  type: string
                  example: some.protocol/v1.0
                  description: Protocol to use for clients connecting to the plugin.
                  enum:
                  - ''
                  - moby.plugins.http/v1
            Entrypoint:
              type: array
              items:
                type: string
              example:
              - /usr/bin/sample-volume-plugin
              - /data
            WorkDir:
              type: string
              example: /bin/
            User:
              type: object
              x-go-name: User
              properties:
                UID:
                  type: integer
                  format: uint32
                  example: 1000
                GID:
                  type: integer
                  format: uint32
                  example: 1000
            Network:
              type: object
              x-go-name: NetworkConfig
              required:
              - Type
              properties:
                Type:
                  type: string
                  example: host
            Linux:
              type: object
              x-go-name: LinuxConfig
              required:
              - Capabilities
              - AllowAllDevices
              - Devices
              properties:
                Capabilities:
                  type: array
                  items:
                    type: string
                  example:
                  - CAP_SYS_ADMIN
                  - CAP_SYSLOG
                AllowAllDevices:
                  type: boolean
                  example: false
                Devices:
                  type: array
                  items:
                    $ref: '#/components/schemas/PluginDevice'
            PropagatedMount:
              type: string
              example: /mnt/volumes
            IpcHost:
              type: boolean
              example: false
            PidHost:
              type: boolean
              example: false
            Mounts:
              type: array
              items:
                $ref: '#/components/schemas/PluginMount'
            Env:
              type: array
              items:
                $ref: '#/components/schemas/PluginEnv'
              example:
              - Name: DEBUG
                Description: If set, prints debug messages
                Settable: null
                Value: '0'
            Args:
              type: object
              x-go-name: Args
              required:
              - Name
              - Description
              - Settable
              - Value
              properties:
                Name:
                  type: string
                  example: args
                Description:
                  type: string
                  example: command line arguments
                Settable:
                  type: array
                  items:
                    type: string
                Value:
                  type: array
                  items:
                    type: string
            rootfs:
              type: object
              x-go-name: RootFS
              properties:
                type:
                  type: string
                  example: layers
                diff_ids:
                  type: array
                  items:
                    type: string
                  example:
                  - sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887
                  - sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8
    PluginDevice:
      type: object
      x-go-name: Device
      required:
      - Name
      - Description
      - Settable
      - Path
      properties:
        Name:
          type: string
        Description:
          type: string
        Settable:
          type: array
          items:
            type: string
        Path:
          type: string
          example: /dev/fuse