Docker Node API

openapi: 3.2.0
info:
  title: Docker Engine Config Node 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: Node
  x-displayName: Nodes
  description: 'Nodes are instances of the Engine participating in a swarm. Swarm mode

    must be enabled for these endpoints to work.

    '
paths:
  /nodes:
    get:
      summary: List nodes
      operationId: NodeList
      responses:
        200:
          description: no error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Node'
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Node'
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: node is not part of a swarm
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: filters
        in: query
        description: 'Filters to process on the nodes list, encoded as JSON (a `map[string][]string`).


          Available filters:

          - `id=<node id>`

          - `label=<engine label>`

          - `membership=`(`accepted`|`pending`)`

          - `name=<node name>`

          - `node.label=<node label>`

          - `role=`(`manager`|`worker`)`

          '
        schema:
          type: string
      tags:
      - Node
  /nodes/{id}:
    get:
      summary: Inspect a node
      operationId: NodeInspect
      responses:
        200:
          description: no error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Node'
            text/plain:
              schema:
                $ref: '#/components/schemas/Node'
        404:
          description: no such node
          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'
        503:
          description: node is not part of a swarm
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: id
        in: path
        description: The ID or name of the node
        required: true
        schema:
          type: string
      tags:
      - Node
    delete:
      summary: Delete a node
      operationId: NodeDelete
      responses:
        200:
          description: no error
        404:
          description: no such node
          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'
        503:
          description: node is not part of a swarm
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: id
        in: path
        description: The ID or name of the node
        required: true
        schema:
          type: string
      - name: force
        in: query
        description: Force remove a node from the swarm
        schema:
          type: boolean
          default: false
      tags:
      - Node
  /nodes/{id}/update:
    post:
      summary: Update a node
      operationId: NodeUpdate
      responses:
        200:
          description: no error
        400:
          description: bad parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        404:
          description: no such node
          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'
        503:
          description: node is not part of a swarm
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: id
        in: path
        description: The ID of the node
        required: true
        schema:
          type: string
      - name: version
        in: query
        description: 'The version number of the node object being updated. This is required

          to avoid conflicting writes.

          '
        required: true
        schema:
          type: integer
          format: int64
      tags:
      - Node
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NodeSpec'
          text/plain:
            schema:
              $ref: '#/components/schemas/NodeSpec'
