Docker Node API

swagger: '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"
basePath: /v1.54
schemes:
- http
- https
consumes:
- application/json
- text/plain
produces:
- application/json
- text/plain
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
          schema:
            type: array
            items:
              $ref: '#/definitions/Node'
        500:
          description: server error
          schema:
            $ref: '#/definitions/ErrorResponse'
        503:
          description: node is not part of a swarm
          schema:
            $ref: '#/definitions/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`)`

          '
        type: string
      tags:
      - Node
  /nodes/{id}:
    get:
      summary: Inspect a node
      operationId: NodeInspect
      responses:
        200:
          description: no error
          schema:
            $ref: '#/definitions/Node'
        404:
          description: no such node
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: server error
          schema:
            $ref: '#/definitions/ErrorResponse'
        503:
          description: node is not part of a swarm
          schema:
            $ref: '#/definitions/ErrorResponse'
      parameters:
      - name: id
        in: path
        description: The ID or name of the node
        type: string
        required: true
      tags:
      - Node
    delete:
      summary: Delete a node
      operationId: NodeDelete
      responses:
        200:
          description: no error
        404:
          description: no such node
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: server error
          schema:
            $ref: '#/definitions/ErrorResponse'
        503:
          description: node is not part of a swarm
          schema:
            $ref: '#/definitions/ErrorResponse'
      parameters:
      - name: id
        in: path
        description: The ID or name of the node
        type: string
        required: true
      - name: force
        in: query
        description: Force remove a node from the swarm
        default: false
        type: boolean
      tags:
      - Node
  /nodes/{id}/update:
    post:
      summary: Update a node
      operationId: NodeUpdate
      responses:
        200:
          description: no error
        400:
          description: bad parameter
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: no such node
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: server error
          schema:
            $ref: '#/definitions/ErrorResponse'
        503:
          description: node is not part of a swarm
          schema:
            $ref: '#/definitions/ErrorResponse'
      parameters:
      - name: id
        in: path
        description: The ID of the node
        type: string
        required: true
      - name: body
        in: body
        schema:
          $ref: '#/definitions/NodeSpec'
      - name: version
        in: query
        description: 'The version number of the node object being updated. This is required

          to avoid conflicting writes.

          '
        type: integer
        format: int64
        required: true
      tags:
      - Node
definitions:
  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
  NodeDescription:
    description: 'NodeDescription encapsulates the properties of the Node as reported by the

      agent.

      '
    type: object
    properties:
      Hostname:
        type: string
        example: bf3067039e47
      Platform:
        $ref: '#/definitions/Platform'
      Resources:
        $ref: '#/definitions/ResourceObject'
      Engine:
        $ref: '#/definitions/EngineDescription'
      TLSInfo:
        $ref: '#/definitions/TLSInfo'
  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
  NodeState:
    description: NodeState represents the state of a node.
    type: string
    enum:
    - unknown
    - down
    - ready
    - disconnected
    example: ready
  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: '#/definitions/GenericResources'
  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
  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
  Reachability:
    description: Reachability represents the reachability of a node.
    type: string
    enum:
    - unknown
    - unreachable
    - reachable
    example: reachable
  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
  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==
  Node:
    type: object
    properties:
      ID:
        type: string
        example: 24ifsmvkjbyhk
      Version:
        $ref: '#/definitions/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: '#/definitions/NodeSpec'
      Description:
        $ref: '#/definitions/NodeDescription'
      Status:
        $ref: '#/definitions/NodeStatus'
      ManagerStatus:
        $ref: '#/definitions/ManagerStatus'
  ErrorResponse:
    description: Represents an error.
    type: object
    required:
    - message
    properties:
      message:
        description: The error message.
        type: string
        x-nullable: false
    example:
      message: Something went wrong.
  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.

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

          '
        type: string
        example: 10.0.0.46:2377
  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: '#/definitions/NodeState'
      Message:
        type: string
        example: ''
      Addr:
        description: IP address of the node.
        type: string
        example: 172.17.0.2