Docker Service API

openapi: 3.2.0
info:
  title: Docker Engine Config Service 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: Service
  x-displayName: Services
  description: 'Services are the definitions of tasks to run on a swarm. Swarm mode must

    be enabled for these endpoints to work.

    '
paths:
  /services:
    get:
      summary: List services
      operationId: ServiceList
      responses:
        200:
          description: no error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
        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: 'A JSON encoded value of the filters (a `map[string][]string`) to

          process on the services list.


          Available filters:


          - `id=<service id>`

          - `label=<service label>`

          - `mode=["replicated"|"global"]`

          - `name=<service name>`

          '
        schema:
          type: string
      - name: status
        in: query
        description: 'Include service status, with count of running and desired tasks.

          '
        schema:
          type: boolean
      tags:
      - Service
  /services/create:
    post:
      summary: Create a service
      operationId: ServiceCreate
      responses:
        201:
          description: no error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceCreateResponse'
        400:
          description: bad parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        403:
          description: network is not eligible for services
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        409:
          description: name conflicts with an existing service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: node is not part of a swarm
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: X-Registry-Auth
        in: header
        description: 'A base64url-encoded auth configuration for pulling from private

          registries.


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

          details.

          '
        schema:
          type: string
      tags:
      - Service
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ServiceSpec'
              - type: object
                example:
                  Name: web
                  TaskTemplate:
                    ContainerSpec:
                      Image: nginx:alpine
                      Mounts:
                      - ReadOnly: true
                        Source: web-data
                        Target: /usr/share/nginx/html
                        Type: volume
                        VolumeOptions:
                          DriverConfig: {}
                          Labels:
                            com.example.something: something-value
                      Hosts:
                      - 10.10.10.10 host1
                      - ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2
                      User: '33'
                      DNSConfig:
                        Nameservers:
                        - 8.8.8.8
                        Search:
                        - example.org
                        Options:
                        - timeout:3
                      Secrets:
                      - File:
                          Name: www.example.org.key
                          UID: '33'
                          GID: '33'
                          Mode: 384
                        SecretID: fpjqlhnwb19zds35k8wn80lq9
                        SecretName: example_org_domain_key
                      OomScoreAdj: 0
                    LogDriver:
                      Name: json-file
                      Options:
                        max-file: '3'
                        max-size: 10M
                    Placement: {}
                    Resources:
                      Limits:
                        MemoryBytes: 104857600
                      Reservations: {}
                    RestartPolicy:
                      Condition: on-failure
                      Delay: 10000000000
                      MaxAttempts: 10
                  Mode:
                    Replicated:
                      Replicas: 4
                  UpdateConfig:
                    Parallelism: 2
                    Delay: 1000000000
                    FailureAction: pause
                    Monitor: 15000000000
                    MaxFailureRatio: 0.15
                  RollbackConfig:
                    Parallelism: 1
                    Delay: 1000000000
                    FailureAction: pause
                    Monitor: 15000000000
                    MaxFailureRatio: 0.15
                  EndpointSpec:
                    Ports:
                    - Protocol: tcp
                      PublishedPort: 8080
                      TargetPort: 80
                  Labels:
                    foo: bar
        required: true
  /services/{id}:
    get:
      summary: Inspect a service
      operationId: ServiceInspect
      responses:
        200:
          description: no error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
            text/plain:
              schema:
                $ref: '#/components/schemas/Service'
        404:
          description: no such service
          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: ID or name of service.
        required: true
        schema:
          type: string
      - name: insertDefaults
        in: query
        description: Fill empty fields with default values.
        schema:
          type: boolean
          default: false
      tags:
      - Service
    delete:
      summary: Delete a service
      operationId: ServiceDelete
      responses:
        200:
          description: no error
        404:
          description: no such service
          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: ID or name of service.
        required: true
        schema:
          type: string
      tags:
      - Service
  /services/{id}/update:
    post:
      summary: Update a service
      operationId: ServiceUpdate
      responses:
        200:
          description: no error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUpdateResponse'
        400:
          description: bad parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        404:
          description: no such service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: node is not part of a swarm
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: id
        in: path
        description: ID or name of service.
        required: true
        schema:
          type: string
      - name: version
        in: query
        description: 'The version number of the service object being updated. This is

          required to avoid conflicting writes.

          This version number should be the value as currently set on the

          service *before* the update. You can find the current version by

          calling `GET /services/{id}`

          '
        required: true
        schema:
          type: integer
      - name: registryAuthFrom
        in: query
        description: 'If the `X-Registry-Auth` header is not specified, this parameter

          indicates where to find registry authorization credentials.

          '
        schema:
          type: string
          enum:
          - spec
          - previous-spec
          default: spec
      - name: rollback
        in: query
        description: 'Set to this parameter to `previous` to cause a server-side rollback

          to the previous service spec. The supplied spec will be ignored in

          this case.

          '
        schema:
          type: string
      - name: X-Registry-Auth
        in: header
        description: 'A base64url-encoded auth configuration for pulling from private

          registries.


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

          details.

          '
        schema:
          type: string
      tags:
      - Service
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ServiceSpec'
              - type: object
                example:
                  Name: top
                  TaskTemplate:
                    ContainerSpec:
                      Image: busybox
                      Args:
                      - top
                      OomScoreAdj: 0
                    Resources:
                      Limits: {}
                      Reservations: {}
                    RestartPolicy:
                      Condition: any
                      MaxAttempts: 0
                    Placement: {}
                    ForceUpdate: 0
                  Mode:
                    Replicated:
                      Replicas: 1
                  UpdateConfig:
                    Parallelism: 2
                    Delay: 1000000000
                    FailureAction: pause
                    Monitor: 15000000000
                    MaxFailureRatio: 0.15
                  RollbackConfig:
                    Parallelism: 1
                    Delay: 1000000000
                    FailureAction: pause
                    Monitor: 15000000000
                    MaxFailureRatio: 0.15
                  EndpointSpec:
                    Mode: vip
        required: true
  /services/{id}/logs:
    get:
      summary: Get service logs
      description: 'Get `stdout` and `stderr` logs from a service. See also

        [`/containers/{id}/logs`](#operation/ContainerLogs).


        **Note**: This endpoint works only for services with the `local`,

        `json-file` or `journald` logging drivers.

        '
      operationId: ServiceLogs
      responses:
        200:
          description: logs returned as a stream in response body
          content:
            application/vnd.docker.raw-stream:
              schema:
                type: string
                format: binary
            application/vnd.docker.multiplexed-stream:
              schema:
                type: string
                format: binary
        404:
          description: no such service
          content:
            application/vnd.docker.raw-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/vnd.docker.multiplexed-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/vnd.docker.raw-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/vnd.docker.multiplexed-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: node is not part of a swarm
          content:
            application/vnd.docker.raw-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/vnd.docker.multiplexed-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: id
        in: path
        required: true
        description: ID or name of the service
        schema:
          type: string
      - name: details
        in: query
        description: Show service context and extra details provided to logs.
        schema:
          type: boolean
          default: false
      - name: follow
        in: query
        description: Keep connection after returning logs.
        schema:
          type: boolean
          default: false
      - name: stdout
        in: query
        description: Return logs from `stdout`
        schema:
          type: boolean
          default: false
      - name: stderr
        in: query
        description: Return logs from `stderr`
        schema:
          type: boolean
          default: false
      - name: since
        in: query
        description: Only return logs since this time, as a UNIX timestamp
        schema:
          type: integer
          default: 0
      - name: timestamps
        in: query
        description: Add timestamps to every log line
        schema:
          type: boolean
          default: false
      - name: tail
        in: query
        description: 'Only return this number of log lines from the end of the logs.

          Specify as an integer or `all` to output all log lines.

          '
        schema:
          type: string
          default: all
      tags:
      - Service
components:
  schemas:
    EndpointPortConfig:
      type: object
      properties:
        Name:
          type: string
        Protocol:
          type: string
          enum:
          - tcp
          - udp
          - sctp
        TargetPort:
          description: The port inside the container.
          type: integer
        PublishedPort:
          description: The port on the swarm hosts.
          type: integer
        PublishMode:
          description: "The mode in which port is published.\n\n<p><br /></p>\n\n- \"ingress\" makes the target port accessible on every node,\n  regardless of whether there is a task for the service running on\n  that node or not.\n- \"host\" bypasses the routing mesh and publish the port directly on\n  the swarm node where that service is running.\n"
          type: string
          enum:
          - ingress
          - host
          default: ingress
          example: ingress
    ServiceSpec:
      description: User modifiable configuration for a service.
      type: object
      properties:
        Name:
          description: Name of the service.
          type: string
        Labels:
          description: User-defined key/value metadata.
          type: object
          additionalProperties:
            type: string
        TaskTemplate:
          $ref: '#/components/schemas/TaskSpec'
        Mode:
          description: Scheduling mode for the service.
          type: object
          properties:
            Replicated:
              type: object
              properties:
                Replicas:
                  type: integer
                  format: int64
            Global:
              type: object
            ReplicatedJob:
              description: 'The mode used for services with a finite number of tasks that run

                to a completed state.

                '
              type: object
              properties:
                MaxConcurrent:
                  description: 'The maximum number of replicas to run simultaneously.

                    '
                  type: integer
                  format: int64
                  default: 1
                TotalCompletions:
                  description: 'The total number of replicas desired to reach the Completed

                    state. If unset, will default to the value of `MaxConcurrent`

                    '
                  type: integer
                  format: int64
            GlobalJob:
              description: 'The mode used for services which run a task to the completed state

                on each valid node.

                '
              type: object
        UpdateConfig:
          description: Specification for the update strategy of the service.
          type: object
          properties:
            Parallelism:
              description: 'Maximum number of tasks to be updated in one iteration (0 means

                unlimited parallelism).

                '
              type: integer
              format: int64
            Delay:
              description: Amount of time between updates, in nanoseconds.
              type: integer
              format: int64
            FailureAction:
              description: 'Action to take if an updated task fails to run, or stops running

                during the update.

                '
              type: string
              enum:
              - continue
              - pause
              - rollback
            Monitor:
              description: 'Amount of time to monitor each updated task for failures, in

                nanoseconds.

                '
              type: integer
              format: int64
            MaxFailureRatio:
              description: 'The fraction of tasks that may fail during an update before the

                failure action is invoked, specified as a floating point number

                between 0 and 1.

                '
              type: number
              default: 0
            Order:
              description: 'The order of operations when rolling out an updated task. Either

                the old task is shut down before the new task is started, or the

                new task is started before the old task is shut down.

                '
              type: string
              enum:
              - stop-first
              - start-first
        RollbackConfig:
          description: Specification for the rollback strategy of the service.
          type: object
          properties:
            Parallelism:
              description: 'Maximum number of tasks to be rolled back in one iteration (0 means

                unlimited parallelism).

                '
              type: integer
              format: int64
            Delay:
              description: 'Amount of time between rollback iterations, in nanoseconds.

                '
              type: integer
              format: int64
            FailureAction:
              description: 'Action to take if an rolled back task fails to run, or stops

                running during the rollback.

                '
              type: string
              enum:
              - continue
              - pause
            Monitor:
              description: 'Amount of time to monitor each rolled back task for failures, in

                nanoseconds.

                '
              type: integer
              format: int64
            MaxFailureRatio:
              description: 'The fraction of tasks that may fail during a rollback before the

                failure action is invoked, specified as a floating point number

                between 0 and 1.

                '
              type: number
              default: 0
            Order:
              description: 'The order of operations when rolling back a task. Either the old

                task is shut down before the new task is started, or the new task

                is started before the old task is shut down.

                '
              type: string
              enum:
              - stop-first
              - start-first
        Networks:
          description: 'Specifies which networks the service should attach to.


            Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead.

            '
          type: array
          items:
            $ref: '#/components/schemas/NetworkAttachmentConfig'
        EndpointSpec:
          $ref: '#/components/schemas/EndpointSpec'
    Limit:
      description: 'An object describing a limit on resources which can be requested by a task.

        '
      type: object
      properties:
        NanoCPUs:
          type: integer
          format: int64
          example: 4000000000
        MemoryBytes:
          type: integer
          format: int64
          example: 8272408576
        Pids:
          description: 'Limits the maximum number of PIDs in the container. Set `0` for unlimited.

            '
          type: integer
          format: int64
          default: 0
          example: 100
    Mount:
      type: object
      properties:
        Target:
          description: Container path.
          type: string
        Source:
          description: 'Mount source (e.g. a volume name, a host path). The source cannot be

            specified when using `Type=tmpfs`. For `Type=bind`, the source path

            must either exist, or the `CreateMountpoint` must be set to `true` to

            create the source path on the host if missing.


            For `Type=npipe`, the pipe must exist prior to creating the container.'
          type: string
        Type:
          description: 'The mount type. Available types:


            - `bind` Mounts a file or directory from the host into the container. The `Source` must exist prior to creating the container.

            - `cluster` a Swarm cluster volume

            - `image` Mounts an image.

            - `npipe` Mounts a named pipe from the host into the container. The `Source` must exist prior to creating the container.

            - `tmpfs` Create a tmpfs with the given options. The mount `Source` cannot be specified for tmpfs.

            - `volume` Creates a volume with the given name and options (or uses a pre-existing volume with the same name and options). These are **not** removed when the container is removed.

            '
          allOf:
          - $ref: '#/components/schemas/MountType'
        ReadOnly:
          description: Whether the mount should be read-only.
          type: boolean
        Consistency:
          description: 'The consistency requirement for the mount: `default`, `consistent`, `cached`, or `delegated`.'
          type: string
        BindOptions:
          description: Optional configuration for the `bind` type.
          type: object
          properties:
            Propagation:
              description: A propagation mode with the value `[r]private`, `[r]shared`, or `[r]slave`.
              type: string
              enum:
              - private
              - rprivate
              - shared
              - rshared
              - slave
              - rslave
            NonRecursive:
              description: Disable recursive bind mount.
              type: boolean
              default: false
            CreateMountpoint:
              description: Create mount point on host if missing
              type: boolean
              default: false
            ReadOnlyNonRecursive:
              description: 'Make the mount non-recursively read-only, but still leave the mount recursive

                (unless NonRecursive is set to `true` in conjunction).


                Added in v1.44, before that version all read-only mounts were

                non-recursive by default. To match the previous behaviour this

                will default to `true` for clients on versions prior to v1.44.

                '
              type: boolean
              default: false
            ReadOnlyForceRecursive:
              description: Raise an error if the mount cannot be made recursively read-only.
              type: boolean
              default: false
        VolumeOptions:
          description: Optional configuration for the `volume` type.
          type: object
          properties:
            NoCopy:
              description: Populate volume with data from the target.
              type: boolean
              default: false
            Labels:
              description: User-defined key/value metadata.
              type: object
              additionalProperties:
                type: string
            DriverConfig:
              description: Map of driver specific options
              type: object
              properties:
                Name:
                  description: Name of the driver to use to create the volume.
                  type: string
                Options:
                  description: key/value map of driver specific options.
                  type: object
                  additionalProperties:
                    type: string
            Subpath:
              description: Source path inside the volume. Must be relative without any back traversals.
              type: string
              example: dir-inside-volume/subdirectory
        ImageOptions:
          description: Optional configuration for the `image` type.
          type: object
          properties:
            Subpath:
              description: Source path inside the image. Must be relative without any back traversals.
              type: string
              example: dir-inside-image/subdirectory
        TmpfsOptions:
          description: Optional configuration for the `tmpfs` type.
          type: object
          properties:
            SizeBytes:
              description: The size for the tmpfs mount in bytes.
              type: integer
              format: int64
            Mode:
              description: 'The permission mode for the tmpfs mount in an integer.

                The value must not be in octal format (e.g. 755) but rather

                the decimal representation of the octal value (e.g. 493).

                '
              type: integer
            Options:
              description: 'The options to be passed to the tmpfs mount. An array of arrays.

                Flag options should be provided as 1-length arrays. Other types

                should be provided as as 2-length arrays, where the first item is

                the key and the second the value.

                '
              type: array
              items:
                type: array
                minItems: 1
                maxItems: 2
                items:
                  type: string
              example:
              - - noexec
    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
    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
  

# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docker/refs/heads/main/openapi/docker-service-api-openapi.yml