components:
  schemas:
    ResourceObject:
      description: 'An object describing the resources which can be advertised by a node and

        requested by a task.

        '
      type: object
      properties:
        NanoCPUs:
          type: integer
          format: int64
          example: 4000000000
        MemoryBytes:
          type: integer
          format: int64
          example: 8272408576
        GenericResources:
          $ref: '#/components/schemas/GenericResources'
    ManagerStatus:
      description: 'ManagerStatus represents the status of a manager.


        It provides the current status of a node''s manager component, if the node

        is a manager.

        '
      type:
      - object
      - 'null'
      properties:
        Leader:
          type: boolean
          default: false
          example: true
        Reachability:
          $ref: '#/components/schemas/Reachability'
        Addr:
          description: 'The IP address and port at which the manager is reachable.

            '
          type: string
          example: 10.0.0.46:2377
    TLSInfo:
      description: 'Information about the issuer of leaf TLS certificates and the trusted root

        CA certificate.

        '
      type: object
      properties:
        TrustRoot:
          description: 'The root CA certificate(s) that are used to validate leaf TLS

            certificates.

            '
          type: string
        CertIssuerSubject:
          description: The base64-url-safe-encoded raw subject bytes of the issuer.
          type: string
        CertIssuerPublicKey:
          description: 'The base64-url-safe-encoded raw public key bytes of the issuer.

            '
          type: string
      example:
        TrustRoot: '-----BEGIN CERTIFICATE-----

          MIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw

          EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0

          MzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH

          A0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf

          3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB

          Af8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO

          PQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz

          pxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H

          -----END CERTIFICATE-----

          '
        CertIssuerSubject: MBMxETAPBgNVBAMTCHN3YXJtLWNh
        CertIssuerPublicKey: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A==
    Platform:
      description: 'Platform represents the platform (Arch/OS).

        '
      type: object
      properties:
        Architecture:
          description: 'Architecture represents the hardware architecture (for example,

            `x86_64`).

            '
          type: string
          example: x86_64
        OS:
          description: 'OS represents the Operating System (for example, `linux` or `windows`).

            '
          type: string
          example: linux
    ErrorResponse:
      description: Represents an error.
      type: object
      required:
      - message
      properties:
        message:
          description: The error message.
          type: string
      example:
        message: Something went wrong.
    ObjectVersion:
      description: 'The version number of the object such as node, service, etc. This is needed

        to avoid conflicting writes. The client must send the version number along

        with the modified specification when updating these objects.


        This approach ensures safe concurrency and determinism in that the change

        on the object may not be applied if the version number has changed from the

        last read. In other words, if two update requests specify the same base

        version, only one of the requests can succeed. As a result, two separate

        update requests that happen at the same time will not unintentionally

        overwrite each other.

        '
      type: object
      properties:
        Index:
          type: integer
          format: uint64
          example: 373531
    NodeState:
      description: NodeState represents the state of a node.
      type: string
      enum:
      - unknown
      - down
      - ready
      - disconnected
      example: ready
    NodeStatus:
      description: 'NodeStatus represents the status of a node.


        It provides the current status of the node, as seen by the manager.

        '
      type: object
      properties:
        State:
          $ref: '#/components/schemas/NodeState'
        Message:
          type: string
          example: ''
        Addr:
          description: IP address of the node.
          type: string
          example: 172.17.0.2
    NodeDescription:
      description: 'NodeDescription encapsulates the properties of the Node as reported by the

        agent.

        '
      type: object
      properties:
        Hostname:
          type: string
          example: bf3067039e47
        Platform:
          $ref: '#/components/schemas/Platform'
        Resources:
          $ref: '#/components/schemas/ResourceObject'
        Engine:
          $ref: '#/components/schemas/EngineDescription'
        TLSInfo:
          $ref: '#/components/schemas/TLSInfo'
    Reachability:
      description: Reachability represents the reachability of a node.
      type: string
      enum:
      - unknown
      - unreachable
      - reachable
      example: reachable
    Node:
      type: object
      properties:
        ID:
          type: string
          example: 24ifsmvkjbyhk
        Version:
          $ref: '#/components/schemas/ObjectVersion'
        CreatedAt:
          description: 'Date and time at which the node was added to the swarm in

            [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds.

            '
          type: string
          format: dateTime
          example: '2016-08-18T10:44:24.496525531Z'
        UpdatedAt:
          description: 'Date and time at which the node was last updated in

            [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds.

            '
          type: string
          format: dateTime
          example: '2017-08-09T07:09:37.632105588Z'
        Spec:
          $ref: '#/components/schemas/NodeSpec'
        Description:
          $ref: '#/components/schemas/NodeDescription'
        Status:
          $ref: '#/components/schemas/NodeStatus'
        ManagerStatus:
          $ref: '#/components/schemas/ManagerStatus'
    NodeSpec:
      type: object
      properties:
        Name:
          description: Name for the node.
          type: string
          example: my-node
        Labels:
          description: User-defined key/value metadata.
          type: object
          additionalProperties:
            type: string
        Role:
          description: Role of the node.
          type: string
          enum:
          - worker
          - manager
          example: manager
        Availability:
          description: Availability of the node.
          type: string
          enum:
          - active
          - pause
          - drain
          example: active
      example:
        Availability: active
        Name: node-name
        Role: manager
        Labels:
          foo: bar
    GenericResources:
      description: 'User-defined resources can be either Integer resources (e.g, `SSD=3`) or

        String resources (e.g, `GPU=UUID1`).

        '
      type: array
      items:
        type: object
        properties:
          NamedResourceSpec:
            type: object
            properties:
              Kind:
                type: string
              Value:
                type: string
          DiscreteResourceSpec:
            type: object
            properties:
              Kind:
                type: string
              Value:
                type: integer
                format: int64
      example:
      - DiscreteResourceSpec:
          Kind: SSD
          Value: 3
      - NamedResourceSpec:
          Kind: GPU
          Value: UUID1
      - NamedResourceSpec:
          Kind: GPU
          Value: UUID2
    EngineDescription:
      description: EngineDescription provides information about an engine.
      type: object
      properties:
        EngineVersion:
          type: string
          example: 17.06.0
        Labels:
          type: object
          additionalProperties:
            type: string
          example:
            foo: bar
        Plugins:
          type: array
          items:
            type: object
            properties:
              Type:
                type: string
              Name:
                type: string
          example:
          - Type: Log
            Name: awslogs
          - Type: Log
            Name: fluentd
          - Type: Log
            Name: gcplogs
          - Type: Log
            Name: gelf
          - Type: Log
            Name: journald
          - Type: Log
            Name: json-file
          - Type: Log
            Name: splunk
          - Type: Log
            Name: syslog
          - Type: Network
            Name: bridge
          - Type: Network
            Name: host
          - Type: Network
            Name: ipvlan
          - Type: Network
            Name: macvlan
          - Type: Network
            Name: 'null'
          - Type: Network
            Name: overlay
          - Type: Volume
            Name: local
          - Type: Volume
            Name: localhost:5000/vieux/sshfs:latest
          - Type: Volume
            Name: vieux/sshfs:latest